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

package/dist/commands/list/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../../src/commands/list/review.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The review-order gathering and sort behind `loam list --needs-work\n * --review-order`: per-service contract reads (contained per read), the one\n * landscape load, and the deterministic ordering. The derivation itself is\n * pure and lives in core/dependencies/fanin.ts.\n *\n * Fifth and LAST file of the list package — the next module added here forces\n * a split along a named seam (docs/CODE-STYLE.md, the five-file limit).\n */\nimport { existsSync } from \"node:fs\";\nimport { readAsyncapi } from \"../../core/asyncapi/read.js\";\nimport { type LoadedDoc } from \"../../core/c4/likec4.js\";\nimport { serviceResolver } from \"../../core/c4/resolve/service.js\";\nimport { fleetFanIn, type FanInContracts } from \"../../core/dependencies/fanin.js\";\nimport { type FleetContext } from \"../../core/fleet-context.js\";\nimport { inOrder } from \"../../core/kernel/concurrency.js\";\nimport { compareIds, type ServiceEntry } from \"../../core/repo/entries.js\";\nimport { landscapePath, servicePathsAt } from \"../../core/repo/paths.js\";\nimport { type ServiceView } from \"./views.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\n/**\n * The landscape for the review path, loaded ONCE through the run's memo and\n * handed both to serviceViews (as `preloaded`) and to the fan-in joins — a\n * second parse of a document the run already holds is the cost the shared\n * load exists to retire.\n *\n * Deliberately NOT `readLandscape` from commands/validate/fleet/load.ts: that\n * import would add a list→validate/fleet package edge while\n * validate/fleet/scorecard→list already exists, and the containment is four\n * lines.\n */\nexport async function reviewLandscape(docsDir: DocsDir, fleet: FleetContext): Promise<LoadedDoc | null> {\n  const lp = landscapePath(docsDir);\n  // Absent is `null` — the same \"there is none\" serviceViews' own load\n  // spells. An UNREADABLE file is deliberately not contained here: bare\n  // `loam list` refuses `repository-unavailable` when serviceViews' load\n  // throws on it, and a rendering flag must never change what the run\n  // refuses — a swallowed throw here answered ok over the exact file the\n  // flagless run refuses on, with rows CHANGED by the silent null\n  // (`proven: false` flips apiExpected and the missing lists). The throw\n  // reaches list.ts's existing handler, so both paths refuse identically.\n  if (!existsSync(lp)) return null;\n  return fleet.loadLikeC4(lp);\n}\n\n/**\n * One service's contract slice for the message join, contained PER READ, not\n * per slice. The distinction is somebody else's rank: a slice is a caller's\n * evidence about OTHER services' fan-in, not only its own row, so a slice\n * that discarded its readable spec.md because its arch.spec.md is broken\n * would silently under-report every producer that spec subscribes to.\n */\nasync function contractSlice(entry: ServiceEntry, fleet: FleetContext): Promise<FanInContracts> {\n  const paths = servicePathsAt(entry.dir);\n  const [sent, specConsumes, archConsumes] = await Promise.all([\n    readOr([], async () => {\n      const events = await readAsyncapi(paths.asyncapi, fleet);\n      // An unreadable contract declares nothing this join may count —\n      // swallowing it into its parsed subset would grade a broken file as a\n      // thin one (the scorecard's contracts.ts spells the same rule).\n      return events.unreadable === true ? ([] as readonly string[]) : events.sent;\n    }),\n    readOr([], () => livingConsumes(paths.spec, fleet)),\n    readOr([], () => livingConsumes(paths.archSpec, fleet)),\n  ]);\n  return { sent, consumed: [...specConsumes, ...archConsumes] };\n}\n\n/** `Consumes:` names of a spec file's living requirements; absent file, nothing. */\nasync function livingConsumes(path: string, fleet: FleetContext): Promise<readonly string[]> {\n  if (!existsSync(path)) return [];\n  // A REMOVED requirement is on its way out and subscribes to nothing, from\n  // either spec namespace.\n  return (await fleet.readRequirements(path)).filter((r) => r.kind !== \"REMOVED\").flatMap((r) => r.consumes);\n}\n\n/**\n * The containment: an unreadable artifact contributes nothing — and ONLY that\n * artifact's evidence, per the doctrine above. The catch also exists for a\n * mechanical reason (commands/validate/fleet/scorecard/contracts.ts): these\n * are memoized reads whose REJECTION rejects again on every await, so an\n * uncontained one would delete the whole queue from inside the pool.\n */\nasync function readOr<T>(fallback: T, read: () => Promise<T>): Promise<T> {\n  try {\n    return await read();\n  } catch {\n    // Unreadable reads as \"declares nothing\" — never as a refusal, and never\n    // as its neighbours' silence.\n    return fallback;\n  }\n}\n\n/**\n * Fan-in per service id, FLEET-WIDE — the joins need every service's slice\n * anyway; the caller ranks only the worklist, so vouched services carry a\n * count without occupying a rank.\n */\nexport async function fanInByService(\n  services: ServiceEntry[],\n  fleet: FleetContext,\n  land: LoadedDoc | null,\n): Promise<Map<string, number>> {\n  const known = new Set<string>(services.map((s) => s.id));\n  const slices = await inOrder(services, async (s) => [s.id, await contractSlice(s, fleet)] as const);\n  const request = {\n    services: services.map((s) => s.id),\n    contracts: new Map<string, FanInContracts>(slices),\n  };\n  if (land !== null && land.errors.length === 0) {\n    return fleetFanIn({\n      ...request,\n      landscape: { parses: true, relationships: land.relationships, svcOf: serviceResolver(land.elements, known) },\n    });\n  }\n  return fleetFanIn({ ...request, landscape: { parses: false } });\n}\n\n/**\n * The queue: fan-in descending, ties broken by id — fully deterministic, no\n * clocks, no readdir order, so two runs over one repository are byte-identical\n * (fan-in is a set size and both joins are order-insensitive).\n */\nexport function reviewOrder(views: ServiceView[], fanIn: ReadonlyMap<string, number>): ServiceView[] {\n  return [...views].sort(\n    (a, b) =>\n      (fanIn.get(b.entry.id) ?? 0) - (fanIn.get(a.entry.id) ?? 0) || compareIds(a.entry.id, b.entry.id),\n  );\n}\n"]}

package/dist/commands/list/suites/suites.js

@@ -0,0 +1,140 @@
+/**
+ * `loam list suites [<name>]` — which use cases run together, and WHICH
+ * SERVICES MUST BE UP for a suite's journeys to run.
+ *
+ * That answer is maintained by hand in most fleets — a compose file, a CI
+ * matrix, a paragraph in a runbook — and it is derivable, because a journey
+ * already names every participant it touches and the fleet map already says
+ * which `services/<id>/` each of those elements stands for. Deriving it means it
+ * cannot drift from the journeys: add a hop to a flow and the environment its
+ * suites need changes in the same commit. The grouping and the union are
+ * `core/usecases/suites/`; this module turns them into the section's payload
+ * and its text.
+ *
+ * A sub-package of list/ for `./campaign/`'s reason: the list package stands at
+ * its five-file limit. The direction is list → list/suites, never back.
+ *
+ * ONE SHAPE whether or not a suite was named. Naming one is a filter over the
+ * same answer, not a different question, so `suites[]` narrows and nothing else
+ * does — `ungrouped[]` in particular stays the fleet's, because which journeys
+ * reached no suite is not a fact about the suite being asked after.
+ *
+ * The use-case corpus's health travels as `useCases`, spelled as `list
+ * capabilities`, `status` and `delta` spell it (`unreadable`, `error`), plus a
+ * `state` this section needs and they do not: here the corpus IS the rows, so
+ * "the fleet declares no use case" (`absent`) and "loam read them" (`ok`) are
+ * two answers a reader has to be able to tell apart from one empty list. Over an
+ * unreadable `architecture/` the section DEGRADES rather than refusing, exactly
+ * as `list capabilities` does: `suites` and `ungrouped` are ABSENT keys — `[]`
+ * would be "loam looked and found none", said about a project nobody read — and
+ * a named suite is not refused as unknown, because that refusal would be a
+ * claim about suites loam never saw.
+ */
+import { fail } from "../../../core/envelope/json.js";
+import { listServices } from "../../../core/repo/repo.js";
+import { closeNamesHint } from "../../../core/repo/tree/find.js";
+import { readUseCases } from "../../../core/usecases/fleet.js";
+import { viewFile } from "../../../core/usecases/place.js";
+import { suiteListing } from "../../../core/usecases/suites/suites.js";
+/**
+ * Read the fleet's use cases and group them, or refuse an unknown suite name.
+ *
+ * Returns `null` when it has already refused — the caller's cue to stop, the
+ * `resolveSubsystemSlice` convention one package over.
+ *
+ * The services are enumerated for the RESOLVER, not for the rows: the
+ * element→service join needs the fleet set for the reason every edge join does
+ * (`readUseCases`' `UseCaseRequest.known`), and without it a step into
+ * `orders.api` would resolve to a service called "api".
+ */
+export async function suitesSection(req) {
+    const entries = await listServices(req.docsDir, req.fleet);
+    const scan = await readUseCases({ docsDir: req.docsDir, known: new Set(entries.map((e) => e.id)) });
+    if (scan.kind === "unreadable") {
+        const error = scan.errors[0];
+        return {
+            payload: { useCases: { state: "unreadable", unreadable: true, ...(error === undefined ? {} : { error }) } },
+            print: () => printUnreadable(error),
+        };
+    }
+    const listing = suiteListing(scan);
+    const state = scan.views.length === 0 ? "absent" : "ok";
+    const shown = req.name === undefined ? listing.suites : listing.suites.filter((s) => s.name === req.name);
+    if (req.name !== undefined && shown.length === 0) {
+        const names = listing.suites.map((s) => s.name);
+        // `unknown-target`, the code `--subsystem` and `show` use for a name that
+        // resolves to nothing, with the same close-name hint — an empty environment
+        // for a typo would read as a suite that needs nothing started.
+        fail(req.json, "unknown-target", `No suite '${req.name}'.` +
+            closeNamesHint(req.name, names, names.length === 0
+                ? " No use case under architecture/ carries a `#suite-` tag."
+                : ` Declared suites: ${names.join(", ")}.`));
+        return null;
+    }
+    return {
+        payload: {
+            suites: shown.map(suiteJson),
+            ungrouped: listing.ungrouped.map(viewJson),
+            useCases: { state, unreadable: false },
+        },
+        print: () => printSuites(shown, listing.ungrouped, state === "absent"),
+    };
+}
+/** A use case as the payload names it: enough to open the document it is written in. */
+function viewJson(view) {
+    return { id: view.id, file: viewFile(view) };
+}
+function suiteJson(suite) {
+    return {
+        name: suite.name,
+        views: suite.views.map(viewJson),
+        services: suite.services,
+        unresolved: suite.unresolved,
+    };
+}
+/**
+ * One block per suite — its services, then the participants a stand cannot
+ * start — then the journeys in no suite.
+ *
+ * An unresolved participant gets a line of its own with a marker rather than
+ * being folded into the service list: it is not a service anybody can start,
+ * and reading it as one is how an environment comes up short.
+ */
+function printSuites(suites, ungrouped, absent) {
+    if (absent) {
+        console.log("no use cases — no dynamic view under architecture/ carries #cap-, #req- or #suite-, so there are no suites");
+        return;
+    }
+    if (suites.length === 0)
+        console.log("no suites — no use case under architecture/ carries a #suite- tag");
+    for (const [i, suite] of suites.entries()) {
+        if (i > 0)
+            console.log("");
+        console.log(`suite ${suite.name} — ${suite.views.length} use case(s), ${suite.services.length} service(s) must be up`);
+        for (const service of suite.services)
+            console.log(`  ${service}`);
+        for (const missing of suite.unresolved) {
+            console.log(`  ! ${missing.element} — resolves to no service in services/` +
+                (missing.external ? " (#external: bring a double)" : ""));
+        }
+        console.log(`  use cases: ${suite.views.map((v) => v.id).join(", ")}`);
+    }
+    console.log("");
+    console.log(`use cases in no suite (${ungrouped.length})`);
+    const width = Math.max(0, ...ungrouped.map((v) => v.id.length));
+    for (const view of ungrouped)
+        console.log(`  ${view.id.padEnd(width)}  ${viewFile(view)}`);
+}
+/**
+ * The `list capabilities` note, in this section's words: UNKNOWN rather than
+ * none, and the parser's own message on its own line, because a LikeC4 error is
+ * several lines of expected-token list and inlining it would push the sentence
+ * off the reader's screen.
+ */
+function printUnreadable(error) {
+    console.log("note: architecture/ did not parse, so no use case could be read — " +
+        "which suites exist, and what each needs up, is UNKNOWN here, not none");
+    if (error !== undefined)
+        console.log(`  ${error}`);
+}
+//# sourceMappingURL=suites.js.map

package/dist/commands/list/suites/suites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suites.js","sourceRoot":"","sources":["../../../../src/commands/list/suites/suites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAc,MAAM,yCAAyC,CAAC;AAkBnF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAkB;IACpD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACpG,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;YAC3G,KAAK,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC;SACpC,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1G,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChD,0EAA0E;QAC1E,4EAA4E;QAC5E,+DAA+D;QAC/D,IAAI,CACF,GAAG,CAAC,IAAI,EACR,gBAAgB,EAChB,aAAa,GAAG,CAAC,IAAI,IAAI;YACvB,cAAc,CACZ,GAAG,CAAC,IAAI,EACR,KAAK,EACL,KAAK,CAAC,MAAM,KAAK,CAAC;gBAChB,CAAC,CAAC,2DAA2D;gBAC7D,CAAC,CAAC,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC7C,CACJ,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,OAAO,EAAE;YACP,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC1C,QAAQ,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE;SACvC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,KAAK,QAAQ,CAAC;KACvE,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,SAAS,QAAQ,CAAC,IAAgB;IAChC,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,KAAY;IAC7B,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;KAC7B,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,MAAwB,EAAE,SAAgC,EAAE,MAAe;IAC9F,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CACT,4GAA4G,CAC7G,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,mEAAmE,CAAC,CAAC;IAC1G,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3B,OAAO,CAAC,GAAG,CACT,SAAS,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,iBAAiB,KAAK,CAAC,QAAQ,CAAC,MAAM,wBAAwB,CAC1G,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAClE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACvC,OAAO,CAAC,GAAG,CACT,OAAO,OAAO,CAAC,OAAO,wCAAwC;gBAC5D,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3D,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,0BAA0B,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,KAAK,MAAM,IAAI,IAAI,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAyB;IAChD,OAAO,CAAC,GAAG,CACT,oEAAoE;QAClE,uEAAuE,CAC1E,CAAC;IACF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;AACrD,CAAC","sourcesContent":["/**\n * `loam list suites [<name>]` — which use cases run together, and WHICH\n * SERVICES MUST BE UP for a suite's journeys to run.\n *\n * That answer is maintained by hand in most fleets — a compose file, a CI\n * matrix, a paragraph in a runbook — and it is derivable, because a journey\n * already names every participant it touches and the fleet map already says\n * which `services/<id>/` each of those elements stands for. Deriving it means it\n * cannot drift from the journeys: add a hop to a flow and the environment its\n * suites need changes in the same commit. The grouping and the union are\n * `core/usecases/suites/`; this module turns them into the section's payload\n * and its text.\n *\n * A sub-package of list/ for `./campaign/`'s reason: the list package stands at\n * its five-file limit. The direction is list → list/suites, never back.\n *\n * ONE SHAPE whether or not a suite was named. Naming one is a filter over the\n * same answer, not a different question, so `suites[]` narrows and nothing else\n * does — `ungrouped[]` in particular stays the fleet's, because which journeys\n * reached no suite is not a fact about the suite being asked after.\n *\n * The use-case corpus's health travels as `useCases`, spelled as `list\n * capabilities`, `status` and `delta` spell it (`unreadable`, `error`), plus a\n * `state` this section needs and they do not: here the corpus IS the rows, so\n * \"the fleet declares no use case\" (`absent`) and \"loam read them\" (`ok`) are\n * two answers a reader has to be able to tell apart from one empty list. Over an\n * unreadable `architecture/` the section DEGRADES rather than refusing, exactly\n * as `list capabilities` does: `suites` and `ungrouped` are ABSENT keys — `[]`\n * would be \"loam looked and found none\", said about a project nobody read — and\n * a named suite is not refused as unknown, because that refusal would be a\n * claim about suites loam never saw.\n */\nimport { fail } from \"../../../core/envelope/json.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { listServices } from \"../../../core/repo/repo.js\";\nimport { closeNamesHint } from \"../../../core/repo/tree/find.js\";\nimport type { ParsedView } from \"../../../core/c4/parsed/dynamic-views.js\";\nimport { readUseCases } from \"../../../core/usecases/fleet.js\";\nimport { viewFile } from \"../../../core/usecases/place.js\";\nimport { suiteListing, type Suite } from \"../../../core/usecases/suites/suites.js\";\n\nexport interface SuitesRequest {\n  docsDir: DocsDir;\n  /** The `[name]` argument: narrows `suites[]` to one suite, refusing a name no use case carries. */\n  name: string | undefined;\n  json: boolean;\n  fleet: FleetContext;\n}\n\n/** The section, ready for whichever view the run prints. */\nexport interface SuitesSection {\n  /** The additive payload keys, spread into the `list` envelope. */\n  payload: Record<string, unknown>;\n  /** The text view of the same answer. */\n  print: () => void;\n}\n\n/**\n * Read the fleet's use cases and group them, or refuse an unknown suite name.\n *\n * Returns `null` when it has already refused — the caller's cue to stop, the\n * `resolveSubsystemSlice` convention one package over.\n *\n * The services are enumerated for the RESOLVER, not for the rows: the\n * element→service join needs the fleet set for the reason every edge join does\n * (`readUseCases`' `UseCaseRequest.known`), and without it a step into\n * `orders.api` would resolve to a service called \"api\".\n */\nexport async function suitesSection(req: SuitesRequest): Promise<SuitesSection | null> {\n  const entries = await listServices(req.docsDir, req.fleet);\n  const scan = await readUseCases({ docsDir: req.docsDir, known: new Set(entries.map((e) => e.id)) });\n  if (scan.kind === \"unreadable\") {\n    const error = scan.errors[0];\n    return {\n      payload: { useCases: { state: \"unreadable\", unreadable: true, ...(error === undefined ? {} : { error }) } },\n      print: () => printUnreadable(error),\n    };\n  }\n  const listing = suiteListing(scan);\n  const state = scan.views.length === 0 ? \"absent\" : \"ok\";\n  const shown = req.name === undefined ? listing.suites : listing.suites.filter((s) => s.name === req.name);\n  if (req.name !== undefined && shown.length === 0) {\n    const names = listing.suites.map((s) => s.name);\n    // `unknown-target`, the code `--subsystem` and `show` use for a name that\n    // resolves to nothing, with the same close-name hint — an empty environment\n    // for a typo would read as a suite that needs nothing started.\n    fail(\n      req.json,\n      \"unknown-target\",\n      `No suite '${req.name}'.` +\n        closeNamesHint(\n          req.name,\n          names,\n          names.length === 0\n            ? \" No use case under architecture/ carries a `#suite-` tag.\"\n            : ` Declared suites: ${names.join(\", \")}.`,\n        ),\n    );\n    return null;\n  }\n  return {\n    payload: {\n      suites: shown.map(suiteJson),\n      ungrouped: listing.ungrouped.map(viewJson),\n      useCases: { state, unreadable: false },\n    },\n    print: () => printSuites(shown, listing.ungrouped, state === \"absent\"),\n  };\n}\n\n/** A use case as the payload names it: enough to open the document it is written in. */\nfunction viewJson(view: ParsedView): { id: string; file: string } {\n  return { id: view.id, file: viewFile(view) };\n}\n\nfunction suiteJson(suite: Suite): Record<string, unknown> {\n  return {\n    name: suite.name,\n    views: suite.views.map(viewJson),\n    services: suite.services,\n    unresolved: suite.unresolved,\n  };\n}\n\n/**\n * One block per suite — its services, then the participants a stand cannot\n * start — then the journeys in no suite.\n *\n * An unresolved participant gets a line of its own with a marker rather than\n * being folded into the service list: it is not a service anybody can start,\n * and reading it as one is how an environment comes up short.\n */\nfunction printSuites(suites: readonly Suite[], ungrouped: readonly ParsedView[], absent: boolean): void {\n  if (absent) {\n    console.log(\n      \"no use cases — no dynamic view under architecture/ carries #cap-, #req- or #suite-, so there are no suites\",\n    );\n    return;\n  }\n  if (suites.length === 0) console.log(\"no suites — no use case under architecture/ carries a #suite- tag\");\n  for (const [i, suite] of suites.entries()) {\n    if (i > 0) console.log(\"\");\n    console.log(\n      `suite ${suite.name} — ${suite.views.length} use case(s), ${suite.services.length} service(s) must be up`,\n    );\n    for (const service of suite.services) console.log(`  ${service}`);\n    for (const missing of suite.unresolved) {\n      console.log(\n        `  ! ${missing.element} — resolves to no service in services/` +\n          (missing.external ? \" (#external: bring a double)\" : \"\"),\n      );\n    }\n    console.log(`  use cases: ${suite.views.map((v) => v.id).join(\", \")}`);\n  }\n  console.log(\"\");\n  console.log(`use cases in no suite (${ungrouped.length})`);\n  const width = Math.max(0, ...ungrouped.map((v) => v.id.length));\n  for (const view of ungrouped) console.log(`  ${view.id.padEnd(width)}  ${viewFile(view)}`);\n}\n\n/**\n * The `list capabilities` note, in this section's words: UNKNOWN rather than\n * none, and the parser's own message on its own line, because a LikeC4 error is\n * several lines of expected-token list and inlining it would push the sentence\n * off the reader's screen.\n */\nfunction printUnreadable(error: string | undefined): void {\n  console.log(\n    \"note: architecture/ did not parse, so no use case could be read — \" +\n      \"which suites exist, and what each needs up, is UNKNOWN here, not none\",\n  );\n  if (error !== undefined) console.log(`  ${error}`);\n}\n"]}

package/dist/commands/list/views.js

@@ -0,0 +1,108 @@
+/**
+ * What the list actually reads: one row per service, one verification cell per
+ * feature.
+ *
+ * Both are gathered before anything is printed or serialized, because the same
+ * numbers appear in `--json` and in the worklist footer — a footer computed
+ * from a second read is a footer that can contradict the rows above it.
+ */
+import { existsSync } from "node:fs";
+import { loadFile } from "../../core/c4/likec4.js";
+import { serviceResolver } from "../../core/c4/resolve/service.js";
+import { maturityGaps, serviceMaturity, } from "../../core/vocabulary/maturity.js";
+import {} from "../../core/repo/entries.js";
+import { landscapePath, servicePathsAt } from "../../core/repo/paths.js";
+import { featureTitle } from "../../core/repo/repo.js";
+import { verificationState } from "../../core/status/verification.js";
+import {} from "../../core/verify/answers.js";
+import {} from "../../core/verify/record.js";
+/**
+ * Read the living landscape ONCE and decide, per service, whether an API is
+ * expected of it. `serviceResolver` is handed the real service ids so an edge
+ * drawn into a modelled container (`paymentService.api`) counts for the service
+ * that owns it — the same resolution `validate` uses, so the two commands
+ * cannot disagree about who is called.
+ */
+export async function serviceViews(docsDir, services, boundService, preloaded) {
+    const known = new Set(services.map((s) => s.id));
+    const lp = landscapePath(docsDir);
+    // `preloaded` is the landscape a caller already holds — `undefined` means
+    // "load it if it exists", null "there is none", the convention
+    // validateService's own `preloaded` follows. The fleet scorecard hands in
+    // the batch-parsed doc because a healthy `validate --all` must spin ZERO
+    // per-document workspaces (test/validate-batch-fallback.test.ts counts
+    // them), and a second parse of a document that run already holds was the
+    // exact per-path cost the batch loader exists to retire.
+    const land = preloaded !== undefined ? preloaded : existsSync(lp) ? await loadFile(lp) : null;
+    const called = new Set();
+    // Positive evidence only: with no landscape, or one that does not parse, we
+    // know nothing about who is called and every service is assumed to have an
+    // API — the conservative direction, because claiming a service needs no
+    // contract is how a real one goes undocumented. This is the SAME rule
+    // `landscapeEvidence` (core/vocabulary/maturity.ts) spells per service for
+    // explore and the context pack — derived fleet-wide here in one pass (one
+    // `called` set for every service) because calling the per-service partition
+    // from this loop would re-walk the whole relationship list once per
+    // service. If the rule moves, both spellings move.
+    const proven = land !== null && land.errors.length === 0;
+    if (proven) {
+        const svcOf = serviceResolver(land.elements, known);
+        for (const r of land.relationships) {
+            // …including its self-edge rule: an edge whose two endpoints resolve to
+            // one service is that service's own internal wiring, and counting it made
+            // a service nobody calls owe an OpenAPI contract — `partial` here while
+            // `loam context` (which reads the shared derivation) said `documented`.
+            if (r.op !== undefined && svcOf(r.source) !== svcOf(r.target))
+                called.add(svcOf(r.target));
+        }
+    }
+    return services.map((entry) => {
+        const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);
+        const apiExpected = !proven || called.has(entry.id);
+        const view = {
+            entry,
+            archSpec,
+            apiExpected,
+            unverifiableFromHere: entry.sources.declared && boundService !== entry.id,
+        };
+        const missing = maturityGaps(view);
+        return { ...view, maturity: serviceMaturity(view), missing };
+    });
+}
+/**
+ * The verification column: `status`'s own record state (`verificationState`),
+ * projected onto the cell — the record read, the files added up against the
+ * checklist just derived, the archived record read as frozen history — so
+ * `list`, `status` and `gate` compute one cell, for the reasons that function
+ * records. Reading the record is cheap but no longer one file read — a
+ * directory listing and one small read per attesting service, plus the
+ * one-file `verification.yaml` — and the checklist is derived only when there
+ * is a record to judge: on a fleet-sized repo most features have none, and
+ * deriving N checklists to print N dashes is the cost that would get this
+ * column dropped. `fleet` is the invocation's read index, so each derivation's
+ * enumerations and delta parse are memo hits rather than a walk per feature.
+ *
+ * A record that cannot be read is one dash like an absent one: this column
+ * shows one glyph either way. That includes a record whose summary
+ * contradicts its own claims (`verify.record-miscounted`), so no count from it
+ * is printed as fact — reading it as absent is the safe half of the truth, and
+ * `status` and `verify`, which can say why, report it as unreadable instead.
+ */
+export async function featureVerification(docsDir, f, fleet) {
+    const { state: s } = await verificationState(docsDir, f, { fleet });
+    if (s.state === "absent" || s.state === "unreadable" || s.recorded === null)
+        return null;
+    return {
+        state: s.state,
+        recorded: s.recorded,
+        verdict: s.verdict,
+        confirmed: s.confirmed,
+        claims: s.claims,
+        attested: s.attested,
+        answered: s.answered,
+    };
+}
+export async function featureRow(docsDir, f, fleet) {
+    return { feature: f, cell: await featureVerification(docsDir, f, fleet), title: await featureTitle(f) };
+}
+//# sourceMappingURL=views.js.map

package/dist/commands/list/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../src/commands/list/views.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the list actually reads: one row per service, one verification cell per\n * feature.\n *\n * Both are gathered before anything is printed or serialized, because the same\n * numbers appear in `--json` and in the worklist footer — a footer computed\n * from a second read is a footer that can contradict the rows above it.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile, type LoadedDoc } from \"../../core/c4/likec4.js\";\nimport { serviceResolver } from \"../../core/c4/resolve/service.js\";\nimport {\n  maturityGaps,\n  serviceMaturity,\n  type Maturity,\n  type MaturityInput,\n} from \"../../core/vocabulary/maturity.js\";\nimport { type FeatureEntry, type ServiceEntry } from \"../../core/repo/entries.js\";\nimport { landscapePath, servicePathsAt } from \"../../core/repo/paths.js\";\nimport { featureTitle } from \"../../core/repo/repo.js\";\nimport type { FleetContext } from \"../../core/fleet-context.js\";\nimport { verificationState } from \"../../core/status/verification.js\";\nimport { type AnsweredBy } from \"../../core/verify/answers.js\";\nimport { type VerificationVerdict } from \"../../core/verify/record.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\nexport interface ServiceView extends MaturityInput {\n  /** True when this service's `sources` can only be resolved from its own repo. */\n  unverifiableFromHere: boolean;\n  maturity: Maturity;\n  /**\n   * What stands between this service and the next rung, in fix order — and at\n   * `vouched`, the re-vouch a document that moved under its stamp owes\n   * (`maturityGaps`). Empty exactly when nothing is owed, which is the\n   * worklist's membership test.\n   */\n  missing: string[];\n}\n\n/**\n * Read the living landscape ONCE and decide, per service, whether an API is\n * expected of it. `serviceResolver` is handed the real service ids so an edge\n * drawn into a modelled container (`paymentService.api`) counts for the service\n * that owns it — the same resolution `validate` uses, so the two commands\n * cannot disagree about who is called.\n */\nexport async function serviceViews(\n  docsDir: DocsDir,\n  services: ServiceEntry[],\n  boundService: string | undefined,\n  preloaded?: LoadedDoc | null,\n): Promise<ServiceView[]> {\n  const known = new Set(services.map((s) => s.id));\n  const lp = landscapePath(docsDir);\n  // `preloaded` is the landscape a caller already holds — `undefined` means\n  // \"load it if it exists\", null \"there is none\", the convention\n  // validateService's own `preloaded` follows. The fleet scorecard hands in\n  // the batch-parsed doc because a healthy `validate --all` must spin ZERO\n  // per-document workspaces (test/validate-batch-fallback.test.ts counts\n  // them), and a second parse of a document that run already holds was the\n  // exact per-path cost the batch loader exists to retire.\n  const land = preloaded !== undefined ? preloaded : existsSync(lp) ? await loadFile(lp) : null;\n  const called = new Set<string>();\n  // Positive evidence only: with no landscape, or one that does not parse, we\n  // know nothing about who is called and every service is assumed to have an\n  // API — the conservative direction, because claiming a service needs no\n  // contract is how a real one goes undocumented. This is the SAME rule\n  // `landscapeEvidence` (core/vocabulary/maturity.ts) spells per service for\n  // explore and the context pack — derived fleet-wide here in one pass (one\n  // `called` set for every service) because calling the per-service partition\n  // from this loop would re-walk the whole relationship list once per\n  // service. If the rule moves, both spellings move.\n  const proven = land !== null && land.errors.length === 0;\n  if (proven) {\n    const svcOf = serviceResolver(land.elements, known);\n    for (const r of land.relationships) {\n      // …including its self-edge rule: an edge whose two endpoints resolve to\n      // one service is that service's own internal wiring, and counting it made\n      // a service nobody calls owe an OpenAPI contract — `partial` here while\n      // `loam context` (which reads the shared derivation) said `documented`.\n      if (r.op !== undefined && svcOf(r.source) !== svcOf(r.target)) called.add(svcOf(r.target));\n    }\n  }\n\n  return services.map((entry) => {\n    const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);\n    const apiExpected = !proven || called.has(entry.id);\n    const view = {\n      entry,\n      archSpec,\n      apiExpected,\n      unverifiableFromHere: entry.sources.declared && boundService !== entry.id,\n    };\n    const missing = maturityGaps(view);\n    return { ...view, maturity: serviceMaturity(view), missing };\n  });\n}\n\n/** What the features table says about verification without N `loam verify` runs. */\nexport interface VerificationCell {\n  state: \"recorded\" | \"stale\";\n  /** The day the record was written. */\n  recorded: string;\n  /**\n   * `verify --json`'s own three-valued verdict, through `verificationVerdict` —\n   * not a fourth opinion computed here. `attested` is the one this column got\n   * wrong: a scenario confirmed on an agent's word printed as `11/11` under a\n   * heading that said `verified`, and `list --json` is how the fleet is graded.\n   */\n  verdict: VerificationVerdict;\n  /** Both counts are `tallyRecord`'s — the record's `claims[]`, never its `summary:` block. */\n  confirmed: number;\n  claims: number;\n  /** Of the confirmed, the scenario claims on an agent's word (`attestedClaims`). */\n  attested: number;\n  /**\n   * Of the confirmed, one count per `answered_by` value (`confirmedProvenance`), every key\n   * present. A different question from `attested` above, which is why both are here: `attested`\n   * asks only about `scenario.tested` because that is what the verdict turns on, while this asks\n   * who answered EVERY kind — and reading the first as if it were the second is how the fleet\n   * scorecard credited agent-answered permission and operation claims to a test runner.\n   */\n  answered: Record<AnsweredBy, number>;\n}\n\n/**\n * The verification column: `status`'s own record state (`verificationState`),\n * projected onto the cell — the record read, the files added up against the\n * checklist just derived, the archived record read as frozen history — so\n * `list`, `status` and `gate` compute one cell, for the reasons that function\n * records. Reading the record is cheap but no longer one file read — a\n * directory listing and one small read per attesting service, plus the\n * one-file `verification.yaml` — and the checklist is derived only when there\n * is a record to judge: on a fleet-sized repo most features have none, and\n * deriving N checklists to print N dashes is the cost that would get this\n * column dropped. `fleet` is the invocation's read index, so each derivation's\n * enumerations and delta parse are memo hits rather than a walk per feature.\n *\n * A record that cannot be read is one dash like an absent one: this column\n * shows one glyph either way. That includes a record whose summary\n * contradicts its own claims (`verify.record-miscounted`), so no count from it\n * is printed as fact — reading it as absent is the safe half of the truth, and\n * `status` and `verify`, which can say why, report it as unreadable instead.\n */\nexport async function featureVerification(\n  docsDir: DocsDir,\n  f: FeatureEntry,\n  fleet: FleetContext,\n): Promise<VerificationCell | null> {\n  const { state: s } = await verificationState(docsDir, f, { fleet });\n  if (s.state === \"absent\" || s.state === \"unreadable\" || s.recorded === null) return null;\n  return {\n    state: s.state,\n    recorded: s.recorded,\n    verdict: s.verdict,\n    confirmed: s.confirmed,\n    claims: s.claims,\n    attested: s.attested,\n    answered: s.answered,\n  };\n}\n\n/**\n * One features-table row: the feature, its verification cell, and what it is\n * called — carried together so the table and the payload iterate rows rather\n * than join two arrays by position.\n */\nexport interface FeatureRow {\n  feature: FeatureEntry;\n  cell: VerificationCell | null;\n  /** intent.md's title (`featureTitle`) — the words a person recognises a change by; the id alone is a key. */\n  title: string | null;\n}\n\nexport async function featureRow(docsDir: DocsDir, f: FeatureEntry, fleet: FleetContext): Promise<FeatureRow> {\n  return { feature: f, cell: await featureVerification(docsDir, f, fleet), title: await featureTitle(f) };\n}\n"]}

package/dist/commands/mcp/dispatch.js

@@ -0,0 +1,238 @@
+/**
+ * In-process dispatch for one MCP tool call: build a fresh commander program
+ * holding only the commands the selected tool table exposes, run the argv through
+ * it, and hand back what the CLI would have printed.
+ *
+ * This is the proven harness pattern (test/helpers/harness.ts runLoamNow)
+ * moved to the commands layer, minus the chdir: the server's own cwd IS the
+ * workdir, so every call resolves loam.json exactly as the CLI would in that
+ * directory — the server serves ONE repository, the one it started in, and
+ * never changes directory. In-process rather than a child per call because a
+ * child re-pays LikeC4/Langium startup on every validate, and because in dev
+ * there is no built binary to exec.
+ *
+ * The capture is process-global (console, exitCode), which is safe under
+ * exactly one condition the serve loop guarantees: calls are strictly
+ * sequential — each one is awaited to completion before the next frame is
+ * read — and `parseAsync` resolves only after the action has fully run (the
+ * entire test suite rests on that same guarantee). Nothing here may be
+ * module-level state: two serve sessions in one process (the tests do this)
+ * must not see each other.
+ *
+ * NOTE for test/agents.test.ts's scan: registration happens through the
+ * imported register functions; this module must never contain the literal
+ * dot-command-paren call, comments included, or the CLI surface count breaks.
+ */
+import { Command, CommanderError } from "commander";
+import { format } from "node:util";
+import { emitJsonError } from "../../core/envelope/json.js";
+import { registerValidate } from "../validate/validate.js";
+import { registerStatus } from "../status/status.js";
+import { registerList } from "../list/list.js";
+import { registerShow } from "../show/show.js";
+import { registerDelta } from "../delta/delta.js";
+import { registerTasks } from "../tasks/tasks.js";
+import { registerDiff } from "../diff/diff.js";
+import { registerExplore } from "../explore.js";
+import { registerDependencies } from "../dependencies.js";
+import { registerDoctor } from "../doctor.js";
+import { registerContext } from "../context/context.js";
+import { registerAdopt } from "../adopt/adopt.js";
+import { registerGate } from "../gate/gate.js";
+import { registerExplain } from "../explain/explain.js";
+import { registerInstructions } from "../instructions.js";
+import { registerSteps } from "../steps/steps.js";
+import { registerNew } from "../new/new.js";
+import { registerRebase } from "../rebase/rebase.js";
+import { registerGherkin } from "../gherkin/gherkin.js";
+import { registerArchive } from "../archive/archive.js";
+import { MCP_TOOLS } from "../../core/mcp/tools.js";
+/**
+ * Every console method Node's Console writes to STDOUT — the protocol stream,
+ * where one stray line corrupts the transport. Hooking only `log` was the
+ * reviewed defect here: a `console.info` in any command, or in a dependency a
+ * command loads, would have written straight into the client's frame stream
+ * with every suite green. `warn`/`error` go to stderr, captured for the
+ * server log rather than the wire.
+ */
+const STDOUT_METHODS = [
+    "log", "info", "debug", "dir", "dirxml", "table",
+    "group", "groupCollapsed", "groupEnd", "count", "countReset", "timeLog", "timeEnd",
+];
+const STDERR_METHODS = ["warn", "error"];
+/**
+ * Replace the console methods named above with sink writers; the returned
+ * function restores every original. Captured output is `format(...)`ed, so
+ * `table`/`group` lose their layout — acceptable on purpose: the invariant
+ * bought here is that their BYTES stay off the protocol stream, not that
+ * their rendering survives.
+ */
+export function captureConsole(sinks) {
+    const target = console;
+    const writer = (sink) => (...parts) => {
+        sink.push(format(...parts));
+    };
+    const toStdout = writer(sinks.stdout);
+    const toStderr = writer(sinks.stderr);
+    const original = new Map();
+    for (const [names, replacement] of [
+        [STDOUT_METHODS, toStdout],
+        [STDERR_METHODS, toStderr],
+    ]) {
+        for (const name of names) {
+            // A method absent on this Node build has nothing to capture — and
+            // nothing to restore, so it must not enter the map either.
+            if (typeof target[name] !== "function")
+                continue;
+            original.set(name, target[name]);
+            target[name] = replacement;
+        }
+    }
+    return () => {
+        for (const [name, method] of original)
+            target[name] = method;
+    };
+}
+/** Commander output codes whose printed output is the point, not a usage failure. */
+const PASS_THROUGH = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
+/**
+ * Every command a tool table may name, keyed by the `command` its tool carries.
+ * A LOOKUP, not a roster: which of these a call's program registers is decided
+ * by the active tool table alone (`toolRunner`), so the authoring writers —
+ * new, rebase, gherkin, archive — exist in it only when `--author` put their
+ * tools in the table, and the table the read-only hints describe is the one
+ * place that gate is written.
+ *
+ * `instructions` and `steps` read no config at all, and are in MCP_TOOLS
+ * because an agent meets them BEFORE the repository is wired: every generated
+ * skill's first line points at `loam instructions <workflow>`. They are why
+ * registration follows the table. This list and MCP_TOOLS used to be two
+ * copies of one roster, and nothing counted them against each other until a
+ * tool advertised in `tools/list` and absent here answered a `tools/call` with
+ * `unknown command 'instructions'` — an envelope that reads as the caller's
+ * mistake. `test/mcp-serve.test.ts` calls every advertised tool, and checks
+ * this lookup against both tables directly.
+ */
+const REGISTRARS = new Map([
+    ["validate", registerValidate],
+    ["status", registerStatus],
+    ["list", registerList],
+    ["show", registerShow],
+    ["delta", registerDelta],
+    ["tasks", registerTasks],
+    ["diff", registerDiff],
+    ["explore", registerExplore],
+    ["dependencies", registerDependencies],
+    ["doctor", registerDoctor],
+    ["context", registerContext],
+    ["adopt", registerAdopt],
+    ["gate", registerGate],
+    ["explain", registerExplain],
+    ["instructions", registerInstructions],
+    ["steps", registerSteps],
+    ["new", registerNew],
+    ["rebase", registerRebase],
+    ["gherkin", registerGherkin],
+    ["archive", registerArchive],
+]);
+/**
+ * Resolve every command `tools` name to its registrar, or throw naming each
+ * one that has none. This is the server's STARTUP check, and it runs once per
+ * table: `toolRunner` calls it before the first frame is read, so a tool
+ * advertised with no registrar — the roster drift above, arriving again —
+ * stops `loam mcp` at launch, through cli.ts's catch like any other throw,
+ * before a client has been promised anything. It used to run inside every call's program build, where one
+ * missing entry turned EVERY `tools/call` into an `internal` envelope naming
+ * it, the tools that were wired correctly included: a call's outcome
+ * depended on a tool it never named.
+ */
+export function resolveRegistrars(tools) {
+    const resolved = [];
+    const missing = [];
+    for (const command of new Set(tools.map((tool) => tool.command))) {
+        const register = REGISTRARS.get(command);
+        if (register === undefined)
+            missing.push(`'${command}'`);
+        else
+            resolved.push(register);
+    }
+    if (missing.length > 0) {
+        throw new Error(`loam mcp: no command registered for MCP tool command ${missing.join(", ")} — add it to REGISTRARS in src/commands/mcp/dispatch.ts`);
+    }
+    return resolved;
+}
+/**
+ * The scoped program, output routed into `sinks`, holding exactly the commands
+ * the resolved table names. configureOutput and exitOverride are set BEFORE the
+ * register calls on purpose: commander copies inherited settings onto a
+ * subcommand when it is created, so settings applied after registration would
+ * leave every subcommand writing to the real stdout — which for an MCP server
+ * is the protocol stream.
+ */
+function readProgram(sinks, registrars) {
+    const program = new Command();
+    program.name("loam");
+    program.exitOverride();
+    program.configureOutput({
+        writeOut: (text) => sinks.stdout.push(text),
+        writeErr: (text) => sinks.stderr.push(text),
+    });
+    for (const register of registrars)
+        register(program);
+    return program;
+}
+/**
+ * The runner `loam mcp` serves `tools` with. Throws HERE, at construction, when
+ * the table names a command with no registrar (`resolveRegistrars`); the
+ * runner it returns never throws, and builds each call's program from the
+ * registrars resolved once — so no call can fail for the sake of a tool it
+ * did not name.
+ */
+export function toolRunner(tools = MCP_TOOLS) {
+    const registrars = resolveRegistrars(tools);
+    return (argv) => runToolArgv(argv, registrars);
+}
+/**
+ * Run one tool argv. Never throws: whatever goes wrong becomes an envelope in
+ * `stdout` with `code` 1, so the serve loop's answer to THIS call is the only
+ * thing affected — one bad call must never take the server down, and a
+ * memoised rejection cannot exist because nothing here outlives the call.
+ */
+async function runToolArgv(argv, registrars) {
+    const sinks = { stdout: [], stderr: [] };
+    const previousExitCode = process.exitCode;
+    const restoreConsole = captureConsole(sinks);
+    process.exitCode = undefined;
+    try {
+        await readProgram(sinks, registrars).parseAsync(["node", "loam", ...argv]);
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            if (PASS_THROUGH.has(err.code)) {
+                // Unreachable through the tool schemas (the argv builder refuses every
+                // '-'-prefixed string, so --help/--version cannot arrive), kept for the
+                // day it is not: the output already sits in the sinks; keep its code.
+                if (process.exitCode === undefined)
+                    process.exitCode = err.exitCode;
+            }
+            else {
+                // The same envelope cli.ts's catch emits for a usage error, so an MCP
+                // caller still receives machine-readable JSON, not a bare exception.
+                emitJsonError("invalid-option", err.message.replace(/^error: /, ""));
+            }
+        }
+        else {
+            // An unexpected throw from a command action: the CLI's own catch-all
+            // (`internal`) — the one code with no stable meaning, carried so the
+            // caller gets an envelope rather than a dead call.
+            emitJsonError("internal", err instanceof Error ? err.message : String(err));
+        }
+    }
+    finally {
+        restoreConsole();
+    }
+    const code = typeof process.exitCode === "number" ? process.exitCode : 0;
+    process.exitCode = previousExitCode;
+    return { stdout: sinks.stdout.join("\n"), stderr: sinks.stderr.join("\n"), code };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/commands/mcp/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../../src/commands/mcp/dispatch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * In-process dispatch for one MCP tool call: build a fresh commander program\n * holding only the commands the selected tool table exposes, run the argv through\n * it, and hand back what the CLI would have printed.\n *\n * This is the proven harness pattern (test/helpers/harness.ts runLoamNow)\n * moved to the commands layer, minus the chdir: the server's own cwd IS the\n * workdir, so every call resolves loam.json exactly as the CLI would in that\n * directory — the server serves ONE repository, the one it started in, and\n * never changes directory. In-process rather than a child per call because a\n * child re-pays LikeC4/Langium startup on every validate, and because in dev\n * there is no built binary to exec.\n *\n * The capture is process-global (console, exitCode), which is safe under\n * exactly one condition the serve loop guarantees: calls are strictly\n * sequential — each one is awaited to completion before the next frame is\n * read — and `parseAsync` resolves only after the action has fully run (the\n * entire test suite rests on that same guarantee). Nothing here may be\n * module-level state: two serve sessions in one process (the tests do this)\n * must not see each other.\n *\n * NOTE for test/agents.test.ts's scan: registration happens through the\n * imported register functions; this module must never contain the literal\n * dot-command-paren call, comments included, or the CLI surface count breaks.\n */\nimport { Command, CommanderError } from \"commander\";\nimport { format } from \"node:util\";\nimport { emitJsonError } from \"../../core/envelope/json.js\";\nimport { registerValidate } from \"../validate/validate.js\";\nimport { registerStatus } from \"../status/status.js\";\nimport { registerList } from \"../list/list.js\";\nimport { registerShow } from \"../show/show.js\";\nimport { registerDelta } from \"../delta/delta.js\";\nimport { registerTasks } from \"../tasks/tasks.js\";\nimport { registerDiff } from \"../diff/diff.js\";\nimport { registerExplore } from \"../explore.js\";\nimport { registerDependencies } from \"../dependencies.js\";\nimport { registerDoctor } from \"../doctor.js\";\nimport { registerContext } from \"../context/context.js\";\nimport { registerAdopt } from \"../adopt/adopt.js\";\nimport { registerGate } from \"../gate/gate.js\";\nimport { registerExplain } from \"../explain/explain.js\";\nimport { registerInstructions } from \"../instructions.js\";\nimport { registerSteps } from \"../steps/steps.js\";\nimport { registerNew } from \"../new/new.js\";\nimport { registerRebase } from \"../rebase/rebase.js\";\nimport { registerGherkin } from \"../gherkin/gherkin.js\";\nimport { registerArchive } from \"../archive/archive.js\";\nimport type { ToolRunOutcome } from \"../../core/mcp/protocol.js\";\nimport type { ToolRunner } from \"./serve.js\";\nimport { MCP_TOOLS, type McpTool } from \"../../core/mcp/tools.js\";\n\n/** Console sinks for one dispatch — a value, not module state, so calls cannot share buffers. */\nexport interface Sinks {\n  readonly stdout: string[];\n  readonly stderr: string[];\n}\n\n/**\n * Every console method Node's Console writes to STDOUT — the protocol stream,\n * where one stray line corrupts the transport. Hooking only `log` was the\n * reviewed defect here: a `console.info` in any command, or in a dependency a\n * command loads, would have written straight into the client's frame stream\n * with every suite green. `warn`/`error` go to stderr, captured for the\n * server log rather than the wire.\n */\nconst STDOUT_METHODS = [\n  \"log\", \"info\", \"debug\", \"dir\", \"dirxml\", \"table\",\n  \"group\", \"groupCollapsed\", \"groupEnd\", \"count\", \"countReset\", \"timeLog\", \"timeEnd\",\n] as const;\nconst STDERR_METHODS = [\"warn\", \"error\"] as const;\n\n/**\n * Replace the console methods named above with sink writers; the returned\n * function restores every original. Captured output is `format(...)`ed, so\n * `table`/`group` lose their layout — acceptable on purpose: the invariant\n * bought here is that their BYTES stay off the protocol stream, not that\n * their rendering survives.\n */\nexport function captureConsole(sinks: Sinks): () => void {\n  const target = console as unknown as Record<string, unknown>;\n  const writer = (sink: string[]) => (...parts: unknown[]): void => {\n    sink.push(format(...parts));\n  };\n  const toStdout = writer(sinks.stdout);\n  const toStderr = writer(sinks.stderr);\n  const original = new Map<string, unknown>();\n  for (const [names, replacement] of [\n    [STDOUT_METHODS, toStdout],\n    [STDERR_METHODS, toStderr],\n  ] as const) {\n    for (const name of names) {\n      // A method absent on this Node build has nothing to capture — and\n      // nothing to restore, so it must not enter the map either.\n      if (typeof target[name] !== \"function\") continue;\n      original.set(name, target[name]);\n      target[name] = replacement;\n    }\n  }\n  return () => {\n    for (const [name, method] of original) target[name] = method;\n  };\n}\n\n/** Commander output codes whose printed output is the point, not a usage failure. */\nconst PASS_THROUGH = new Set([\"commander.help\", \"commander.helpDisplayed\", \"commander.version\"]);\n\n/** One command's registration onto a program — the shape every `registerX` export has. */\ntype Registrar = (program: Command) => void;\n\n/**\n * Every command a tool table may name, keyed by the `command` its tool carries.\n * A LOOKUP, not a roster: which of these a call's program registers is decided\n * by the active tool table alone (`toolRunner`), so the authoring writers —\n * new, rebase, gherkin, archive — exist in it only when `--author` put their\n * tools in the table, and the table the read-only hints describe is the one\n * place that gate is written.\n *\n * `instructions` and `steps` read no config at all, and are in MCP_TOOLS\n * because an agent meets them BEFORE the repository is wired: every generated\n * skill's first line points at `loam instructions <workflow>`. They are why\n * registration follows the table. This list and MCP_TOOLS used to be two\n * copies of one roster, and nothing counted them against each other until a\n * tool advertised in `tools/list` and absent here answered a `tools/call` with\n * `unknown command 'instructions'` — an envelope that reads as the caller's\n * mistake. `test/mcp-serve.test.ts` calls every advertised tool, and checks\n * this lookup against both tables directly.\n */\nconst REGISTRARS = new Map<string, Registrar>([\n  [\"validate\", registerValidate],\n  [\"status\", registerStatus],\n  [\"list\", registerList],\n  [\"show\", registerShow],\n  [\"delta\", registerDelta],\n  [\"tasks\", registerTasks],\n  [\"diff\", registerDiff],\n  [\"explore\", registerExplore],\n  [\"dependencies\", registerDependencies],\n  [\"doctor\", registerDoctor],\n  [\"context\", registerContext],\n  [\"adopt\", registerAdopt],\n  [\"gate\", registerGate],\n  [\"explain\", registerExplain],\n  [\"instructions\", registerInstructions],\n  [\"steps\", registerSteps],\n  [\"new\", registerNew],\n  [\"rebase\", registerRebase],\n  [\"gherkin\", registerGherkin],\n  [\"archive\", registerArchive],\n]);\n\n/**\n * Resolve every command `tools` name to its registrar, or throw naming each\n * one that has none. This is the server's STARTUP check, and it runs once per\n * table: `toolRunner` calls it before the first frame is read, so a tool\n * advertised with no registrar — the roster drift above, arriving again —\n * stops `loam mcp` at launch, through cli.ts's catch like any other throw,\n * before a client has been promised anything. It used to run inside every call's program build, where one\n * missing entry turned EVERY `tools/call` into an `internal` envelope naming\n * it, the tools that were wired correctly included: a call's outcome\n * depended on a tool it never named.\n */\nexport function resolveRegistrars(tools: readonly McpTool[]): readonly Registrar[] {\n  const resolved: Registrar[] = [];\n  const missing: string[] = [];\n  for (const command of new Set(tools.map((tool) => tool.command))) {\n    const register = REGISTRARS.get(command);\n    if (register === undefined) missing.push(`'${command}'`);\n    else resolved.push(register);\n  }\n  if (missing.length > 0) {\n    throw new Error(`loam mcp: no command registered for MCP tool command ${missing.join(\", \")} — add it to REGISTRARS in src/commands/mcp/dispatch.ts`);\n  }\n  return resolved;\n}\n\n/**\n * The scoped program, output routed into `sinks`, holding exactly the commands\n * the resolved table names. configureOutput and exitOverride are set BEFORE the\n * register calls on purpose: commander copies inherited settings onto a\n * subcommand when it is created, so settings applied after registration would\n * leave every subcommand writing to the real stdout — which for an MCP server\n * is the protocol stream.\n */\nfunction readProgram(sinks: Sinks, registrars: readonly Registrar[]): Command {\n  const program = new Command();\n  program.name(\"loam\");\n  program.exitOverride();\n  program.configureOutput({\n    writeOut: (text) => sinks.stdout.push(text),\n    writeErr: (text) => sinks.stderr.push(text),\n  });\n  for (const register of registrars) register(program);\n  return program;\n}\n\n/**\n * The runner `loam mcp` serves `tools` with. Throws HERE, at construction, when\n * the table names a command with no registrar (`resolveRegistrars`); the\n * runner it returns never throws, and builds each call's program from the\n * registrars resolved once — so no call can fail for the sake of a tool it\n * did not name.\n */\nexport function toolRunner(tools: readonly McpTool[] = MCP_TOOLS): ToolRunner {\n  const registrars = resolveRegistrars(tools);\n  return (argv) => runToolArgv(argv, registrars);\n}\n\n/**\n * Run one tool argv. Never throws: whatever goes wrong becomes an envelope in\n * `stdout` with `code` 1, so the serve loop's answer to THIS call is the only\n * thing affected — one bad call must never take the server down, and a\n * memoised rejection cannot exist because nothing here outlives the call.\n */\nasync function runToolArgv(argv: readonly string[], registrars: readonly Registrar[]): Promise<ToolRunOutcome> {\n  const sinks: Sinks = { stdout: [], stderr: [] };\n  const previousExitCode = process.exitCode;\n  const restoreConsole = captureConsole(sinks);\n  process.exitCode = undefined;\n  try {\n    await readProgram(sinks, registrars).parseAsync([\"node\", \"loam\", ...argv]);\n  } catch (err) {\n    if (err instanceof CommanderError) {\n      if (PASS_THROUGH.has(err.code)) {\n        // Unreachable through the tool schemas (the argv builder refuses every\n        // '-'-prefixed string, so --help/--version cannot arrive), kept for the\n        // day it is not: the output already sits in the sinks; keep its code.\n        if (process.exitCode === undefined) process.exitCode = err.exitCode;\n      } else {\n        // The same envelope cli.ts's catch emits for a usage error, so an MCP\n        // caller still receives machine-readable JSON, not a bare exception.\n        emitJsonError(\"invalid-option\", err.message.replace(/^error: /, \"\"));\n      }\n    } else {\n      // An unexpected throw from a command action: the CLI's own catch-all\n      // (`internal`) — the one code with no stable meaning, carried so the\n      // caller gets an envelope rather than a dead call.\n      emitJsonError(\"internal\", err instanceof Error ? err.message : String(err));\n    }\n  } finally {\n    restoreConsole();\n  }\n  const code = typeof process.exitCode === \"number\" ? process.exitCode : 0;\n  process.exitCode = previousExitCode;\n  return { stdout: sinks.stdout.join(\"\\n\"), stderr: sinks.stderr.join(\"\\n\"), code };\n}\n"]}