@davidbalzan/groundwork-console 0.1.0

package/dist/seamwrite.js

@@ -0,0 +1,87 @@
+/* v0.2 seam writes — the ONLY way the console changes seam files. Rules:
+   1. parse → render must reproduce the file byte-for-byte BEFORE we touch it (else refuse: hand-edit).
+   2. The change is expressed as seam records and rendered by the seam (renderWorkDoc / upsertFact), never by string surgery on the doc.
+   3. Re-parse after write and assert the record is present.
+   4. Scope check (list_scopes): allowed when the doc is unscoped, or owner ∈ {any, david, human, aide, liaison, curator} — David is the aide's principal. */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseWorkDoc, renderWorkDoc, queueItemsOf, upsertFact, parseFactsDoc } from "@davidbalzan/groundwork-seam";
+const DAVID_MAY = new Set(["any", "david", "human", "aide", "liaison", "curator", "groundwork-console", "kit-console"]);
+export function scopeAllows(scopes, docPath) {
+    const sc = scopes[docPath];
+    if (!sc)
+        return { ok: true, reason: "unscoped (no scopes.json entry)" };
+    if (DAVID_MAY.has(sc.owner.toLowerCase()))
+        return { ok: true, reason: `scope owner ${sc.owner} · ${sc.mode ?? "shared"} — David is the principal` };
+    return { ok: false, reason: `scope owner is ${sc.owner} (${sc.mode ?? "shared"}) — write it through that role` };
+}
+function roundTrips(source) {
+    const doc = parseWorkDoc(source);
+    const back = renderWorkDoc(doc);
+    if (back === source)
+        return { ok: true, doc };
+    const a = source.split("\n"), b = back.split("\n");
+    const at = a.findIndex((l, i) => l !== b[i]);
+    return { ok: false, doc, diffAt: at + 1 };
+}
+/** Append a queue.v1 item under the last `## Queue` block (or the `## Queue` heading if the list is empty). */
+export function addQueueItem(projectPath, item, log) {
+    const file = path.join(projectPath, "docs/QUEUE.md");
+    if (!existsSync(file))
+        throw new Error("docs/QUEUE.md missing — run /kickstart");
+    const src = readFileSync(file, "utf8");
+    const rt = roundTrips(src);
+    if (!rt.ok)
+        throw new Error(`QUEUE.md does not round-trip through the seam (first divergence at line ${rt.diffAt}) — refusing to write; fix the file by hand first`);
+    log("round-trip: byte-identical ✓");
+    const doc = rt.doc;
+    const text = item.text.trim().replace(/\r?\n/g, " ");
+    if (!text)
+        throw new Error("empty item");
+    const newItem = { id: `q-${Date.now().toString(36)}`, priority: item.priority, text, done: false };
+    const lastQueue = [...doc.blocks].reverse().find((b) => b.kind === "queue");
+    if (lastQueue) {
+        lastQueue.items.push(newItem);
+        log(`append to existing queue block (${lastQueue.items.length} items)`);
+    }
+    else {
+        const idx = doc.blocks.findIndex((b) => b.kind === "text" && b.lines.some((l) => /^## Queue\b/.test(l)));
+        if (idx < 0)
+            throw new Error("no `## Queue` section in QUEUE.md");
+        const tb = doc.blocks[idx];
+        const h = tb.lines.findIndex((l) => /^## Queue\b/.test(l));
+        const before = tb.lines.slice(0, h + 1), after = tb.lines.slice(h + 1);
+        // keep a blank line after the heading if the source had one
+        const lead = after[0] === "" ? [""] : [];
+        const rest = after[0] === "" ? after.slice(1) : after;
+        doc.blocks.splice(idx, 1, { kind: "text", lines: [...before, ...lead] }, { kind: "queue", items: [newItem] }, ...(rest.length ? [{ kind: "text", lines: rest }] : []));
+        log("no queue items yet — inserted a queue block under ## Queue");
+    }
+    const out = renderWorkDoc(doc);
+    writeFileSync(file, out);
+    const check = queueItemsOf(parseWorkDoc(readFileSync(file, "utf8"))).some((q) => q.text === text && q.priority === item.priority && !q.done);
+    if (!check)
+        throw new Error("post-write verification failed: item not found after re-parse");
+    log(`wrote docs/QUEUE.md (+1 item, ${out.length - src.length} bytes)`);
+    return { file: "docs/QUEUE.md", line: renderWorkDocLine(newItem), bytesDelta: out.length - src.length };
+}
+const renderWorkDocLine = (q) => `- [ ] (${q.priority}) ${q.text}`;
+/** Re-verify (or add) a fact: seam upsertFact with a fresh timestamp. */
+export function reverifyFact(projectPath, entry, log) {
+    const file = path.join(projectPath, "docs/FACTS.md");
+    if (!existsSync(file))
+        throw new Error("docs/FACTS.md missing — run `groundwork update --docs`");
+    const src = readFileSync(file, "utf8");
+    const parsed = parseFactsDoc(src);
+    const existing = parsed.entries.find((e) => e.id === entry.id);
+    if (!existing && !entry.claim)
+        throw new Error(`fact ${entry.id} not found and no claim given`);
+    const claim = entry.claim ?? existing.claim;
+    const out = upsertFact(src, { id: entry.id, claim, by: entry.by, method: entry.method });
+    writeFileSync(file, out);
+    const after = parseFactsDoc(readFileSync(file, "utf8")).entries.find((e) => e.id === entry.id);
+    if (!after || after.by !== entry.by)
+        throw new Error("post-write verification failed");
+    log(`upsertFact ${entry.id} · verified now · by ${entry.by} · ${entry.method}`);
+    return { file: "docs/FACTS.md", entry: after };
+}