@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/commands/adopt/render.js

@@ -0,0 +1,268 @@
+/**
+ * The brief as a person reads it.
+ *
+ * A module of its own because the brief is the one loam output an agent is
+ * expected to FOLLOW rather than parse: `--json` carries the same eight targets,
+ * and this decides only how they read. The wrapping matters for that reason —
+ * a continuation line indented past its marker cannot be misread as a second
+ * bullet, which is what a hand-followed checklist gets wrong first.
+ */
+import { SEVERITY_MARK } from "../../core/vocabulary/report.js";
+import {} from "../../core/brief/brief.js";
+import { VIA_ALL } from "../../core/brief/checks.js";
+/* ------------------------------------------------------------------ */
+/* Text                                                                */
+/* ------------------------------------------------------------------ */
+/**
+ * `full` is the `--targets` pointer — the sentence naming the run that carries
+ * the invariant half of the brief. Its PRESENCE is what narrows this view, so
+ * the two views cannot disagree about what `--targets` means: exactly the
+ * sections `--targets` omits from `--json` are the sections skipped here.
+ * `undefined` is the default brief, unchanged byte for byte.
+ */
+export function render(b, warnings, full) {
+    console.log(`adopt ${b.service} — write the baseline into ${b.path}/\n`);
+    // In the header, before the work: a warning printed after eight artifact
+    // shapes is a warning read after the agent has started writing.
+    for (const w of warnings) {
+        console.log(wrap(`! ${w}`, "  "));
+        console.log("");
+    }
+    if (full === undefined) {
+        // First, above even the never-overwrite rule, because the rule is an
+        // instruction and this is the answer to "what am I looking at": measured on
+        // the example fleet, this view is over 650 lines and 5,600 words to an
+        // unpaged terminal, and the two rows that actually orient a person —
+        // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line
+        // 450, behind four hundred lines of prose. `--json` is explicitly the agent
+        // contract, so nothing was served by leaving the human view unintroduced.
+        // `--targets` skips it — bullet three describes sections that view omits,
+        // and that view has its own pointer for the same job.
+        printOrientation(b);
+        console.log(wrap(b.rule, "  "));
+        // Before the artifact table, because the table is the output and this is the
+        // input: an agent that meets the file list first starts writing files.
+        printWalk(b);
+    }
+    console.log("\n  artifacts\n");
+    // The legend again, next to the thing it decodes. A reader who scrolls back
+    // to the table two hundred lines later arrives at four flags and no key, and
+    // the capital/lowercase distinction is invisible to anyone who has to
+    // remember it rather than read it.
+    console.log(wrap(LEGEND_LINE, "    "));
+    console.log("");
+    const width = Math.max(...b.targets.map((t) => t.artifact.length));
+    for (const t of b.targets) {
+        // `edit` is the shared fleet map: the file exists, but "present" would read
+        // as "nothing to do here", which is the opposite of why it is on the list.
+        const flag = t.action === "edit" ? "UNDRAWN" : t.exists ? "present" : t.required ? "MISSING" : "missing";
+        console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);
+    }
+    for (const t of b.targets)
+        printShape(t);
+    printLandscape(b);
+    if (full === undefined)
+        printChecking(b);
+    else {
+        // The pointer takes the place of the sections it stands for, in the same
+        // position they would have occupied. Anywhere else — a footnote under the
+        // closing instructions, say — and it reads as a cross-reference rather
+        // than as the notice that this brief is not all of the brief.
+        console.log("\n  the rest of the brief\n");
+        console.log(wrap(full, "    "));
+    }
+    console.log("\n  when you are done\n");
+    console.log(`    loam validate --service ${b.service} --json    # fix every error`);
+    // The fleet run is not a nicety: --service never reports the landscape
+    // cross-check, so a baseline can pass the line above with the fleet map
+    // never edited at all.
+    console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);
+    console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);
+    console.log("");
+    console.log(wrap("Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.", "    "));
+}
+/** The table's four flags, compressed to one terminal line for the scroll-back reader. */
+const LEGEND_LINE = "MISSING required · missing optional · present diff it · UNDRAWN add to the map";
+/**
+ * A required target whose work is still outstanding.
+ *
+ * `!t.exists` alone is the wrong test, and the fleet map is the reason: for
+ * every repo after its first service `architecture/landscape.likec4` already
+ * exists, so `exists` is true while nothing in it resolves to this boundary —
+ * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.
+ * `action` carries that distinction and nothing else does: `edit` is only ever
+ * the undrawn fleet map (see `BriefTarget.action`, core/brief/targets.ts).
+ */
+function outstanding(t) {
+    return t.required && (!t.exists || t.action === "edit");
+}
+/**
+ * The three sentences that make the rest of the page readable: how much of it
+ * is owed, what the table's own convention means, and what the four hundred
+ * lines below it are.
+ *
+ * Every number here is computed from the brief that was just assembled — the
+ * outstanding count off `targets`, the section sizes off `walk`, `checks` and
+ * `unchecked`. A literal would be right until the next check is added and
+ * silently wrong forever after, and this block's whole value is that a reader
+ * can trust it instead of scrolling to verify it.
+ */
+function printOrientation(b) {
+    const owed = b.targets.filter(outstanding);
+    console.log("  read this first\n");
+    // What is actually owed, named. The count is the load-bearing half: "some of
+    // these are required" is a sentence a reader skips, "three of the nine, and
+    // here they are" is one they act on.
+    console.log(bullet(owed.length === 0
+        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`
+        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? "is" : "are"} required and not yet done: ${owed.map((t) => t.artifact).join(", ")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`, "    "));
+    console.log("");
+    // The legend, in full. The table prints `MISSING` and `missing` as if the
+    // capitals were emphasis; they are the required/optional distinction, and
+    // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the
+    // one row that is not this boundary's file at all.
+    console.log(bullet("The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `UNDRAWN` marks the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error).", "    "));
+    console.log("");
+    // What the rest of the page is, so a reader who stops here still knows what
+    // they scrolled past — and where the same content lives for an agent, which
+    // is the reader this long body was written for.
+    console.log(bullet(`The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \`loam adopt --service ${b.service} --json\` carries the same targets for an agent, and \`--targets\` narrows that to only the part that varies by boundary.`, "    "));
+    console.log("");
+}
+/**
+ * The invariant half: the frontmatter rules, the checks that run, and the
+ * checks that do not exist. A function of its own only so `--targets` can skip
+ * all three in one place — the three sections are the exact set `--targets`
+ * omits from `--json`, and splitting them here is what keeps that a single
+ * decision instead of three that can drift apart.
+ */
+function printChecking(b) {
+    console.log("\n  frontmatter — on every markdown artifact\n");
+    for (const [field, what] of Object.entries(b.frontmatter.fields)) {
+        console.log(`    ${field}`);
+        console.log(wrap(what, "      "));
+    }
+    console.log(`\n    never write by hand: ${b.frontmatter.never.join(", ")}`);
+    console.log(`\n${wrap(b.frontmatter.why, "    ")}`);
+    // Attribution matters here: the fleet cross-check runs under `--all`, and a
+    // header promising it to `--service` sent agents chasing a finding that
+    // invocation never reports.
+    console.log(`\n  what \`loam validate --service ${b.service}\` then checks\n`);
+    for (const c of b.checks) {
+        if (c.via !== VIA_ALL)
+            printCheck(c);
+    }
+    console.log(`\n  and what only \`loam validate --all\` surfaces\n`);
+    for (const c of b.checks) {
+        if (c.via === VIA_ALL)
+            printCheck(c);
+    }
+    console.log("\n  what nothing checks\n");
+    for (const u of b.unchecked)
+        console.log(bullet(u, "    "));
+}
+/**
+ * The walk, numbered. The numbers are the point: an unordered list of nine
+ * places to look reads as nine optional suggestions, and the two stops that fix
+ * what the service IS have to happen before the surfaces are enumerated.
+ */
+function printWalk(b) {
+    console.log("\n  read the code in this order — nothing below is written from anything else\n");
+    for (const [i, stop] of b.walk.entries()) {
+        // The hang is explicit rather than derived: `wrap` infers one from a leading
+        // `- `, and a numbered stop whose second line starts at the number's own
+        // column reads as the next stop — which for a list whose ORDER is the point
+        // is the one misreading that costs something.
+        console.log(wrap(`${String(i + 1)}. ${stop.where}`, "    ", 88, "       "));
+        // Two more columns than the stop it belongs to: where-to-look and
+        // what-to-take are different sentences, and at one indent the second reads
+        // as a continuation of the first.
+        console.log(wrap(stop.find, "         "));
+        console.log(`         → ${stop.lands.join(", ")}`);
+        console.log("");
+    }
+    console.log(wrap(b.walkClose, "    "));
+}
+function printCheck(c) {
+    console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);
+    console.log(wrap(c.what, "        "));
+}
+const ACTION_NOTE = {
+    create: "",
+    diff: "   (exists — diff, do not replace)",
+    edit: "   (the whole fleet's file — ADD to it, never rewrite it)",
+};
+function printShape(t) {
+    console.log(`\n  ${t.path}${ACTION_NOTE[t.action]}\n`);
+    for (const rule of t.shape)
+        console.log(bullet(rule, "    "));
+    if (t.example === undefined)
+        return;
+    console.log("");
+    for (const line of t.example.trimEnd().split("\n"))
+        console.log(`      ${line}`.trimEnd());
+}
+function printLandscape(b) {
+    const l = b.landscape;
+    console.log("\n  what the fleet already says about this service\n");
+    // The instruction is the same sentence the JSON carries, printed from the
+    // same field — the text view and `--json` cannot drift into briefing two
+    // different writes.
+    if (!l.present) {
+        console.log("    architecture/landscape.likec4 does not exist yet — nothing to bind to.");
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        return;
+    }
+    if (!l.parses) {
+        console.log("    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.");
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        return;
+    }
+    if (l.elements.length === 0) {
+        console.log(`    Nothing in the landscape models '${b.service}'.`);
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        return;
+    }
+    for (const e of l.elements) {
+        const bound = e.bound ? "bound" : "matched by title — bind it";
+        console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);
+    }
+    for (const e of l.inbound)
+        console.log(`    ← ${e.from}  ${e.op ?? `"${e.title ?? ""}"`}`);
+    for (const e of l.outbound)
+        console.log(`    → ${e.to}  ${e.op ?? `"${e.title ?? ""}"`}`);
+    if (l.expects.length > 0) {
+        console.log("");
+        console.log(wrap(`openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(", ")} — the fleet already calls ${l.expects.length === 1 ? "it" : "them"}, and a contract that omits ${l.expects.length === 1 ? "it" : "them"} fails spine.op-undefined the moment it lands.`, "    "));
+    }
+}
+/**
+ * Wrap prose so the brief is readable in a terminal. Continuation lines are
+ * indented past the marker, so a wrapped bullet cannot be misread as two.
+ */
+function wrap(text, indent, width = 88, hangIndent) {
+    const hang = hangIndent ?? (/^\s*-\s/.test(text) ? `${indent}  ` : indent);
+    const out = [];
+    let line = indent;
+    let pad = indent;
+    for (const word of text.trim().split(/\s+/)) {
+        if (line.length > pad.length && line.length + 1 + word.length > width) {
+            out.push(line);
+            pad = hang;
+            line = hang + word;
+        }
+        else {
+            line = line.length > pad.length ? `${line} ${word}` : line + word;
+        }
+    }
+    out.push(line);
+    return out.join("\n");
+}
+/** A bullet, wrapped with its continuation lines hanging under the text. */
+function bullet(text, indent) {
+    return wrap(`- ${text}`, indent);
+}
+//# sourceMappingURL=render.js.map

package/dist/commands/adopt/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/adopt/render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The brief as a person reads it.\n *\n * A module of its own because the brief is the one loam output an agent is\n * expected to FOLLOW rather than parse: `--json` carries the same eight targets,\n * and this decides only how they read. The wrapping matters for that reason —\n * a continuation line indented past its marker cannot be misread as a second\n * bullet, which is what a hand-followed checklist gets wrong first.\n */\nimport { SEVERITY_MARK } from \"../../core/vocabulary/report.js\";\nimport { type Brief } from \"../../core/brief/brief.js\";\nimport { VIA_ALL, type BriefCheck } from \"../../core/brief/checks.js\";\nimport type { BriefTarget } from \"../../core/brief/targets.js\";\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * `full` is the `--targets` pointer — the sentence naming the run that carries\n * the invariant half of the brief. Its PRESENCE is what narrows this view, so\n * the two views cannot disagree about what `--targets` means: exactly the\n * sections `--targets` omits from `--json` are the sections skipped here.\n * `undefined` is the default brief, unchanged byte for byte.\n */\nexport function render(b: Brief, warnings: string[], full?: string): void {\n  console.log(`adopt ${b.service} — write the baseline into ${b.path}/\\n`);\n  // In the header, before the work: a warning printed after eight artifact\n  // shapes is a warning read after the agent has started writing.\n  for (const w of warnings) {\n    console.log(wrap(`! ${w}`, \"  \"));\n    console.log(\"\");\n  }\n  if (full === undefined) {\n    // First, above even the never-overwrite rule, because the rule is an\n    // instruction and this is the answer to \"what am I looking at\": measured on\n    // the example fleet, this view is over 650 lines and 5,600 words to an\n    // unpaged terminal, and the two rows that actually orient a person —\n    // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line\n    // 450, behind four hundred lines of prose. `--json` is explicitly the agent\n    // contract, so nothing was served by leaving the human view unintroduced.\n    // `--targets` skips it — bullet three describes sections that view omits,\n    // and that view has its own pointer for the same job.\n    printOrientation(b);\n    console.log(wrap(b.rule, \"  \"));\n\n    // Before the artifact table, because the table is the output and this is the\n    // input: an agent that meets the file list first starts writing files.\n    printWalk(b);\n  }\n\n  console.log(\"\\n  artifacts\\n\");\n  // The legend again, next to the thing it decodes. A reader who scrolls back\n  // to the table two hundred lines later arrives at four flags and no key, and\n  // the capital/lowercase distinction is invisible to anyone who has to\n  // remember it rather than read it.\n  console.log(wrap(LEGEND_LINE, \"    \"));\n  console.log(\"\");\n  const width = Math.max(...b.targets.map((t) => t.artifact.length));\n  for (const t of b.targets) {\n    // `edit` is the shared fleet map: the file exists, but \"present\" would read\n    // as \"nothing to do here\", which is the opposite of why it is on the list.\n    const flag = t.action === \"edit\" ? \"UNDRAWN\" : t.exists ? \"present\" : t.required ? \"MISSING\" : \"missing\";\n    console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);\n  }\n\n  for (const t of b.targets) printShape(t);\n\n  printLandscape(b);\n\n  if (full === undefined) printChecking(b);\n  else {\n    // The pointer takes the place of the sections it stands for, in the same\n    // position they would have occupied. Anywhere else — a footnote under the\n    // closing instructions, say — and it reads as a cross-reference rather\n    // than as the notice that this brief is not all of the brief.\n    console.log(\"\\n  the rest of the brief\\n\");\n    console.log(wrap(full, \"    \"));\n  }\n\n  console.log(\"\\n  when you are done\\n\");\n  console.log(`    loam validate --service ${b.service} --json    # fix every error`);\n  // The fleet run is not a nicety: --service never reports the landscape\n  // cross-check, so a baseline can pass the line above with the fleet map\n  // never edited at all.\n  console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);\n  console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);\n  console.log(\"\");\n  console.log(\n    wrap(\n      \"Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.\",\n      \"    \",\n    ),\n  );\n}\n\n/** The table's four flags, compressed to one terminal line for the scroll-back reader. */\nconst LEGEND_LINE = \"MISSING required · missing optional · present diff it · UNDRAWN add to the map\";\n\n/**\n * A required target whose work is still outstanding.\n *\n * `!t.exists` alone is the wrong test, and the fleet map is the reason: for\n * every repo after its first service `architecture/landscape.likec4` already\n * exists, so `exists` is true while nothing in it resolves to this boundary —\n * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.\n * `action` carries that distinction and nothing else does: `edit` is only ever\n * the undrawn fleet map (see `BriefTarget.action`, core/brief/targets.ts).\n */\nfunction outstanding(t: BriefTarget): boolean {\n  return t.required && (!t.exists || t.action === \"edit\");\n}\n\n/**\n * The three sentences that make the rest of the page readable: how much of it\n * is owed, what the table's own convention means, and what the four hundred\n * lines below it are.\n *\n * Every number here is computed from the brief that was just assembled — the\n * outstanding count off `targets`, the section sizes off `walk`, `checks` and\n * `unchecked`. A literal would be right until the next check is added and\n * silently wrong forever after, and this block's whole value is that a reader\n * can trust it instead of scrolling to verify it.\n */\nfunction printOrientation(b: Brief): void {\n  const owed = b.targets.filter(outstanding);\n  console.log(\"  read this first\\n\");\n\n  // What is actually owed, named. The count is the load-bearing half: \"some of\n  // these are required\" is a sentence a reader skips, \"three of the nine, and\n  // here they are\" is one they act on.\n  console.log(\n    bullet(\n      owed.length === 0\n        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`\n        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? \"is\" : \"are\"} required and not yet done: ${owed.map((t) => t.artifact).join(\", \")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // The legend, in full. The table prints `MISSING` and `missing` as if the\n  // capitals were emphasis; they are the required/optional distinction, and\n  // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the\n  // one row that is not this boundary's file at all.\n  console.log(\n    bullet(\n      \"The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `UNDRAWN` marks the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error).\",\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // What the rest of the page is, so a reader who stops here still knows what\n  // they scrolled past — and where the same content lives for an agent, which\n  // is the reader this long body was written for.\n  console.log(\n    bullet(\n      `The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \\`loam adopt --service ${b.service} --json\\` carries the same targets for an agent, and \\`--targets\\` narrows that to only the part that varies by boundary.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n}\n\n/**\n * The invariant half: the frontmatter rules, the checks that run, and the\n * checks that do not exist. A function of its own only so `--targets` can skip\n * all three in one place — the three sections are the exact set `--targets`\n * omits from `--json`, and splitting them here is what keeps that a single\n * decision instead of three that can drift apart.\n */\nfunction printChecking(b: Brief): void {\n  console.log(\"\\n  frontmatter — on every markdown artifact\\n\");\n  for (const [field, what] of Object.entries(b.frontmatter.fields)) {\n    console.log(`    ${field}`);\n    console.log(wrap(what, \"      \"));\n  }\n  console.log(`\\n    never write by hand: ${b.frontmatter.never.join(\", \")}`);\n  console.log(`\\n${wrap(b.frontmatter.why, \"    \")}`);\n\n  // Attribution matters here: the fleet cross-check runs under `--all`, and a\n  // header promising it to `--service` sent agents chasing a finding that\n  // invocation never reports.\n  console.log(`\\n  what \\`loam validate --service ${b.service}\\` then checks\\n`);\n  for (const c of b.checks) {\n    if (c.via !== VIA_ALL) printCheck(c);\n  }\n  console.log(`\\n  and what only \\`loam validate --all\\` surfaces\\n`);\n  for (const c of b.checks) {\n    if (c.via === VIA_ALL) printCheck(c);\n  }\n\n  console.log(\"\\n  what nothing checks\\n\");\n  for (const u of b.unchecked) console.log(bullet(u, \"    \"));\n}\n\n/**\n * The walk, numbered. The numbers are the point: an unordered list of nine\n * places to look reads as nine optional suggestions, and the two stops that fix\n * what the service IS have to happen before the surfaces are enumerated.\n */\nfunction printWalk(b: Brief): void {\n  console.log(\"\\n  read the code in this order — nothing below is written from anything else\\n\");\n  for (const [i, stop] of b.walk.entries()) {\n    // The hang is explicit rather than derived: `wrap` infers one from a leading\n    // `- `, and a numbered stop whose second line starts at the number's own\n    // column reads as the next stop — which for a list whose ORDER is the point\n    // is the one misreading that costs something.\n    console.log(wrap(`${String(i + 1)}. ${stop.where}`, \"    \", 88, \"       \"));\n    // Two more columns than the stop it belongs to: where-to-look and\n    // what-to-take are different sentences, and at one indent the second reads\n    // as a continuation of the first.\n    console.log(wrap(stop.find, \"         \"));\n    console.log(`         → ${stop.lands.join(\", \")}`);\n    console.log(\"\");\n  }\n  console.log(wrap(b.walkClose, \"    \"));\n}\n\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);\n  console.log(wrap(c.what, \"        \"));\n}\n\nconst ACTION_NOTE: Record<BriefTarget[\"action\"], string> = {\n  create: \"\",\n  diff: \"   (exists — diff, do not replace)\",\n  edit: \"   (the whole fleet's file — ADD to it, never rewrite it)\",\n};\n\nfunction printShape(t: BriefTarget): void {\n  console.log(`\\n  ${t.path}${ACTION_NOTE[t.action]}\\n`);\n  for (const rule of t.shape) console.log(bullet(rule, \"    \"));\n  if (t.example === undefined) return;\n  console.log(\"\");\n  for (const line of t.example.trimEnd().split(\"\\n\")) console.log(`      ${line}`.trimEnd());\n}\n\nfunction printLandscape(b: Brief): void {\n  const l = b.landscape;\n  console.log(\"\\n  what the fleet already says about this service\\n\");\n  // The instruction is the same sentence the JSON carries, printed from the\n  // same field — the text view and `--json` cannot drift into briefing two\n  // different writes.\n  if (!l.present) {\n    console.log(\"    architecture/landscape.likec4 does not exist yet — nothing to bind to.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (!l.parses) {\n    console.log(\"    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (l.elements.length === 0) {\n    console.log(`    Nothing in the landscape models '${b.service}'.`);\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  for (const e of l.elements) {\n    const bound = e.bound ? \"bound\" : \"matched by title — bind it\";\n    console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);\n  }\n  for (const e of l.inbound) console.log(`    ← ${e.from}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  for (const e of l.outbound) console.log(`    → ${e.to}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  if (l.expects.length > 0) {\n    console.log(\"\");\n    console.log(\n      wrap(\n        `openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(\", \")} — the fleet already calls ${l.expects.length === 1 ? \"it\" : \"them\"}, and a contract that omits ${l.expects.length === 1 ? \"it\" : \"them\"} fails spine.op-undefined the moment it lands.`,\n        \"    \",\n      ),\n    );\n  }\n}\n\n/**\n * Wrap prose so the brief is readable in a terminal. Continuation lines are\n * indented past the marker, so a wrapped bullet cannot be misread as two.\n */\nfunction wrap(text: string, indent: string, width = 88, hangIndent?: string): string {\n  const hang = hangIndent ?? (/^\\s*-\\s/.test(text) ? `${indent}  ` : indent);\n  const out: string[] = [];\n  let line = indent;\n  let pad = indent;\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line.length > pad.length && line.length + 1 + word.length > width) {\n      out.push(line);\n      pad = hang;\n      line = hang + word;\n    } else {\n      line = line.length > pad.length ? `${line} ${word}` : line + word;\n    }\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n\n/** A bullet, wrapped with its continuation lines hanging under the text. */\nfunction bullet(text: string, indent: string): string {\n  return wrap(`- ${text}`, indent);\n}\n"]}

package/dist/commands/archive/archive.js

@@ -0,0 +1,77 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { fail, reportNoConfig } from "../../core/envelope/json.js";
+import { message } from "../../core/staging/commit.js";
+import { acquireDocsLock, DocsBusyError } from "../../core/staging/lock.js";
+import { ArchiveFailure } from "./plan/refusal.js";
+import { archiveLocked } from "./run.js";
+import { LandscapeSpliceError } from "../../core/c4/splice/contract.js";
+import { NotUtf8Error } from "../../core/staging/writes.js";
+import { OpenapiMergeError } from "../../core/openapi/merge/error.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+function archiveErrorCode(err) {
+    if (err instanceof ArchiveFailure)
+        return err.code;
+    // Every splice refusal is the mechanical merge answer — see the class.
+    if (err instanceof LandscapeSpliceError)
+        return "merge-failed";
+    if (err instanceof NotUtf8Error)
+        return "merge-failed";
+    // The merge branch wraps its own call and re-throws as merge-failed; the
+    // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable
+    // feature contract answered merge-failed or `internal` depending on whether
+    // the service already had a living openapi.yaml. The code answers "can I
+    // trust the repo?", and that answer does not turn on which side of the merge
+    // the document sat on.
+    if (err instanceof OpenapiMergeError)
+        return "merge-failed";
+    if (err instanceof InterruptedCommitError)
+        return "commit-interrupted";
+    return "internal";
+}
+export function registerArchive(program) {
+    program
+        .command("archive")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("Merge a shipped feature's deltas into the living specs + model, then archive it")
+        .option("--approve", "archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block")
+        .option("--dry-run", "print the whole merge plan and write nothing")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        try {
+            await runArchive(featureId, opts);
+        }
+        catch (err) {
+            // Plan-phase failures happen before any write; commit-phase failures are
+            // rolled back by runArchive, which says so in the message it throws.
+            // A file loam cannot decode is one it cannot merge, and that is the same
+            // answer as any other merge it could not compute: nothing was written.
+            fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);
+        }
+    });
+}
+async function runArchive(featureId, opts) {
+    const json = opts.json === true;
+    const loaded = await loadConfig();
+    if (loaded.kind !== "loaded") {
+        reportNoConfig(json, loaded);
+        return;
+    }
+    const config = loaded.config;
+    let release;
+    try {
+        release = await acquireDocsLock(config.docsDir);
+    }
+    catch (err) {
+        if (err instanceof DocsBusyError)
+            throw new ArchiveFailure("docs-busy", err.message);
+        throw err;
+    }
+    try {
+        await archiveLocked(config, featureId, opts);
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/commands/archive/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/commands/archive/archive.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam archive`: fold a finished feature's three axes into the living docs.\n *\n * Registration and the lock, nothing else. Everything the command actually does\n * is under `./plan/` and `./run.ts`, in that order — the gate refuses, the plan\n * computes, the commit swaps.\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { fail, reportNoConfig, type ErrorCode } from \"../../core/envelope/json.js\";\nimport { message } from \"../../core/staging/commit.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { ArchiveFailure, type ArchiveOptions } from \"./plan/refusal.js\";\nimport { archiveLocked } from \"./run.js\";\nimport { LandscapeSpliceError } from \"../../core/c4/splice/contract.js\";\nimport { NotUtf8Error } from \"../../core/staging/writes.js\";\nimport { OpenapiMergeError } from \"../../core/openapi/merge/error.js\";\nimport { InterruptedCommitError } from \"../../core/staging/interrupted.js\";\n\n\nfunction archiveErrorCode(err: unknown): ErrorCode {\n  if (err instanceof ArchiveFailure) return err.code;\n  // Every splice refusal is the mechanical merge answer — see the class.\n  if (err instanceof LandscapeSpliceError) return \"merge-failed\";\n  if (err instanceof NotUtf8Error) return \"merge-failed\";\n  // The merge branch wraps its own call and re-throws as merge-failed; the\n  // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable\n  // feature contract answered merge-failed or `internal` depending on whether\n  // the service already had a living openapi.yaml. The code answers \"can I\n  // trust the repo?\", and that answer does not turn on which side of the merge\n  // the document sat on.\n  if (err instanceof OpenapiMergeError) return \"merge-failed\";\n  if (err instanceof InterruptedCommitError) return \"commit-interrupted\";\n  return \"internal\";\n}\n\n\nexport function registerArchive(program: Command): void {\n  program\n    .command(\"archive\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Merge a shipped feature's deltas into the living specs + model, then archive it\")\n    .option(\"--approve\", \"archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block\")\n    .option(\"--dry-run\", \"print the whole merge plan and write nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: ArchiveOptions) => {\n      const json = opts.json === true;\n      try {\n        await runArchive(featureId, opts);\n      } catch (err) {\n        // Plan-phase failures happen before any write; commit-phase failures are\n        // rolled back by runArchive, which says so in the message it throws.\n        // A file loam cannot decode is one it cannot merge, and that is the same\n        // answer as any other merge it could not compute: nothing was written.\n        fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);\n      }\n    });\n}\n\nasync function runArchive(featureId: string, opts: ArchiveOptions): Promise<void> {\n  const json = opts.json === true;\n  const loaded = await loadConfig();\n  if (loaded.kind !== \"loaded\") {\n    reportNoConfig(json, loaded);\n    return;\n  }\n  const config = loaded.config;\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLock(config.docsDir);\n  } catch (err) {\n    if (err instanceof DocsBusyError) throw new ArchiveFailure(\"docs-busy\", err.message);\n    throw err;\n  }\n  try {\n    await archiveLocked(config, featureId, opts);\n  } finally {\n    await release();\n  }\n}\n"]}

package/dist/commands/archive/plan/contracts/asyncapi.js

@@ -0,0 +1,178 @@
+/**
+ * The AsyncAPI contract merge: the feature's asyncapi deltas folded into each
+ * living event contract — the event axis's mirror of ./openapi.ts, slot-keyed
+ * where that one is path-keyed.
+ *
+ * Nothing is written. Everything lands in the `Plan`, so a failure on any axis
+ * leaves the living docs exactly as they were.
+ */
+import { existsSync } from "node:fs";
+import { parse } from "yaml";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { planWrite, readUtf8 } from "../../../../core/staging/writes.js";
+import { featureSpecPaths } from "../../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../../core/repo/service-target.js";
+import { readAsyncapi } from "../../../../core/asyncapi/read.js";
+import { asyncapiSlots } from "../../../../core/asyncapi/digest.js";
+import { asyncapiSurfaces } from "../../../../core/asyncapi/baseline/surfaces.js";
+import { AsyncapiMergeError } from "../../../../core/asyncapi/merge/error.js";
+import { stripAsyncapiMarkers } from "../../../../core/asyncapi/merge/markers.js";
+import { mergeAsyncapiSlots } from "../../../../core/asyncapi/merge/merge.js";
+import { ArchiveFailure } from "../refusal.js";
+import {} from "../state.js";
+/** The per-section overwrite code — three codes, one per slot shape, mirroring the OpenAPI axis's. */
+function modifiedCode(section) {
+    if (section === "components.messages")
+        return "asyncapi.message-modified";
+    return section === "channels" ? "asyncapi.channel-modified" : "asyncapi.operation-modified";
+}
+export async function planAsyncapiContracts(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes, planWarns, planGates, asyncapiRemovals } = plan;
+    for (const svc of deltaServices) {
+        const featAsyncapi = featureSpecPaths(featureDir, svc).asyncapi;
+        if (!existsSync(featAsyncapi))
+            continue;
+        const featText = await readUtf8(featAsyncapi);
+        const featDoc = await readAsyncapi(featAsyncapi);
+        // Coherence grades `asyncapi.invalid` and gates on it; the merge stays
+        // mechanical under --approve for the OpenAPI planner's reason: a document
+        // loam cannot read is one it cannot merge, and that is the same answer as
+        // any other merge it could not compute — nothing is written.
+        if (featDoc.unreadable) {
+            throw new ArchiveFailure("merge-failed", `feature asyncapi ${repoPath(config.docsDir, featAsyncapi)} for ${svc} does not read as an AsyncAPI document (${featDoc.error ?? "not a YAML mapping"}) — the event axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
+        }
+        const names = featDoc.messages.filter((m) => m.remove !== true).map((m) => m.name);
+        // An `x-loam-remove` NESTED on an inline channel message retires nothing:
+        // an inline message is channel-slot interior (SCHEMA.md's decision), so
+        // the marker is just channel content — and when the restated channel is
+        // otherwise identical to living, not even that: the merge deduplicates it
+        // away and the marker lands in no bucket at all. The merge is safe either
+        // way (the deep strip keeps the key out of living), but the author asked
+        // for a removal that will not happen, and silence there is how a retired
+        // message would stay on the wire — openapi.remove-marker-path-level's
+        // lesson at the nested depth. Gated like the other plan-visible breaches,
+        // --approve and all.
+        for (const m of featDoc.messages) {
+            if (m.remove !== true || !m.slot.startsWith("channels."))
+                continue;
+            const channel = m.slot.slice("channels.".length, m.slot.lastIndexOf(".messages."));
+            planGates.push({
+                severity: "error",
+                code: "asyncapi.remove-marker-inline",
+                subject: svc,
+                message: `${svc}: '${m.slot}' carries x-loam-remove nested on an inline channel message — inline messages are channel interior, not slots, so this retires nothing. Retire the whole channel (x-loam-remove: true at channels.${channel}), or declare the message under components.messages (the channel $ref-ing it) and put the marker there.`,
+            });
+        }
+        // The shared context, for the OpenAPI planner's reason: once per delta
+        // service must not mean one fleet walk per delta service.
+        const livingAsyncapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).asyncapi;
+        try {
+            if (!existsSync(livingAsyncapi)) {
+                // A removal against a non-existent contract is gated by coherence;
+                // under --approve the strip drops the markers, so the one thing left
+                // to decide is whether a document remains. It must not when nothing
+                // survives: an asyncapi.yaml's very PRESENCE is graded on this axis
+                // (absence is `service.no-asyncapi`'s question, silence otherwise),
+                // so a slotless or all-markers delta creating an empty living
+                // contract would put a presence claim on a service that has none.
+                // SLOTS only, deliberately, now that component surfaces merge: a
+                // document holding schemas and no channel, operation or message
+                // declares no event at all, and creating it would make exactly the
+                // presence claim this branch exists to refuse.
+                const surviving = asyncapiSlots(parse(featText)).filter((slot) => !slot.remove);
+                if (surviving.length === 0) {
+                    say(`  asyncapi: ${svc} — nothing to merge (the delta declares no surviving slots), no living asyncapi.yaml created`);
+                    continue;
+                }
+                writes.push(planWrite(livingAsyncapi, stripAsyncapiMarkers(featText, svc)));
+                say(`  asyncapi: ${svc} — created (${names.join(", ")})`);
+                continue;
+            }
+            const merge = mergeAsyncapiSlots(await readUtf8(livingAsyncapi), featText, svc);
+            // What the delta declares OUTSIDE the three slot sections — the one
+            // question the merge result cannot answer for the silence below, because
+            // a merge that wrote nothing reports nothing to distinguish "the delta
+            // was all quotes" from "the delta was all schemas and I dropped them".
+            const surfaces = asyncapiSurfaces(parse(featText));
+            if (merge.text !== null) {
+                writes.push(planWrite(livingAsyncapi, merge.text));
+                // The parenthesised list names the MESSAGES the delta declares, and a
+                // delta whose whole change is a component surface has none — so this
+                // printed `merged ()`, the same empty-parenthesis lie the create
+                // branch above is commented for: it reads as "this merge wrote
+                // nothing" about a merge that just published a shared schema to every
+                // consumer of the fleet. Drop the parentheses when there is nothing to
+                // put in them; the surface lines below name what actually moved.
+                say(`  asyncapi: ${svc} — merged${names.length > 0 ? ` (${names.join(", ")})` : ""}`);
+            }
+            else if (surfaces.length > 0) {
+                // "The plan wrote less than my delta spells" is the sentence a reader
+                // cannot infer from an unchanged file — this file's own comment below
+                // names it for slots, and a components-only delta is the shape where
+                // silence is indistinguishable from the defect that made it merge
+                // nothing at all. Not a warning: every surface being a quote is
+                // correct authoring and the correct merge.
+                say(`  asyncapi: ${svc} — nothing to write: every one of the ${surfaces.length} component surface(s) this delta declares already stands as living has it`);
+            }
+            if (merge.removed.length > 0) {
+                asyncapiRemovals.push({ service: svc, slots: merge.removed.map((slot) => slot.label) });
+                for (const slot of merge.removed)
+                    say(`      - removes ${slot.label}`);
+            }
+            // Said out loud, because "the plan wrote less than my delta spells" is
+            // the one thing a reader cannot infer from a merged file. Not a warning:
+            // quoting the contract around your change is correct authoring, and
+            // leaving the quote alone is the correct merge.
+            for (const slot of merge.quoted) {
+                say(`      · quotes ${slot.label} — unchanged since it was pinned, left as living has it`);
+            }
+            // The surface half's mirrors of the three lines around them. A component
+            // surface reaches the reader by exactly the same three sentences a slot
+            // does, because it is graded by exactly the same verdict.
+            for (const id of merge.componentsQuoted) {
+                say(`      · quotes components.${id} — unchanged since it was pinned, left as living has it`);
+            }
+            // Stale surfaces reaching the merge at all means --approve pushed past
+            // the gate's asyncapi.baseline-stale — the plan still names what it cost.
+            for (const slot of merge.baselineStale) {
+                say(`      ⚠ stale baseline on ${slot.label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+            }
+            for (const id of merge.componentsStale) {
+                say(`      ⚠ stale baseline on components.${id} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+            }
+            for (const id of merge.componentsModified) {
+                planWarns.push({
+                    severity: "warn",
+                    code: "asyncapi.component-modified",
+                    subject: svc,
+                    message: `${svc}: the delta declares components.${id}, which the living AsyncAPI already has with different content — the merge overwrites the living component wholesale`,
+                });
+                say(`      ⚠ overwrites components.${id} — the living definition differs`);
+            }
+            for (const slot of merge.modified) {
+                planWarns.push({
+                    severity: "warn",
+                    code: modifiedCode(slot.section),
+                    subject: svc,
+                    message: `${svc}: the delta redefines ${slot.label}, which the living AsyncAPI already has — the merge overwrites the living slot wholesale`,
+                });
+                say(`      ⚠ overwrites ${slot.label} — the living definition differs`);
+            }
+            for (const ref of merge.unresolved) {
+                planGates.push({
+                    severity: "error",
+                    code: "asyncapi.ref-unresolved",
+                    subject: svc,
+                    message: `${svc}: $ref '${ref}' resolves in neither the feature's asyncapi.yaml nor the living one — the merged document would carry a dangling reference`,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof AsyncapiMergeError)
+                throw new ArchiveFailure("merge-failed", err.message);
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=asyncapi.js.map