/**

* Mutate a `MdAst` at an OcPath. Returns a new AST with the

* value replaced; the original is unchanged.

* Mutate `MdAst` at an OcPath. Returns a new AST; original unchanged.

*

* Writable surface:

* oc://FILE/[frontmatter]/key → frontmatter value

* oc://FILE/section/item/field → item.kv.value

*

* oc://FILE/[frontmatter]/key → frontmatter entry value

* oc://FILE/section/item/field → item.kv.value (when item has kv shape)

*

* Section bodies, tables, and code blocks are NOT writable through

* this primitive — they're prose, and a generic "set" doesn't compose

* cleanly. Doctor fixers handle structural edits via dedicated verbs.

* Section bodies aren't writable through this primitive.

*

* @module @openclaw/oc-path/edit

*/

readonly reason: "unresolved" | "not-writable" | "no-item-kv";

};

/**

* Replace the value at `path` with `newValue`. The new AST has fresh

* `raw` re-rendered from the structural fields.

*

* Sentinel guard at the substrate boundary — `setJsoncOcPath` and the

* jsonl `finalize`-via-render path both reject sentinel-bearing values

* before they reach the AST. The md path was deferring entirely to

* round-trip echo through `emitMd`, which `acceptPreExistingSentinel`

* by default skips. Closing the gap here keeps F9 (formatter sentinel

* guard) symmetric across all three kinds.

*/

// Sentinel guard at the boundary keeps md symmetric with jsonc/jsonl,

// which both reject sentinel values before they reach the AST.

export function setMdOcPath(ast: MdAst, path: OcPath, newValue: string): MdEditResult {

guardSentinel(newValue, formatOcPath(path));

// Frontmatter address: oc://FILE/[frontmatter]/<key>

if (path.section === "[frontmatter]") {

const key = path.item ?? path.field;

if (key === undefined) {

return { ok: false, reason: "unresolved" };

}

if (key === undefined) return { ok: false, reason: "unresolved" };

const idx = ast.frontmatter.findIndex((e) => e.key === key);

if (idx === -1) {

return { ok: false, reason: "unresolved" };

}

if (idx === -1) return { ok: false, reason: "unresolved" };

const existing = ast.frontmatter[idx];

if (existing === undefined) {

return { ok: false, reason: "unresolved" };

}

if (existing === undefined) return { ok: false, reason: "unresolved" };

const newEntry: FrontmatterEntry = { ...existing, value: newValue };

const newFm = ast.frontmatter.slice();

newFm[idx] = newEntry;

return finalize({ ...ast, frontmatter: newFm });

}

// Item-field address: oc://FILE/section/item/field

if (path.section === undefined || path.item === undefined || path.field === undefined) {

return { ok: false, reason: "not-writable" };

}

const sectionSlug = path.section.toLowerCase();

const blockIdx = ast.blocks.findIndex((b) => b.slug === sectionSlug);

if (blockIdx === -1) {

return { ok: false, reason: "unresolved" };

}

if (blockIdx === -1) return { ok: false, reason: "unresolved" };

const block = ast.blocks[blockIdx];

if (block === undefined) {

return { ok: false, reason: "unresolved" };

}

if (block === undefined) return { ok: false, reason: "unresolved" };

const itemSlug = path.item.toLowerCase();

const itemIdx = block.items.findIndex((i) => i.slug === itemSlug);

if (itemIdx === -1) {

return { ok: false, reason: "unresolved" };

}

if (itemIdx === -1) return { ok: false, reason: "unresolved" };

const item = block.items[itemIdx];

if (item === undefined) {

return { ok: false, reason: "unresolved" };

}

if (item.kv === undefined) {

return { ok: false, reason: "no-item-kv" };

}

if (item === undefined) return { ok: false, reason: "unresolved" };

if (item.kv === undefined) return { ok: false, reason: "no-item-kv" };

if (item.kv.key.toLowerCase() !== path.field.toLowerCase()) {

return { ok: false, reason: "unresolved" };

}

const newItem: AstItem = {

...item,

kv: { key: item.kv.key, value: newValue },

};

const newItem: AstItem = { ...item, kv: { key: item.kv.key, value: newValue } };

const newItems = block.items.slice();

newItems[itemIdx] = newItem;

const newBlock: AstBlock = {

return finalize({ ...ast, blocks: newBlocks });

}

/**

* Rebuild block.bodyText so emit-roundtrip mode reflects the edit. We

* do a minimal in-place substitution on the existing bodyText: find

* each `- key: value` line for a touched item and rewrite the value.

*

* For items without a matching bullet line, we leave bodyText alone

* (the structural fields take precedence in render mode anyway).

*/

// In-place substitution on `bodyText` so round-trip emit reflects the

// edit. Items without a matching bullet line are skipped (render mode

// uses structural fields anyway).

function rebuildBlockBody(block: AstBlock, newItems: readonly AstItem[]): string {

let body = block.bodyText;

for (let i = 0; i < newItems.length; i++) {

const newItem = newItems[i];

const oldItem = block.items[i];

if (newItem === undefined || oldItem === undefined) {

continue;

}

if (newItem.kv === undefined || oldItem.kv === undefined) {

continue;

}

if (newItem.kv.value === oldItem.kv.value) {

continue;

}

if (newItem === undefined || oldItem === undefined) continue;

if (newItem.kv === undefined || oldItem.kv === undefined) continue;

if (newItem.kv.value === oldItem.kv.value) continue;

const re = new RegExp(`^(\\s*-\\s*${escapeRegex(oldItem.kv.key)}\\s*:\\s*).*$`, "m");

body = body.replace(re, `$1${newItem.kv.value}`);

}

return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

}

/**

* Re-render `ast.raw` from the (possibly mutated) tree using the same

* shape the round-trip emitter expects.

*/

function finalize(ast: MdAst): MdEditResult {

const parts: string[] = [];

if (ast.frontmatter.length > 0) {

parts.push("---");

}

if (ast.preamble.length > 0) {

if (parts.length > 0) {

parts.push("");

}

if (parts.length > 0) parts.push("");

parts.push(ast.preamble);

}

for (const block of ast.blocks) {

if (parts.length > 0) {

parts.push("");

}

if (parts.length > 0) parts.push("");

parts.push(`## ${block.heading}`);

if (block.bodyText.length > 0) {

parts.push(block.bodyText);

}

if (block.bodyText.length > 0) parts.push(block.bodyText);

}

const raw = parts.join("\n");

return { ok: true, ast: { ...ast, raw } };

return { ok: true, ast: { ...ast, raw: parts.join("\n") } };

}

function formatFrontmatterValue(value: string): string {

if (value.length === 0) {

return '""';

}

if (/[:#&*?|<>=!%@`,[\]{}\r\n]/.test(value)) {

return JSON.stringify(value);

}

if (value.length === 0) return '""';

if (/[:#&*?|<>=!%@`,[\]{}\r\n]/.test(value)) return JSON.stringify(value);

return value;

}