pub enum EditMode {
Overwrite,
Append,
Prepend,
}Expand description
Behavior mode for NbClient::edit_note content updates.
§Vocabulary
The variant previously named Replace is now Overwrite to
remove the vocabulary trap at the root of nb-api:issues/api/6:
callers reading mode: "replace" reasonably expected a
substring-style replacement (analogous to
str::replace), but nb edit --overwrite
is destructive — it replaces every byte of the note body.
Renaming the variant to Overwrite makes the destructive
intent unambiguous at the call site.
The legacy string "replace" is accepted as a serde alias for
backward compatibility with payloads produced before this
rename. The alias is not advertised in the derived
schemars JSON Schema — only the
canonical "overwrite" is exposed to MCP tool consumers.
§Mapping
| Variant | Canonical serialization | nb edit flag(s) | Effect |
|---|---|---|---|
EditMode::Overwrite | "overwrite" | --overwrite --content <content> | Replace every byte of the note body with <content>. Destructive: any existing content is lost. |
EditMode::Append | "append" | --content <content> | Append <content> after the existing note body. |
EditMode::Prepend | "prepend" | --prepend --content <content> | Prepend <content> before the existing note body. |
§Default
EditMode derives Default with EditMode::Overwrite as the
default variant. This is the nb-api default, chosen for
compatibility with the current API contract and the documented
destructive default on nb_api’s edit API. Note that this is
distinct from the nb CLI’s native no-flag behavior (nb edit --content without --overwrite appends; see the mapping
table above). Requiredness on the consumer side (e.g., the
mode field on nb-mcp-server’s EditArgs) is a
consumer-layer concern, not enforced here. Downstream
consumers that want to require mode explicitly should drop
#[serde(default)] from their containing struct.
Variants§
Overwrite
Replace every byte of the note body with the provided
content. Destructive: any existing content is lost. Maps to
nb edit --overwrite --content <content>.
Accepts legacy "replace" as a serde alias for backward
compatibility with payloads produced before the variant
rename. The alias is not advertised in the derived JSON
Schema; only "overwrite" is exposed to schema consumers.
Append
Append the provided content after the existing note body.
Maps to nb edit --content <content> (the nb default
content-mode behavior).
Prepend
Prepend the provided content before the existing note body.
Maps to nb edit --prepend --content <content>.