@dogsbay/commands 0.2.0-beta.101

package/dist/commands/content.js

@@ -0,0 +1,634 @@
+/**
+ * Content verbs — the agent broker's typed alternative to "edit the file"
+ * (plans/agent-broker.md Phase 3): `topic-read`, `topic-set-title`,
+ * `section-replace`, `block-insert`, `block-delete`, `props-get`,
+ * `props-set`.
+ *
+ * All of them are LINE-WISE edits on the shared fence grammar (a `## x`
+ * inside a code example is never structure) with the frontmatter split
+ * off first, so every byte outside the edited span is untouched by
+ * construction — no parse/serialize round-trip that could normalise
+ * directives, tables, or whitespace elsewhere in the file. Every mutation
+ * invalidates the workspace index and reports what changed; what cannot
+ * be done safely (a mid-fence insert, an ambiguous section, deleting the
+ * H1) is refused with an issue, never guessed.
+ */
+import { z } from "zod";
+import { createHash } from "node:crypto";
+import { dump as dumpYaml, load as loadYaml } from "js-yaml";
+import { fenceOpenBefore, slugifyHeadingText } from "@dogsbay/format-dogsbay-md";
+import { normalizeStoragePath } from "../storage.js";
+import { splitFrontmatter } from "../edits.js";
+import { defineCommand } from "../engine.js";
+const fail = (code, message, file, extra = {}) => ({
+    data: { applied: false, ...extra },
+    issues: [{ severity: "error", code, message, ...(file ? { file } : {}) }],
+    summary: message,
+});
+// CommonMark ATX heading: up to 3 leading spaces, optional closing #s, optional {#id}
+const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*(?:\{#([^\s}]+)[^}]*\})?\s*$/;
+const strip = (line) => line.replace(/\r$/, "");
+/** Structure state per body line: code fence (shared grammar) + HTML comment + `:::` container depth. */
+const structureMask = (lines) => {
+    const fence = fenceOpenBefore(lines.join("\n"));
+    const mask = [];
+    let inComment = false;
+    let depth = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = strip(lines[i]);
+        const inFence = fence[i];
+        // state BEFORE this line decides whether it can be a heading
+        mask.push(inFence || inComment || depth > 0);
+        if (inFence)
+            continue;
+        if (!inComment && /^\s*<!--/.test(line) && !/-->/.test(line))
+            inComment = true;
+        else if (inComment && /-->/.test(line))
+            inComment = false;
+        if (inComment)
+            continue;
+        const container = /^ {0,3}(:{3,})\s*(\S.*)?$/.exec(line);
+        if (container) {
+            if (container[2])
+                depth++;
+            else if (depth > 0)
+                depth--;
+        }
+    }
+    return mask;
+};
+const loadDoc = async (ctx, rawFile) => {
+    const file = normalizeStoragePath(rawFile);
+    const { storage } = ctx.workspace;
+    if (!(await storage.exists(file)))
+        return fail("file-missing", `${file} does not exist`, file);
+    if (!file.endsWith(".md"))
+        return fail("not-markdown", `${file} is not a markdown document`, file);
+    const content = await storage.read(file);
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const [frontmatter, body] = splitFrontmatter(content);
+    const lines = body.split("\n");
+    const openBefore = structureMask(lines);
+    const headings = [];
+    const seenSlugs = new Map();
+    lines.forEach((raw, i) => {
+        if (openBefore[i])
+            return;
+        const m = HEADING.exec(strip(raw));
+        if (!m)
+            return;
+        const text = m[2] ?? "";
+        // the site's anchor: an explicit id REPLACES the text slug; text slugs dedupe in document order
+        let slug;
+        if (m[3])
+            slug = m[3];
+        else {
+            const base = slugifyHeadingText(text);
+            const n = seenSlugs.get(base) ?? 0;
+            seenSlugs.set(base, n + 1);
+            slug = n === 0 ? base : `${base}-${n}`;
+        }
+        headings.push({ level: m[1].length, text, ...(m[3] ? { id: m[3] } : {}), slug, line: i });
+    });
+    const sections = headings.map((h, idx) => {
+        let end = lines.length;
+        for (let j = idx + 1; j < headings.length; j++) {
+            if (headings[j].level <= h.level) {
+                end = headings[j].line;
+                break;
+            }
+        }
+        const ownEnd = headings[idx + 1] ? Math.min(end, headings[idx + 1].line) : end;
+        return { ...h, end, ownEnd };
+    });
+    return { file, doc: { frontmatter, body, lines, openBefore, sections, eol } };
+};
+const isOutput = (x) => typeof x === "object" && x !== null && "data" in x;
+/**
+ * Divergence gate (plans/ide-change-review.md §3): a short content hash the
+ * agent gets from `topic-read` and hands back as `expect` on a mutation. If
+ * the target changed in between (a human typing, another agent), the verb
+ * refuses with the current hash instead of writing over the newer text.
+ */
+export const contentHash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
+const sectionHash = (doc, s) => contentHash(doc.lines.slice(s.line, s.end).join("\n"));
+const fileHash = (doc) => contentHash(doc.frontmatter + doc.lines.join("\n"));
+const STALE_PREVIEW_LINES = 40;
+/**
+ * The refusal deliberately does NOT hand back the new hash (an LLM's cheapest
+ * recovery would be to replay it without reading); it shows what the target
+ * looks like NOW so the caller can decide, then re-read.
+ */
+const stale = (file, what, currentText) => {
+    const lines = currentText.split("\n");
+    const preview = lines.slice(0, STALE_PREVIEW_LINES).join("\n") + (lines.length > STALE_PREVIEW_LINES ? `\n… (${lines.length - STALE_PREVIEW_LINES} more lines)` : "");
+    return fail("stale-expect", `${what} changed since it was read; nothing written. Re-read it with topic-read and retry with the new hash.`, file, { currentText: preview });
+};
+/** A gate passes when `expect` matches the target's own hash OR the whole file's (a file-level match is strictly stronger). */
+const gateOk = (expect, doc, section) => expect === undefined || expect === fileHash(doc) || (section !== undefined && expect === sectionHash(doc, section));
+const sectionText = (doc, s) => doc.lines.slice(s.line, s.end).join("\n");
+const EXPECT = z
+    .string()
+    .optional()
+    .describe("Divergence gate: the target's `hash` from topic-read (a section's hash covers its sub-sections; `fileHash` is accepted anywhere); refused with stale-expect if it changed since");
+/** Resolve a section selector: `{#id}` / `#id` / exact heading text / slug. Ambiguity is an error. */
+const findSection = (doc, selector) => {
+    const s = selector.trim();
+    const braced = /^\{#([^\s}]+)\}$/.exec(s);
+    const wantId = braced ? braced[1] : s.startsWith("#") && !s.startsWith("# ") ? s.slice(1) : undefined;
+    let candidates;
+    if (wantId !== undefined) {
+        // an explicit {#id} is authoritative; fall back to the assigned slug only when no id matches
+        candidates = doc.sections.filter((sec) => sec.id === wantId);
+        if (!candidates.length)
+            candidates = doc.sections.filter((sec) => sec.slug === wantId);
+    }
+    else {
+        candidates = doc.sections.filter((sec) => sec.text === s || sec.id === s || sec.slug === s || sec.slug === slugifyHeadingText(s));
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    if (candidates.length === 0) {
+        return {
+            error: fail("section-not-found", `no section matches "${selector}"`, undefined, {
+                sections: doc.sections.map((x) => ({ level: x.level, text: x.text, ...(x.id ? { id: x.id } : {}), slug: x.slug })),
+            }),
+        };
+    }
+    return {
+        error: fail("section-ambiguous", `"${selector}" matches ${candidates.length} sections; use {#id} or a unique heading text`, undefined, { candidates: candidates.map((x) => ({ level: x.level, text: x.text, ...(x.id ? { id: x.id } : {}), line: x.line + 1 })) }),
+    };
+};
+const writeDoc = async (ctx, file, doc, lines) => {
+    // lines carry their own "\r" (CRLF files) — joining on "\n" changes no untouched byte
+    await ctx.workspace.storage.write(file, doc.frontmatter + lines.join("\n"));
+    ctx.workspace.invalidate();
+};
+/** New content, as lines in the DOCUMENT's line ending. */
+const normalizeBlock = (content, eol) => {
+    const text = content.replace(/\r\n/g, "\n").replace(/\n+$/, "");
+    if (text === "")
+        return [];
+    return text.split("\n").map((l) => (eol === "\r\n" ? l + "\r" : l));
+};
+const blank = (eol) => (eol === "\r\n" ? "\r" : "");
+/** Blank-line separated splice: ensures one blank line before/after the block when neighbours are non-blank. */
+const spliceBlock = (lines, at, deleteCount, block, eol) => {
+    const before = lines.slice(0, at);
+    const after = lines.slice(at + deleteCount);
+    const out = [...before];
+    if (block.length) {
+        if (out.length && out[out.length - 1].trim() !== "")
+            out.push(blank(eol));
+        out.push(...block);
+        if (after.length && after[0].trim() !== "")
+            out.push(blank(eol));
+    }
+    out.push(...after);
+    return out;
+};
+/** The YAML between the frontmatter fences (handles the empty `---\n---\n` block). */
+const frontmatterInner = (frontmatter) => frontmatter.replace(/^---[^\n]*\r?\n/, "").replace(/(^|\r?\n)---[ \t]*(\r?\n)?$/, "");
+const parseFrontmatterObject = (frontmatter) => {
+    if (!frontmatter)
+        return {};
+    const inner = frontmatterInner(frontmatter);
+    if (inner.trim() === "")
+        return {}; // `---\n---\n`: an empty block is valid, not an error
+    try {
+        const parsed = loadYaml(inner);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (err) {
+        return { error: err.message.split("\n")[0] ?? "invalid YAML" };
+    }
+};
+const isFmError = (x) => typeof x.error === "string" && Object.keys(x).length === 1;
+// ─── topic-read ─────────────────────────────────────────────────────────────
+export const topicReadCommand = defineCommand({
+    name: "topic-read",
+    writes: "none",
+    description: "Enriched read of a document: title, frontmatter, section outline (with line ranges and ids), links, includes, key uses, inbound references, directive count — and optionally the body",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        includeBody: z.boolean().default(false).describe("Include the raw body text (frontmatter excluded)"),
+    })
+        .strict(),
+    positionals: ["file"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        const index = await ctx.workspace.index();
+        const entry = index.docs.get(file);
+        const inbound = [];
+        for (const [from, other] of index.docs) {
+            if (from === file)
+                continue;
+            for (const link of other.links)
+                if (link.target === file)
+                    inbound.push({ from, kind: link.kind, raw: link.href });
+            for (const inc of other.includes)
+                if (inc.target === file)
+                    inbound.push({ from, kind: "include", raw: inc.raw });
+        }
+        let directives = 0;
+        const fence = fenceOpenBefore(doc.body);
+        doc.lines.forEach((line, i) => {
+            if (!fence[i] && /^ {0,3}:{3,}\s*[A-Za-z]/.test(strip(line)))
+                directives++;
+        });
+        const outline = doc.sections.map((s) => ({
+            level: s.level,
+            text: s.text,
+            ...(s.id ? { id: s.id } : {}),
+            slug: s.slug,
+            line: s.line + 1,
+            endLine: s.end,
+            /** pass as `expect` to section-replace / block-insert / block-delete; covers this section INCLUDING its sub-sections */
+            hash: sectionHash(doc, s),
+        }));
+        return {
+            data: {
+                file,
+                /** pass as `expect` to topic-set-title / props-set */
+                fileHash: fileHash(doc),
+                title: entry?.title ?? doc.sections.find((s) => s.level === 1)?.text,
+                frontmatter: entry?.frontmatter ?? {},
+                outline,
+                anchors: entry?.anchors ?? [],
+                links: entry?.links ?? [],
+                includes: entry?.includes ?? [],
+                keyUses: entry?.keyUses ?? [],
+                inbound,
+                directives,
+                lineCount: doc.lines.length,
+                ...(input.includeBody ? { body: doc.body } : {}),
+                ...(entry?.parseError ? { parseError: entry.parseError } : {}),
+            },
+            summary: `${file}: ${outline.length} section(s), ${inbound.length} inbound reference(s), ${directives} directive block(s)`,
+        };
+    },
+});
+// ─── topic-set-title ────────────────────────────────────────────────────────
+export const topicSetTitleCommand = defineCommand({
+    name: "topic-set-title",
+    writes: "content",
+    description: "Replace the document's H1 heading text (keeps its {#id}); warns when frontmatter `title:` now differs",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        title: z.string().min(1).describe("New heading text (no leading #)"),
+        expect: EXPECT,
+    })
+        .strict(),
+    positionals: ["file", "title"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        if (!gateOk(input.expect, doc))
+            return stale(file, file, doc.frontmatter + doc.body);
+        const h1 = doc.sections.find((s) => s.level === 1);
+        if (!h1)
+            return fail("title-missing", `${file} has no level-1 heading to retitle`, file);
+        if (/[\r\n]/.test(input.title))
+            return fail("title-multiline", "a title is one line", file);
+        const title = input.title.trim().replace(/^#+\s*/, "").replace(/\s+#+$/, "").trim();
+        if (!title)
+            return fail("title-empty", "the title is empty after stripping #", file);
+        if (/\{#[^}]*\}/.test(title))
+            return fail("title-has-id", "put the id on the heading with props, not in the title text (the existing {#id} is kept)", file);
+        const issues = [];
+        const fm = parseFrontmatterObject(doc.frontmatter);
+        if (isFmError(fm))
+            issues.push({ severity: "warning", code: "frontmatter-invalid", message: `frontmatter is not valid YAML (${fm.error}); left untouched`, file });
+        else if (typeof fm.title === "string" && fm.title !== title) {
+            issues.push({ severity: "warning", code: "title-frontmatter-differs", message: `frontmatter title is "${fm.title}"; use props-set to align it`, file });
+        }
+        const lines = [...doc.lines];
+        lines[h1.line] = `# ${title}${h1.id ? ` {#${h1.id}}` : ""}${doc.eol === "\r\n" ? "\r" : ""}`;
+        await writeDoc(ctx, file, doc, lines);
+        return {
+            data: { applied: true, file, from: h1.text, to: title, line: h1.line + 1 },
+            issues,
+            summary: `${file}: "${h1.text}" → "${title}"`,
+        };
+    },
+});
+// ─── section-replace ────────────────────────────────────────────────────────
+export const sectionReplaceCommand = defineCommand({
+    name: "section-replace",
+    writes: "content",
+    description: "Replace the content of one section (everything under its heading up to the next heading of the same or higher level; for the H1, its own preamble before the first sub-heading); the heading line itself is kept unless keepHeading=false",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        section: z.string().min(1).describe("Section selector: {#id}, heading text, or slug"),
+        body: z.string().describe("New section content (markdown; may be empty)"),
+        keepHeading: z.boolean().default(true).describe("Keep the heading line (default) or replace it too"),
+        expect: EXPECT,
+    })
+        .strict(),
+    positionals: ["file", "section"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        const found = findSection(doc, input.section);
+        if ("error" in found)
+            return { ...found.error, issues: found.error.issues.map((i) => ({ ...i, file })) };
+        if (!gateOk(input.expect, doc, found))
+            return stale(file, `section "${found.text}"`, sectionText(doc, found));
+        const block = normalizeBlock(input.body, doc.eol);
+        if (!input.keepHeading && block.length === 0) {
+            return fail("section-replace-empty", "replacing the heading with an empty body would delete the section; use block-delete", file);
+        }
+        if (!input.keepHeading && found.level === 1 && !/^# /.test(strip(block[0]))) {
+            return fail("section-replace-h1", "replacing the H1 line requires the new body to start with an H1 (`# Title`)", file);
+        }
+        const start = input.keepHeading ? found.line + 1 : found.line;
+        // The H1 "section" is the whole document; replacing it means its own
+        // preamble (its sub-sections are addressable on their own).
+        // preserve one trailing blank line separation with the next section
+        let end = found.level === 1 ? found.ownEnd : found.end;
+        while (end > start && doc.lines[end - 1].trim() === "")
+            end--;
+        const removed = doc.lines.slice(start, end);
+        const lines = spliceBlock(doc.lines, start, end - start, block, doc.eol);
+        await writeDoc(ctx, file, doc, lines);
+        return {
+            data: { applied: true, file, section: { level: found.level, text: found.text, ...(found.id ? { id: found.id } : {}) }, removedLines: removed.length, insertedLines: block.length },
+            summary: `${file}: replaced section "${found.text}" (${removed.length} → ${block.length} lines)`,
+        };
+    },
+});
+// ─── block-insert ───────────────────────────────────────────────────────────
+export const blockInsertCommand = defineCommand({
+    name: "block-insert",
+    writes: "content",
+    description: "Insert a markdown block into a document: at the start or end of a section, or before a 1-based line. Refuses to insert inside a code fence",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        content: z.string().min(1).describe("Markdown to insert"),
+        section: z.string().optional().describe("Section selector ({#id}, heading text, slug); default: end of document"),
+        position: z.enum(["start", "end"]).default("end").describe("Within the section (or document): after the heading, or before the next section"),
+        line: z.number().int().min(1).optional().describe("Insert before this 1-based BODY line instead (overrides section/position)"),
+        expect: EXPECT,
+    })
+        .strict(),
+    positionals: ["file"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        // The gate follows the WRITE TARGET: a `line` insert (which overrides section/position)
+        // or no section ⇒ the whole file; a section insert ⇒ that section (or the file).
+        if (input.line !== undefined || !input.section) {
+            if (!gateOk(input.expect, doc))
+                return stale(file, file, doc.frontmatter + doc.body);
+        }
+        const block = normalizeBlock(input.content, doc.eol);
+        let at;
+        let where;
+        if (input.line !== undefined) {
+            at = Math.min(input.line - 1, doc.lines.length);
+            where = `line ${input.line}`;
+        }
+        else if (input.section) {
+            const found = findSection(doc, input.section);
+            if ("error" in found)
+                return { ...found.error, issues: found.error.issues.map((i) => ({ ...i, file })) };
+            if (!gateOk(input.expect, doc, found))
+                return stale(file, `section "${found.text}"`, sectionText(doc, found));
+            if (input.position === "start") {
+                at = found.line + 1;
+            }
+            else {
+                // "end of the H1" = end of its own preamble (end of DOCUMENT is the no-section default)
+                at = found.level === 1 ? found.ownEnd : found.end;
+                while (at > found.line + 1 && doc.lines[at - 1].trim() === "")
+                    at--;
+            }
+            where = `${input.position} of "${found.text}"`;
+        }
+        else if (input.position === "start") {
+            const h1 = doc.sections.find((s) => s.level === 1);
+            at = h1 ? h1.line + 1 : 0;
+            where = "start of document";
+        }
+        else {
+            at = doc.lines.length;
+            while (at > 0 && doc.lines[at - 1].trim() === "")
+                at--;
+            where = "end of document";
+        }
+        if (doc.openBefore[at])
+            return fail("insert-inside-fence", `line ${at + 1} is inside a code fence, HTML comment or ::: container; choose another position`, file);
+        const lines = spliceBlock(doc.lines, at, 0, block, doc.eol);
+        if (lines.length && lines[lines.length - 1].trim() !== "")
+            lines.push(blank(doc.eol));
+        await writeDoc(ctx, file, doc, lines);
+        return {
+            data: { applied: true, file, at: at + 1, insertedLines: block.length, where },
+            summary: `${file}: inserted ${block.length} line(s) at ${where}`,
+        };
+    },
+});
+// ─── block-delete ───────────────────────────────────────────────────────────
+export const blockDeleteCommand = defineCommand({
+    name: "block-delete",
+    writes: "content",
+    description: "Delete a whole section (heading + content up to the next heading of the same or higher level). Refuses the H1 (use safe-delete for the document); warns about inbound anchor links",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        section: z.string().min(1).describe("Section selector: {#id}, heading text, or slug"),
+        expect: EXPECT,
+    })
+        .strict(),
+    positionals: ["file", "section"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        const found = findSection(doc, input.section);
+        if ("error" in found)
+            return { ...found.error, issues: found.error.issues.map((i) => ({ ...i, file })) };
+        if (!gateOk(input.expect, doc, found))
+            return stale(file, `section "${found.text}"`, sectionText(doc, found));
+        if (found.level === 1)
+            return fail("delete-h1-refused", "the H1 section is the document; use safe-delete to remove the file", file);
+        const issues = [];
+        const index = await ctx.workspace.index();
+        // `slug` IS the assigned anchor (explicit id, else the deduped text slug); sub-sections go too
+        const anchors = new Set();
+        for (const s of doc.sections)
+            if (s.line >= found.line && s.line < found.end)
+                anchors.add(s.slug);
+        for (const [from, other] of index.docs) {
+            for (const link of other.links) {
+                if (link.target !== file || !link.fragment)
+                    continue;
+                if (anchors.has(link.fragment)) {
+                    issues.push({ severity: "warning", code: "inbound-anchor-orphaned", message: `${from} links to #${link.fragment}, which this delete removes`, file: from });
+                }
+            }
+        }
+        const end = found.end;
+        const lines = [...doc.lines.slice(0, found.line), ...doc.lines.slice(end)];
+        await writeDoc(ctx, file, doc, lines);
+        return {
+            data: { applied: true, file, section: { level: found.level, text: found.text, ...(found.id ? { id: found.id } : {}) }, removedLines: end - found.line, orphanedInbound: issues.length },
+            issues,
+            summary: `${file}: deleted section "${found.text}" (${end - found.line} lines)${issues.length ? `, ${issues.length} inbound anchor link(s) now orphaned` : ""}`,
+        };
+    },
+});
+// ─── props-get / props-set ──────────────────────────────────────────────────
+export const propsGetCommand = defineCommand({
+    name: "props-get",
+    writes: "none",
+    description: "Read a document's frontmatter properties as an object",
+    input: z.object({ file: z.string().min(1).describe("Workspace-relative .md path") }).strict(),
+    positionals: ["file"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        const props = parseFrontmatterObject(doc.frontmatter);
+        if (isFmError(props))
+            return fail("frontmatter-invalid", `frontmatter is not valid YAML: ${props.error}`, file);
+        return { data: { file, props, hasFrontmatter: doc.frontmatter !== "" }, summary: `${file}: ${Object.keys(props).length} propert${Object.keys(props).length === 1 ? "y" : "ies"}` };
+    },
+});
+const jsonScalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const jsonValue = z.lazy(() => z.union([jsonScalar, z.array(jsonValue), z.record(z.string(), jsonValue)]));
+export const propsSetCommand = defineCommand({
+    name: "props-set",
+    writes: "content",
+    description: "Set and/or unset top-level frontmatter properties. Existing keys are rewritten in place (only their own lines change), new keys are appended, frontmatter is created when absent",
+    input: z
+        .object({
+        file: z.string().min(1).describe("Workspace-relative .md path"),
+        set: z.record(z.string().min(1), jsonValue).default({}).describe("Properties to set (JSON values; nested values are written as YAML)"),
+        unset: z.array(z.string().min(1)).default([]).describe("Top-level property names to remove"),
+        expect: EXPECT,
+    })
+        .strict(),
+    positionals: ["file"],
+    async run(ctx, input) {
+        const loaded = await loadDoc(ctx, input.file);
+        if (isOutput(loaded))
+            return loaded;
+        const { file, doc } = loaded;
+        if (!gateOk(input.expect, doc))
+            return stale(file, file, doc.frontmatter + doc.body);
+        if (!Object.keys(input.set).length && !input.unset.length)
+            return fail("props-noop", "nothing to set or unset", file);
+        for (const key of [...Object.keys(input.set), ...input.unset]) {
+            if (!/^[A-Za-z_][\w.-]*$/.test(key))
+                return fail("props-bad-key", `"${key}" is not a plain top-level key`, file);
+        }
+        // refuse to line-edit YAML we cannot re-parse (and never write into a broken block)
+        const existing = parseFrontmatterObject(doc.frontmatter);
+        if (isFmError(existing))
+            return fail("frontmatter-invalid", `frontmatter is not valid YAML: ${existing.error}`, file);
+        // the frontmatter's OWN line ending (may differ from the body's)
+        const eol = doc.frontmatter ? (doc.frontmatter.includes("\r\n") ? "\r\n" : "\n") : doc.eol;
+        // Existing frontmatter lines (without the fences)
+        let fmLines = [];
+        if (doc.frontmatter) {
+            const inner = frontmatterInner(doc.frontmatter);
+            fmLines = inner === "" ? [] : inner.split(/\r?\n/);
+        }
+        const isTop = (line) => /^[A-Za-z_][\w.-]*\s*:/.test(line);
+        const keyOf = (line) => line.slice(0, line.indexOf(":")).trim();
+        // a top-level key's span ends at the next column-0 line that is not a list item or comment
+        const endsSpan = (line) => /^\S/.test(line) && !/^#/.test(line) && !/^-(\s|$)/.test(line);
+        /**
+         * [start, end) line span of a top-level key including its indented/continuation lines.
+         * TRAILING comments and blank lines are NOT part of it: they belong to whatever comes
+         * next, and swallowing them deleted a writer's comment on every rewrite.
+         */
+        const spanOf = (key) => {
+            for (let i = 0; i < fmLines.length; i++) {
+                if (isTop(fmLines[i]) && keyOf(fmLines[i]) === key) {
+                    let j = i + 1;
+                    while (j < fmLines.length && !endsSpan(fmLines[j]))
+                        j++;
+                    while (j > i + 1 && (fmLines[j - 1].trim() === "" || fmLines[j - 1].trimStart().startsWith("#")))
+                        j--;
+                    return [i, j];
+                }
+            }
+            return undefined;
+        };
+        /** A same-line trailing comment on a scalar key line, to re-append after the new value. */
+        const trailingComment = (line) => {
+            const value = line.slice(line.indexOf(":") + 1);
+            // only outside quotes: `title: "a # b"` has no comment
+            let quote = null;
+            for (let i = 0; i < value.length; i++) {
+                const ch = value[i];
+                if (quote) {
+                    if (ch === quote && value[i - 1] !== "\\")
+                        quote = null;
+                    continue;
+                }
+                if (ch === '"' || ch === "'") {
+                    quote = ch;
+                    continue;
+                }
+                if (ch === "#" && (i === 0 || /\s/.test(value[i - 1])))
+                    return value.slice(i ? i - 1 : 0);
+            }
+            return "";
+        };
+        const changed = [];
+        const removed = [];
+        for (const key of input.unset) {
+            const span = spanOf(key);
+            if (!span)
+                continue;
+            fmLines.splice(span[0], span[1] - span[0]);
+            removed.push(key);
+        }
+        for (const [key, value] of Object.entries(input.set)) {
+            const dumped = dumpYaml({ [key]: value }, { lineWidth: 100, noRefs: true }).replace(/\n$/, "").split("\n");
+            const span = spanOf(key);
+            // a `key: value   # note` keeps its note when the new value is a single line
+            if (span && dumped.length === 1) {
+                const note = trailingComment(fmLines[span[0]]);
+                if (note)
+                    dumped[0] += note;
+            }
+            if (span)
+                fmLines.splice(span[0], span[1] - span[0], ...dumped);
+            else
+                fmLines.push(...dumped);
+            changed.push(key);
+        }
+        let frontmatter = "";
+        if (fmLines.length)
+            frontmatter = `---${eol}${fmLines.join(eol)}${eol}---${eol}`;
+        const reparsed = parseFrontmatterObject(frontmatter);
+        if (isFmError(reparsed))
+            return fail("frontmatter-invalid", `the edit would produce invalid YAML (${reparsed.error}); nothing written`, file);
+        await ctx.workspace.storage.write(file, frontmatter + doc.lines.join("\n"));
+        ctx.workspace.invalidate([file]); // this file only: the rest of the index is still good
+        return {
+            data: { applied: true, file, set: changed, unset: removed, props: reparsed },
+            summary: `${file}: set ${changed.length}, unset ${removed.length} propert${changed.length + removed.length === 1 ? "y" : "ies"}`,
+        };
+    },
+});
+//# sourceMappingURL=content.js.map