From 2c359d441b210bc15bf0b6f01c045391c76b16d6 Mon Sep 17 00:00:00 2001 From: Kayshen-X Date: Thu, 14 May 2026 21:35:39 +0800 Subject: [PATCH] docs(mcp/replace): warn that container children are dropped Codex review on e51b979f flagged that the replace_node doc comment didn't mention the destructive behavior on containers. Add an explicit "Destructive on containers" note to both the McpCommand variant and the tool struct, pointing readers at update_node for in-place patches. No behavior change. --- crates/openpencil-shell-core/src/mcp.rs | 6 ++++++ crates/openpencil-shell-core/src/mcp/write_tools.rs | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/crates/openpencil-shell-core/src/mcp.rs b/crates/openpencil-shell-core/src/mcp.rs index ae24a2fd0..1c91c5b3b 100644 --- a/crates/openpencil-shell-core/src/mcp.rs +++ b/crates/openpencil-shell-core/src/mcp.rs @@ -196,6 +196,12 @@ pub enum McpCommand { /// carry children / a full subtree once a JSON Node parser /// lives on the host. The current contract matches what TS /// `replace_node` accepts for primitives, minus children. + /// + /// **Destructive on containers**: replacing a Frame / Group + /// / node-with-children drops every descendant of the old + /// node without warning. Use `update_node` to patch a + /// container in place; reserve `replace_node` for primitive + /// → primitive swaps where the loss is intended. ReplaceNode { node_id: u64, kind: String, diff --git a/crates/openpencil-shell-core/src/mcp/write_tools.rs b/crates/openpencil-shell-core/src/mcp/write_tools.rs index 4d12af52f..fcce37046 100644 --- a/crates/openpencil-shell-core/src/mcp/write_tools.rs +++ b/crates/openpencil-shell-core/src/mcp/write_tools.rs @@ -514,6 +514,12 @@ pub fn copy_node_snapshot() -> CopyNode { /// children of the replacement default to empty). TS-equivalent /// behavior for primitives; subtree-replacement requires a JSON /// Node parser that doesn't live on this side yet. +/// +/// **Destructive on containers**: replacing a Frame / Group / node +/// with children drops every descendant of the old node without +/// warning. Use `update_node` to patch a container in place; +/// reserve `replace_node` for primitive → primitive swaps where +/// the loss is intended. pub struct ReplaceNode; impl McpTool for ReplaceNode {