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

package/dist/commands/archive/plan/state.js

@@ -0,0 +1,27 @@
+/**
+ * What one phase of an archive hands the next.
+ *
+ * `Gated` is everything the refusals resolved on the way through — the
+ * canonical id, the delta document parsed once, the issue lists. `Plan` is what
+ * the merges accumulate. Neither is a bag of conveniences: a value is in here
+ * exactly when two phases have to agree about it, and the alternative was
+ * fifteen parameters threaded through three functions in the same order.
+ */
+import {} from "../../../core/vocabulary/issue.js";
+import {} from "../../../core/staging/writes.js";
+import {} from "../../../core/kernel/ids/dirs.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/capabilities/tree.js";
+import {} from "../../../core/staging/interrupted.js";
+export function emptyPlan() {
+    return {
+        writes: [],
+        planWarns: [],
+        planGates: [],
+        openapiRemovals: [],
+        asyncapiRemovals: [],
+        architectureServices: new Set(),
+    };
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAc,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAmB,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAuB,MAAM,sCAAsC,CAAC;AA6C3E,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,oBAAoB,EAAE,IAAI,GAAG,EAAmB;KACjD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What one phase of an archive hands the next.\n *\n * `Gated` is everything the refusals resolved on the way through — the\n * canonical id, the delta document parsed once, the issue lists. `Plan` is what\n * the merges accumulate. Neither is a bag of conveniences: a value is in here\n * exactly when two phases have to agree about it, and the alternative was\n * fifteen parameters threaded through three functions in the same order.\n */\nimport { type Issue } from \"../../../core/vocabulary/issue.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { type FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type CapabilityDoc } from \"../../../core/capabilities/tree.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\n\nexport interface Gated {\n  /** The canonical feature id. The raw argument does not survive the gate. */\n  id: string;\n  dirName: string;\n  featureDir: FeatureDir;\n  /** Parsed ONCE for the whole run — loading it spins up a fresh Langium workspace. */\n  deltaDoc: LoadedDoc | undefined;\n  deltaServices: PathableService[];\n  /**\n   * The capability documents this feature's delta carries, walked ONCE in the\n   * gate. Three phases downstream ask about them — the conflict-marker scan,\n   * the strayed-requirement scan and the merge — and a second walk is a second\n   * chance to disagree about which capabilities the merge touches.\n   */\n  capabilityDeltas: CapabilityDoc[];\n  gating: Issue[];\n  advisory: Issue[];\n  archiveDir: string;\n  archiveDest: string;\n  /** The interrupted commit this run repaired, if any — `--json` reports it. */\n  recovered: CommitRecovery | null;\n  /** Every coherence issue the gate read, gating and advisory together. */\n  issues: Issue[];\n}\n\nexport interface Plan {\n  writes: PlannedWrite[];\n  /**\n   * Warnings born in the plan itself (openapi.op-modified,\n   * openapi.component-modified, the asyncapi.*-modified trio) — printed with\n   * the plan and carried into the `--json` envelope beside the coherence\n   * warnings.\n   */\n  planWarns: Issue[];\n  /** Gating issues born in the plan itself (openapi.ref-unresolved, asyncapi.ref-unresolved). */\n  planGates: Issue[];\n  openapiRemovals: Array<{ service: string; operations: string[] }>;\n  /** Living asyncapi slots the plan deletes on removal markers, by their labels. */\n  asyncapiRemovals: Array<{ service: string; slots: string[] }>;\n  /** Services this feature introduces on the architecture axis alone. */\n  architectureServices: Set<PathableService>;\n}\n\nexport function emptyPlan(): Plan {\n  return {\n    writes: [],\n    planWarns: [],\n    planGates: [],\n    openapiRemovals: [],\n    asyncapiRemovals: [],\n    architectureServices: new Set<PathableService>(),\n  };\n}\n"]}

package/dist/commands/archive/run.js

@@ -0,0 +1,251 @@
+/**
+ * The archive itself, under the docs lock: gate, plan, commit.
+ *
+ * The order is the command's whole safety property. Every refusal happens before
+ * a byte is planned (`./plan/gate.ts`), the plan is computed entirely in memory
+ * so a failure on any axis leaves the living docs untouched (`./plan/specs.ts`,
+ * `./plan/contracts/`, `./plan/landscape.ts`), and only a plan that succeeded
+ * on every axis is staged
+ * and swapped. `--dry-run` returns between the second and the third.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { emitJson, repoPath, sayExplain } from "../../core/envelope/json.js";
+import { message, quietPruneEmptyParents, quietRm, rollbackError, rollbackStaged, stageWrites, swapStaged, } from "../../core/staging/commit.js";
+import { clearCommitIntent, writeCommitIntent } from "../../core/staging/recovery/intent.js";
+import { SNAPSHOT_DIR, SnapshotClobberError, snapshotDir, writeSnapshot, } from "../../core/staging/snapshot.js";
+import { enumeratedServices } from "../../core/repo/service-target.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { gate } from "./plan/gate.js";
+import {} from "./plan/refusal.js";
+import { planCapabilities, planGlossary, planSpecs } from "./plan/specs.js";
+import { planOpenapiContracts } from "./plan/contracts/openapi.js";
+import { planAsyncapiContracts } from "./plan/contracts/asyncapi.js";
+import { planFlows, planLandscape } from "./plan/landscape.js";
+import { emptyPlan } from "./plan/state.js";
+import { issueJson, refuseJson } from "./plan/refusal.js";
+import { ArchiveFailure } from "./plan/refusal.js";
+import { printPlan } from "./plan/refusal.js";
+export async function archiveLocked(config, featureId, opts) {
+    const dryRun = opts.dryRun === true;
+    const json = opts.json === true;
+    // All prose goes through here so `--json` keeps stdout a single JSON document.
+    const say = (line = "") => {
+        if (!json)
+            console.log(line);
+    };
+    // One read index for the whole run, threaded through every planner's
+    // config record: gate, the spec merge and both contract merges each hold
+    // per-service loops that resolve living paths through the enumeration, and
+    // without a shared context every one of those calls re-walks the fleet —
+    // O(services²) work under a lock that guarantees the tree is not moving.
+    // The snapshot resolver below reads through the same context, so it pays
+    // for that enumeration too.
+    const read = { docsDir: config.docsDir, fleet: new FleetContext() };
+    const gated = await gate(read, featureId, opts, say);
+    if (gated === null)
+        return;
+    const { id, dirName, featureDir, gating, advisory, archiveDir, archiveDest, recovered, issues } = gated;
+    say(`archive ${id}${dryRun ? "  (dry run)" : ""}\n`);
+    // PLAN — compute every merge in memory. Nothing is written until the whole plan
+    // succeeds, so a failure on any axis leaves the living docs untouched.
+    const planned = emptyPlan();
+    await planSpecs(read, gated, planned, say);
+    // The business corpus, beside the service one and before the contracts: both
+    // are requirement merges, and reading them together is how a plan stays
+    // legible as "what this feature promises" followed by "how it is built".
+    await planCapabilities(read, gated, planned, say);
+    // The vocabulary the change brings with it, beside the promises it makes:
+    // a create-only whole-file copy, refused at the gate if the word already
+    // lives (`core/glossary/delta.ts`).
+    await planGlossary(read, gated, planned, say);
+    await planOpenapiContracts(read, gated, planned, say);
+    await planAsyncapiContracts(read, gated, planned, say);
+    await planLandscape(config, gated, planned, say);
+    // The flows this feature brings, after the elements they draw hops over: the
+    // copy is create-only and refused at the gate if the living tree already holds
+    // one (`core/usecases/delta/flows.ts`), and it is ordered after the landscape
+    // merge so a reader of the plan sees the map change before the sequence drawn
+    // on it.
+    await planFlows(config, gated, planned, say);
+    const { writes, planWarns, planGates, openapiRemovals, asyncapiRemovals } = planned;
+    // Gate on what only the plan could see: a merged operation pointing at a
+    // component that exists nowhere, a removal marker addressing no operation.
+    // Same doctrine as the coherence gate — a judgment call --approve overrides
+    // (unlike the mechanical merge-failed refusals), and a dry run is gated too.
+    // Checked after the whole plan so the refusal costs nothing: no write has
+    // happened yet either way.
+    if (planGates.length > 0 && !opts.approve) {
+        const msg = `archive ${id} — BLOCKED: ${planGates.length} issue(s) in the contract merge`;
+        if (json) {
+            refuseJson("not-coherent", msg, [...issues, ...planWarns, ...planGates], `features/${dirName}`);
+            return;
+        }
+        console.error(`${msg}:`);
+        for (const i of planGates)
+            console.error(`  ✗ ${i.message}`);
+        console.error(`\nFix them in the feature's openapi.yaml / asyncapi.yaml — or re-run with --approve to merge anyway.`);
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return;
+    }
+    if (planGates.length > 0) {
+        say(`\n  ⚠ archiving despite ${planGates.length} contract merge issue(s) (--approve):`);
+        for (const i of planGates)
+            say(`      ✗ ${i.message}`);
+    }
+    // The plan as data, verb decided now — after the commit everything would read
+    // as an update. The `--json` payload is identical for a dry run and the real
+    // thing except for `archived`; what WOULD happen is what DOES happen.
+    const warnings = [...advisory, ...planWarns];
+    const overridden = opts.approve === true ? [...gating, ...planGates] : [];
+    const plan = writes.map((w) => ({
+        path: repoPath(config.docsDir, w.path),
+        action: existsSync(w.path) ? "update" : "create",
+    }));
+    plan.push({ path: `features/${dirName}`, action: "move", to: `features/archive/${dirName}` });
+    const payload = (archived) => ({
+        command: "archive",
+        feature: id,
+        archived,
+        path: repoPath(config.docsDir, archiveDest),
+        plan,
+        warnings: warnings.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),
+        overridden: overridden.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),
+        openapiRemovals,
+        asyncapiRemovals,
+        // Present only when this run found an interrupted commit and dealt with it:
+        // an agent that sees the docs change under it deserves to be told why, and
+        // the absent field is the ordinary case.
+        ...(recovered === null ? {} : { recovered }),
+    });
+    if (dryRun) {
+        if (json)
+            emitJson(payload(false));
+        else
+            printPlan(config.docsDir, writes, dirName);
+        return;
+    }
+    // COMMIT — the whole plan computed cleanly. Stage every new version beside its
+    // target, snapshot what is about to be overwritten, then swap them into place.
+    // Staging touches the filesystem — a read-only `architecture/`, a full disk,
+    // a target whose pre-image cannot be read. None of that is a bug in loam, and
+    // reporting `internal` sends the reader looking for one; it is the same
+    // answer as any other merge that could not be computed: nothing was written.
+    let staged;
+    try {
+        staged = await stageWrites(writes);
+    }
+    catch (err) {
+        throw new ArchiveFailure("merge-failed", `${message(err)} — nothing was written`);
+    }
+    let snapshot = false;
+    let createdArchiveDir;
+    try {
+        // The snapshot's resolver pair: how a docs-relative path decomposes into a
+        // service identity, and where that identity lives NOW. Built here — the
+        // command layer's view of the tree — and injected, so the snapshot module
+        // never learns the repo layout. The seam the flat wave left is now
+        // threaded: both answers come from the enumeration, so a service filed
+        // into a subsystem keys its snapshot rows by the directory it actually
+        // lives in, and the clobber guard grades a leftover claim at that same
+        // address. The root-level parse stays as the fallback for the one path
+        // shape the enumeration cannot know yet — a service this archive CREATES,
+        // which always materialises unfiled at services/<id>/.
+        // Tolerant on purpose: a docs repo whose services/ is absent still
+        // archives a landscape-only feature exactly as before — the enumeration
+        // is empty, every row keys by the flat fallback, and the missing
+        // directory stays doctor's diagnosis rather than a merge-failed here.
+        const dirOf = new Map((await enumeratedServices(config.docsDir, read.fleet)).map((s) => [s.id, repoPath(config.docsDir, s.dir)]));
+        const serviceKeyOf = (rel) => {
+            for (const [service, dir] of dirOf) {
+                if (rel.startsWith(`${dir}/`))
+                    return { service, artifact: rel.slice(dir.length + 1) };
+            }
+            const m = /^services\/([^/]+)\/(.+)$/.exec(rel);
+            return m ? { service: m[1], artifact: m[2] } : null;
+        };
+        const serviceDirOf = (service) => dirOf.get(service) ?? null;
+        await writeSnapshot({
+            featureDir,
+            docsDir: config.docsDir,
+            feature: { featureId: id, dirName },
+            staged,
+            serviceKeyOf,
+            serviceDirOf,
+        });
+        snapshot = true;
+        // The journal, fsynced, BEFORE the first rename: swapStaged is N renames and
+        // only each one of them is atomic, so a kill between two used to leave a
+        // half-merged repo that nothing could name — `doctor` and `status` called it
+        // healthy and `validate --all` blamed the delta. Written from `staged`, so
+        // it records the same digests the swaps are about to produce.
+        await writeCommitIntent(config.docsDir, { command: "archive", restore: "before", feature: id, moveFrom: featureDir, moveTo: archiveDest }, staged);
+        await swapStaged(staged);
+        createdArchiveDir = await mkdir(archiveDir, { recursive: true });
+        await rename(featureDir, archiveDest);
+        // Last: while it exists, the commit is in flight.
+        await clearCommitIntent(config.docsDir);
+    }
+    catch (err) {
+        if (err instanceof SnapshotClobberError) {
+            // Nothing swapped — the refusal happens before the journal is even
+            // written — so this only takes the temp files away. Its own code, because
+            // the answer is not "re-run": a previous archive of this feature is still
+            // sitting in the living docs.
+            await rollbackStaged(staged);
+            throw new ArchiveFailure("commit-interrupted", err.message);
+        }
+        // Everything this run made, unmade: the swapped files, the snapshot inside the
+        // feature that is staying put, and features/archive/ if we are the ones who
+        // created it (mkdir reports nothing when it was already there).
+        const failures = await rollbackStaged(staged);
+        // The rollback decided the outcome, so the journal has nothing left to
+        // describe — including on rollback-incomplete, where the files it names are
+        // the ones the message tells a human to look at.
+        await clearCommitIntent(config.docsDir);
+        // The snapshot goes only when the rollback HELD. On rollback-incomplete it
+        // holds the only on-disk pre-images of the very files the message tells the
+        // reader to repair by hand — a MODIFIED requirement's previous text appears
+        // nowhere else. Retaining it is safe: the next archive of this feature reads
+        // it before it would replace it, and refuses if the living docs have moved.
+        if (snapshot && failures.length === 0)
+            await quietRm(snapshotDir(featureDir));
+        // `features/archive/` is shared the moment it exists: another archive can
+        // have moved a whole feature into it between our mkdir and this rollback,
+        // and a recursive remove of "the directory we created" took that feature —
+        // snapshot and all — with it, on OUR failure path, in silence. Empty
+        // directories only, stopping at the first that is not.
+        if (createdArchiveDir !== undefined)
+            await quietPruneEmptyParents(archiveDir, createdArchiveDir);
+        // The code is a caller's answer to "can I trust the repo?": merge-failed
+        // means yes (rolled back), rollback-incomplete means look at it by hand.
+        const wrapped = rollbackError(err, failures);
+        const kept = snapshot && failures.length > 0
+            ? ` Pre-images of the overwritten files are kept in features/${dirName}/${SNAPSHOT_DIR}/files/.`
+            : "";
+        throw new ArchiveFailure(failures.length > 0 ? "rollback-incomplete" : "merge-failed", wrapped.message + kept);
+    }
+    if (json) {
+        emitJson(payload(true));
+        return;
+    }
+    console.log(`\n  archived: features/${dirName} → features/archive/${dirName}`);
+    console.log(`  snapshot: features/archive/${dirName}/${SNAPSHOT_DIR}/ — \`loam unarchive ${id}\` puts it back`);
+    // The closing line is a claim about the whole docs repo, and it is the line a
+    // reader stops at. It may be printed only when this archive left nothing the
+    // next `validate --all` will fail on — a service with no model, or a gate the
+    // caller told it to merge past. Printing it over either is how a red fleet
+    // gets reported as a finished one.
+    const incomplete = planWarns.filter((w) => w.code === "service.no-model");
+    if (incomplete.length === 0 && overridden.length === 0) {
+        console.log("  living spec + landscape are now complete + current.");
+        return;
+    }
+    for (const w of incomplete)
+        console.log(`  ⚠ ${w.message}`);
+    if (overridden.length > 0) {
+        console.log(`  ⚠ merged past ${overridden.length} gating issue(s) with --approve — the living docs carry them now; \`loam validate --all\` says what they cost.`);
+    }
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/archive/run.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The archive itself, under the docs lock: gate, plan, commit.\n *\n * The order is the command's whole safety property. Every refusal happens before\n * a byte is planned (`./plan/gate.ts`), the plan is computed entirely in memory\n * so a failure on any axis leaves the living docs untouched (`./plan/specs.ts`,\n * `./plan/contracts/`, `./plan/landscape.ts`), and only a plan that succeeded\n * on every axis is staged\n * and swapped. `--dry-run` returns between the second and the third.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir, rename } from \"node:fs/promises\";\nimport { emitJson, repoPath, sayExplain } from \"../../core/envelope/json.js\";\nimport {\n  message,\n  quietPruneEmptyParents,\n  quietRm,\n  rollbackError,\n  rollbackStaged,\n  stageWrites,\n  swapStaged,\n} from \"../../core/staging/commit.js\";\nimport { clearCommitIntent, writeCommitIntent } from \"../../core/staging/recovery/intent.js\";\nimport {\n  SNAPSHOT_DIR,\n  SnapshotClobberError,\n  snapshotDir,\n  writeSnapshot,\n  type ServiceKey,\n} from \"../../core/staging/snapshot.js\";\nimport { enumeratedServices } from \"../../core/repo/service-target.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { gate } from \"./plan/gate.js\";\nimport { type ArchiveOptions } from \"./plan/refusal.js\";\nimport { planCapabilities, planGlossary, planSpecs } from \"./plan/specs.js\";\nimport { planOpenapiContracts } from \"./plan/contracts/openapi.js\";\nimport { planAsyncapiContracts } from \"./plan/contracts/asyncapi.js\";\nimport { planFlows, planLandscape } from \"./plan/landscape.js\";\nimport { emptyPlan } from \"./plan/state.js\";\nimport { issueJson, refuseJson } from \"./plan/refusal.js\";\nimport { ArchiveFailure } from \"./plan/refusal.js\";\nimport { printPlan } from \"./plan/refusal.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\nexport async function archiveLocked(\n  config: { docsDir: DocsDir },\n  featureId: string,\n  opts: ArchiveOptions,\n): Promise<void> {\n  const dryRun = opts.dryRun === true;\n  const json = opts.json === true;\n  // All prose goes through here so `--json` keeps stdout a single JSON document.\n  const say = (line = \"\"): void => {\n    if (!json) console.log(line);\n  };\n\n  // One read index for the whole run, threaded through every planner's\n  // config record: gate, the spec merge and both contract merges each hold\n  // per-service loops that resolve living paths through the enumeration, and\n  // without a shared context every one of those calls re-walks the fleet —\n  // O(services²) work under a lock that guarantees the tree is not moving.\n  // The snapshot resolver below reads through the same context, so it pays\n  // for that enumeration too.\n  const read = { docsDir: config.docsDir, fleet: new FleetContext() };\n  const gated = await gate(read, featureId, opts, say);\n  if (gated === null) return;\n  const { id, dirName, featureDir, gating, advisory, archiveDir, archiveDest, recovered, issues } = gated;\n\n  say(`archive ${id}${dryRun ? \"  (dry run)\" : \"\"}\\n`);\n\n  // PLAN — compute every merge in memory. Nothing is written until the whole plan\n  // succeeds, so a failure on any axis leaves the living docs untouched.\n  const planned = emptyPlan();\n  await planSpecs(read, gated, planned, say);\n  // The business corpus, beside the service one and before the contracts: both\n  // are requirement merges, and reading them together is how a plan stays\n  // legible as \"what this feature promises\" followed by \"how it is built\".\n  await planCapabilities(read, gated, planned, say);\n  // The vocabulary the change brings with it, beside the promises it makes:\n  // a create-only whole-file copy, refused at the gate if the word already\n  // lives (`core/glossary/delta.ts`).\n  await planGlossary(read, gated, planned, say);\n  await planOpenapiContracts(read, gated, planned, say);\n  await planAsyncapiContracts(read, gated, planned, say);\n  await planLandscape(config, gated, planned, say);\n  // The flows this feature brings, after the elements they draw hops over: the\n  // copy is create-only and refused at the gate if the living tree already holds\n  // one (`core/usecases/delta/flows.ts`), and it is ordered after the landscape\n  // merge so a reader of the plan sees the map change before the sequence drawn\n  // on it.\n  await planFlows(config, gated, planned, say);\n  const { writes, planWarns, planGates, openapiRemovals, asyncapiRemovals } = planned;\n\n  // Gate on what only the plan could see: a merged operation pointing at a\n  // component that exists nowhere, a removal marker addressing no operation.\n  // Same doctrine as the coherence gate — a judgment call --approve overrides\n  // (unlike the mechanical merge-failed refusals), and a dry run is gated too.\n  // Checked after the whole plan so the refusal costs nothing: no write has\n  // happened yet either way.\n  if (planGates.length > 0 && !opts.approve) {\n    const msg = `archive ${id} — BLOCKED: ${planGates.length} issue(s) in the contract merge`;\n    if (json) {\n      refuseJson(\n        \"not-coherent\",\n        msg,\n        [...issues, ...planWarns, ...planGates],\n        `features/${dirName}`,\n      );\n      return;\n    }\n    console.error(`${msg}:`);\n    for (const i of planGates) console.error(`  ✗ ${i.message}`);\n    console.error(`\\nFix them in the feature's openapi.yaml / asyncapi.yaml — or re-run with --approve to merge anyway.`);\n    sayExplain(\"not-coherent\");\n    process.exitCode = 1;\n    return;\n  }\n  if (planGates.length > 0) {\n    say(`\\n  ⚠ archiving despite ${planGates.length} contract merge issue(s) (--approve):`);\n    for (const i of planGates) say(`      ✗ ${i.message}`);\n  }\n\n  // The plan as data, verb decided now — after the commit everything would read\n  // as an update. The `--json` payload is identical for a dry run and the real\n  // thing except for `archived`; what WOULD happen is what DOES happen.\n  const warnings = [...advisory, ...planWarns];\n  const overridden = opts.approve === true ? [...gating, ...planGates] : [];\n  const plan: Array<Record<string, unknown>> = writes.map((w) => ({\n    path: repoPath(config.docsDir, w.path),\n    action: existsSync(w.path) ? \"update\" : \"create\",\n  }));\n  plan.push({ path: `features/${dirName}`, action: \"move\", to: `features/archive/${dirName}` });\n  const payload = (archived: boolean): Record<string, unknown> => ({\n    command: \"archive\",\n    feature: id,\n    archived,\n    path: repoPath(config.docsDir, archiveDest),\n    plan,\n    warnings: warnings.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),\n    overridden: overridden.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),\n    openapiRemovals,\n    asyncapiRemovals,\n    // Present only when this run found an interrupted commit and dealt with it:\n    // an agent that sees the docs change under it deserves to be told why, and\n    // the absent field is the ordinary case.\n    ...(recovered === null ? {} : { recovered }),\n  });\n\n  if (dryRun) {\n    if (json) emitJson(payload(false));\n    else printPlan(config.docsDir, writes, dirName);\n    return;\n  }\n\n  // COMMIT — the whole plan computed cleanly. Stage every new version beside its\n  // target, snapshot what is about to be overwritten, then swap them into place.\n  // Staging touches the filesystem — a read-only `architecture/`, a full disk,\n  // a target whose pre-image cannot be read. None of that is a bug in loam, and\n  // reporting `internal` sends the reader looking for one; it is the same\n  // answer as any other merge that could not be computed: nothing was written.\n  let staged;\n  try {\n    staged = await stageWrites(writes);\n  } catch (err) {\n    throw new ArchiveFailure(\"merge-failed\", `${message(err)} — nothing was written`);\n  }\n  let snapshot = false;\n  let createdArchiveDir: string | undefined;\n  try {\n    // The snapshot's resolver pair: how a docs-relative path decomposes into a\n    // service identity, and where that identity lives NOW. Built here — the\n    // command layer's view of the tree — and injected, so the snapshot module\n    // never learns the repo layout. The seam the flat wave left is now\n    // threaded: both answers come from the enumeration, so a service filed\n    // into a subsystem keys its snapshot rows by the directory it actually\n    // lives in, and the clobber guard grades a leftover claim at that same\n    // address. The root-level parse stays as the fallback for the one path\n    // shape the enumeration cannot know yet — a service this archive CREATES,\n    // which always materialises unfiled at services/<id>/.\n    // Tolerant on purpose: a docs repo whose services/ is absent still\n    // archives a landscape-only feature exactly as before — the enumeration\n    // is empty, every row keys by the flat fallback, and the missing\n    // directory stays doctor's diagnosis rather than a merge-failed here.\n    const dirOf = new Map(\n      (await enumeratedServices(config.docsDir, read.fleet)).map((s) => [s.id as string, repoPath(config.docsDir, s.dir)]),\n    );\n    const serviceKeyOf = (rel: string): ServiceKey | null => {\n      for (const [service, dir] of dirOf) {\n        if (rel.startsWith(`${dir}/`)) return { service, artifact: rel.slice(dir.length + 1) };\n      }\n      const m = /^services\\/([^/]+)\\/(.+)$/.exec(rel);\n      return m ? { service: m[1]!, artifact: m[2]! } : null;\n    };\n    const serviceDirOf = (service: string): string | null => dirOf.get(service) ?? null;\n    await writeSnapshot({\n      featureDir,\n      docsDir: config.docsDir,\n      feature: { featureId: id, dirName },\n      staged,\n      serviceKeyOf,\n      serviceDirOf,\n    });\n    snapshot = true;\n    // The journal, fsynced, BEFORE the first rename: swapStaged is N renames and\n    // only each one of them is atomic, so a kill between two used to leave a\n    // half-merged repo that nothing could name — `doctor` and `status` called it\n    // healthy and `validate --all` blamed the delta. Written from `staged`, so\n    // it records the same digests the swaps are about to produce.\n    await writeCommitIntent(\n      config.docsDir,\n      { command: \"archive\", restore: \"before\", feature: id, moveFrom: featureDir, moveTo: archiveDest },\n      staged,\n    );\n    await swapStaged(staged);\n    createdArchiveDir = await mkdir(archiveDir, { recursive: true });\n    await rename(featureDir, archiveDest);\n    // Last: while it exists, the commit is in flight.\n    await clearCommitIntent(config.docsDir);\n  } catch (err) {\n    if (err instanceof SnapshotClobberError) {\n      // Nothing swapped — the refusal happens before the journal is even\n      // written — so this only takes the temp files away. Its own code, because\n      // the answer is not \"re-run\": a previous archive of this feature is still\n      // sitting in the living docs.\n      await rollbackStaged(staged);\n      throw new ArchiveFailure(\"commit-interrupted\", err.message);\n    }\n    // Everything this run made, unmade: the swapped files, the snapshot inside the\n    // feature that is staying put, and features/archive/ if we are the ones who\n    // created it (mkdir reports nothing when it was already there).\n    const failures = await rollbackStaged(staged);\n    // The rollback decided the outcome, so the journal has nothing left to\n    // describe — including on rollback-incomplete, where the files it names are\n    // the ones the message tells a human to look at.\n    await clearCommitIntent(config.docsDir);\n    // The snapshot goes only when the rollback HELD. On rollback-incomplete it\n    // holds the only on-disk pre-images of the very files the message tells the\n    // reader to repair by hand — a MODIFIED requirement's previous text appears\n    // nowhere else. Retaining it is safe: the next archive of this feature reads\n    // it before it would replace it, and refuses if the living docs have moved.\n    if (snapshot && failures.length === 0) await quietRm(snapshotDir(featureDir));\n    // `features/archive/` is shared the moment it exists: another archive can\n    // have moved a whole feature into it between our mkdir and this rollback,\n    // and a recursive remove of \"the directory we created\" took that feature —\n    // snapshot and all — with it, on OUR failure path, in silence. Empty\n    // directories only, stopping at the first that is not.\n    if (createdArchiveDir !== undefined) await quietPruneEmptyParents(archiveDir, createdArchiveDir);\n    // The code is a caller's answer to \"can I trust the repo?\": merge-failed\n    // means yes (rolled back), rollback-incomplete means look at it by hand.\n    const wrapped = rollbackError(err, failures);\n    const kept =\n      snapshot && failures.length > 0\n        ? ` Pre-images of the overwritten files are kept in features/${dirName}/${SNAPSHOT_DIR}/files/.`\n        : \"\";\n    throw new ArchiveFailure(failures.length > 0 ? \"rollback-incomplete\" : \"merge-failed\", wrapped.message + kept);\n  }\n\n  if (json) {\n    emitJson(payload(true));\n    return;\n  }\n  console.log(`\\n  archived: features/${dirName} → features/archive/${dirName}`);\n  console.log(`  snapshot: features/archive/${dirName}/${SNAPSHOT_DIR}/ — \\`loam unarchive ${id}\\` puts it back`);\n  // The closing line is a claim about the whole docs repo, and it is the line a\n  // reader stops at. It may be printed only when this archive left nothing the\n  // next `validate --all` will fail on — a service with no model, or a gate the\n  // caller told it to merge past. Printing it over either is how a red fleet\n  // gets reported as a finished one.\n  const incomplete = planWarns.filter((w) => w.code === \"service.no-model\");\n  if (incomplete.length === 0 && overridden.length === 0) {\n    console.log(\"  living spec + landscape are now complete + current.\");\n    return;\n  }\n  for (const w of incomplete) console.log(`  ⚠ ${w.message}`);\n  if (overridden.length > 0) {\n    console.log(\n      `  ⚠ merged past ${overridden.length} gating issue(s) with --approve — the living docs carry them now; \\`loam validate --all\\` says what they cost.`,\n    );\n  }\n}\n"]}

package/dist/commands/context/context.js

@@ -0,0 +1,99 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { emitJson, fail, reportNoConfig } from "../../core/envelope/json.js";
+import { parseServiceId } from "../../core/kernel/ids/service.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { assemblePack, packHoles } from "../../core/pack/pack.js";
+import { nearestIds } from "../../core/repo/entries.js";
+import { missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
+import { printPack } from "./print.js";
+export function registerContext(program) {
+    program
+        .command("context")
+        .argument("<service>", "service id, e.g. payment-service")
+        .description("Assemble one service's docs slice — spec, contracts, edges, permissions, capabilities, and the deltas in flight over it — as one deterministic briefing; writes nothing")
+        .option("--feature <FEAT>", "narrow the in-flight section to this one feature")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (serviceArg, opts) => {
+        const json = opts.json === true;
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const { docsDir } = loaded.config;
+        // `services`, not `docs`: the pack is a statement about one service in
+        // the fleet, and an empty pack read out of a directory that is not a
+        // docs repo would say "nothing is documented here" about a repo nobody
+        // looked in.
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        const context = new FleetContext();
+        try {
+            // The feature is resolved BEFORE the service is looked up (delta's
+            // ordering): its refusal is about the flag, and it must not depend on
+            // whether the service half of the invocation was right.
+            let feature = null;
+            if (opts.feature !== undefined) {
+                feature = await resolveFeature(docsDir, opts.feature, "exclude", context);
+                if (!feature) {
+                    fail(json, "unknown-target", await missingFeatureMessage(docsDir, opts.feature, context));
+                    return;
+                }
+            }
+            // The enumeration answers first and the grammar second —
+            // core/repo/service-target.ts's settled order, and the pack is exactly
+            // the case its banner argues from: `services/payment service/` is a
+            // directory `validate --all` grades and `service.id-invalid` tells the
+            // team to rename, so refusing it on the grammar would make the one
+            // service loam complains about the one service nobody can be briefed
+            // on. The enumerated id is safe to use onward — a readdir produced it,
+            // which is `RawServiceId`'s whole provenance. A name that is neither
+            // enumerated nor legal is refused before any path is built; a legal
+            // name with no directory is `unknown-service`, because a typo must
+            // never be indistinguishable from an undocumented service — an EMPTY
+            // pack reads as "nothing to know here".
+            const entries = await context.listServices(docsDir);
+            const entry = entries.find((e) => e.id === serviceArg);
+            if (entry === undefined) {
+                const parsed = parseServiceId(serviceArg, "service");
+                if (!parsed.ok) {
+                    fail(json, "invalid-option", parsed.problem);
+                    return;
+                }
+                const near = nearestIds(serviceArg, entries.map((e) => e.id));
+                fail(json, "unknown-service", `No service '${serviceArg}' under ${docsDir}/services/.` +
+                    (near.length === 0 ? "" : ` Did you mean ${near.map((n) => `'${n}'`).join(" or ")}?`));
+                return;
+            }
+            const pack = await assemblePack({ docsDir, entry, feature, context });
+            // A document behind the pack that exists but does not parse empties
+            // its section, and an agent loading the pack as a briefing would read
+            // that as "nothing here" — the vacuously-green pattern. The output
+            // stays as informative as ever (and `ok` stays true under --json: the
+            // command ran); the exit code is what stops a pipeline from building
+            // on it, so it is set BEFORE the format fork — the guard is about the
+            // pack, not about how it is rendered.
+            if (packHoles(pack))
+                process.exitCode = 1;
+            if (json) {
+                emitJson({ command: "context", docsDir, ...pack });
+                return;
+            }
+            printPack(pack);
+        }
+        catch (err) {
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            // The assembly is all-or-nothing, like explore's scan: it reads every
+            // document the pack quotes, so the honest answer to an unreadable FILE
+            // (a directory where a document belongs, bytes that are not UTF-8) is
+            // a refusal naming the path, not a briefing with a silent hole in it.
+            reportRepositoryUnavailable(json, err, "the pack would be missing a document", docsDir);
+        }
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/commands/context/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/commands/context/context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, fail, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { parseServiceId } from \"../../core/kernel/ids/service.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { assemblePack, packHoles } from \"../../core/pack/pack.js\";\nimport { nearestIds, type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { printPack } from \"./print.js\";\n\ninterface ContextOptions {\n  feature?: string;\n  json?: boolean;\n}\n\nexport function registerContext(program: Command): void {\n  program\n    .command(\"context\")\n    .argument(\"<service>\", \"service id, e.g. payment-service\")\n    .description(\n      \"Assemble one service's docs slice — spec, contracts, edges, permissions, capabilities, and the deltas in flight over it — as one deterministic briefing; writes nothing\",\n    )\n    .option(\"--feature <FEAT>\", \"narrow the in-flight section to this one feature\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (serviceArg: string, opts: ContextOptions) => {\n      const json = opts.json === true;\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const { docsDir } = loaded.config;\n      // `services`, not `docs`: the pack is a statement about one service in\n      // the fleet, and an empty pack read out of a directory that is not a\n      // docs repo would say \"nothing is documented here\" about a repo nobody\n      // looked in.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      const context = new FleetContext();\n      try {\n        // The feature is resolved BEFORE the service is looked up (delta's\n        // ordering): its refusal is about the flag, and it must not depend on\n        // whether the service half of the invocation was right.\n        let feature: FeatureEntry | null = null;\n        if (opts.feature !== undefined) {\n          feature = await resolveFeature(docsDir, opts.feature, \"exclude\", context);\n          if (!feature) {\n            fail(json, \"unknown-target\", await missingFeatureMessage(docsDir, opts.feature, context));\n            return;\n          }\n        }\n\n        // The enumeration answers first and the grammar second —\n        // core/repo/service-target.ts's settled order, and the pack is exactly\n        // the case its banner argues from: `services/payment service/` is a\n        // directory `validate --all` grades and `service.id-invalid` tells the\n        // team to rename, so refusing it on the grammar would make the one\n        // service loam complains about the one service nobody can be briefed\n        // on. The enumerated id is safe to use onward — a readdir produced it,\n        // which is `RawServiceId`'s whole provenance. A name that is neither\n        // enumerated nor legal is refused before any path is built; a legal\n        // name with no directory is `unknown-service`, because a typo must\n        // never be indistinguishable from an undocumented service — an EMPTY\n        // pack reads as \"nothing to know here\".\n        const entries = await context.listServices(docsDir);\n        const entry = entries.find((e) => e.id === serviceArg);\n        if (entry === undefined) {\n          const parsed = parseServiceId(serviceArg, \"service\");\n          if (!parsed.ok) {\n            fail(json, \"invalid-option\", parsed.problem);\n            return;\n          }\n          const near = nearestIds(serviceArg, entries.map((e) => e.id));\n          fail(\n            json,\n            \"unknown-service\",\n            `No service '${serviceArg}' under ${docsDir}/services/.` +\n              (near.length === 0 ? \"\" : ` Did you mean ${near.map((n) => `'${n}'`).join(\" or \")}?`),\n          );\n          return;\n        }\n\n        const pack = await assemblePack({ docsDir, entry, feature, context });\n        // A document behind the pack that exists but does not parse empties\n        // its section, and an agent loading the pack as a briefing would read\n        // that as \"nothing here\" — the vacuously-green pattern. The output\n        // stays as informative as ever (and `ok` stays true under --json: the\n        // command ran); the exit code is what stops a pipeline from building\n        // on it, so it is set BEFORE the format fork — the guard is about the\n        // pack, not about how it is rendered.\n        if (packHoles(pack)) process.exitCode = 1;\n\n        if (json) {\n          emitJson({ command: \"context\", docsDir, ...pack });\n          return;\n        }\n        printPack(pack);\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // The assembly is all-or-nothing, like explore's scan: it reads every\n        // document the pack quotes, so the honest answer to an unreadable FILE\n        // (a directory where a document belongs, bytes that are not UTF-8) is\n        // a refusal naming the path, not a briefing with a silent hole in it.\n        reportRepositoryUnavailable(json, err, \"the pack would be missing a document\", docsDir);\n      }\n    });\n}\n"]}