@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

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":"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","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

@@ -12,10 +12,9 @@ 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 { featureChecklist } from "../../core/verify/checklist.js";
-import { readVerification } from "../../core/verify/file.js";
+import { verificationState } from "../../core/status/verification.js";
 import {} from "../../core/verify/answers.js";
-import { confirmedProvenance, tallyRecord, verificationVerdict, } from "../../core/verify/record.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
@@ -70,40 +69,36 @@ export async function serviceViews(docsDir, services, boundService, preloaded) {
     });
 }
 /**
- * The verification column. `readVerification` is one file read; 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.
+ * 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.
  *
- * An archived feature's record is frozen history (see `core/verify/record.ts`): archive
- * merged the feature's operations into the living openapi, so a re-derived
- * checklist can only mismatch — the record is reported as recorded, never
- * judged stale.
+ * 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) {
-    const v = await readVerification(f.dir);
-    if (v === null)
+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;
-    const stale = f.archived
-        ? false
-        : (await featureChecklist(docsDir, f.dir, f.id)).digest !== v.checklist;
-    const tally = tallyRecord(v);
     return {
-        state: stale ? "stale" : "recorded",
-        recorded: v.recorded,
-        verdict: verificationVerdict(tally, stale),
-        confirmed: tally.confirmed,
-        claims: tally.claims,
-        attested: tally.attested,
-        answered: confirmedProvenance(v.claims),
+        state: s.state,
+        recorded: s.recorded,
+        verdict: s.verdict,
+        confirmed: s.confirmed,
+        claims: s.claims,
+        attested: s.attested,
+        answered: s.answered,
     };
 }
-/* ------------------------------------------------------------------ */
-/* Text                                                                */
-/* ------------------------------------------------------------------ */
-/**
- * Fixed-width presence flags. `a` and `A` are deliberately the same letter in
- * two cases: the arch spec and the API are the two things a reader most often
- * mistakes for each other, and one is lowercase because it is optional.
- */
 //# sourceMappingURL=views.js.map

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

@@ -1 +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 { featureChecklist } from \"../../core/verify/checklist.js\";\nimport { readVerification } from \"../../core/verify/file.js\";\nimport { type AnsweredBy } from \"../../core/verify/answers.js\";\nimport {\n  confirmedProvenance,\n  tallyRecord,\n  type VerificationVerdict,\n  verificationVerdict,\n} 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  /** What stands between this service and the next rung, in fix order. */\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/* ------------------------------------------------------------------ */\n/* JSON                                                                */\n/* ------------------------------------------------------------------ */\n\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. `readVerification` is one file read; the checklist\n * is derived only when there is a record to judge — on a fleet-sized repo most\n * features have none, and deriving N checklists to print N dashes is the cost\n * that would get this column dropped.\n *\n * An archived feature's record is frozen history (see `core/verify/record.ts`): archive\n * merged the feature's operations into the living openapi, so a re-derived\n * checklist can only mismatch — the record is reported as recorded, never\n * judged stale.\n */\nexport async function featureVerification(\n  docsDir: DocsDir,\n  f: FeatureEntry,\n): Promise<VerificationCell | null> {\n  const v = await readVerification(f.dir);\n  if (v === null) return null;\n  const stale = f.archived\n    ? false\n    : (await featureChecklist(docsDir, f.dir, f.id)).digest !== v.checklist;\n  const tally = tallyRecord(v);\n  return {\n    state: stale ? \"stale\" : \"recorded\",\n    recorded: v.recorded,\n    verdict: verificationVerdict(tally, stale),\n    confirmed: tally.confirmed,\n    claims: tally.claims,\n    attested: tally.attested,\n    answered: confirmedProvenance(v.claims),\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * Fixed-width presence flags. `a` and `A` are deliberately the same letter in\n * two cases: the arch spec and the API are the two things a reader most often\n * mistakes for each other, and one is lowercase because it is optional.\n */\n"]}
+{"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 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"]}

package/dist/commands/mcp/dispatch.js

@@ -31,11 +31,13 @@ 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";
@@ -44,6 +46,7 @@ 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
@@ -93,13 +96,80 @@ export function captureConsole(sinks) {
 /** Commander output codes whose printed output is the point, not a usage failure. */
 const PASS_THROUGH = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
 /**
- * The scoped program, output routed into `sinks`. 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.
+ * 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, authoring = false) {
+function readProgram(sinks, registrars) {
     const program = new Command();
     program.name("loam");
     program.exitOverride();
@@ -107,49 +177,34 @@ function readProgram(sinks, authoring = false) {
         writeOut: (text) => sinks.stdout.push(text),
         writeErr: (text) => sinks.stderr.push(text),
     });
-    registerValidate(program);
-    registerStatus(program);
-    registerList(program);
-    registerShow(program);
-    registerDelta(program);
-    registerDiff(program);
-    registerExplore(program);
-    registerDependencies(program);
-    registerDoctor(program);
-    registerContext(program);
-    registerGate(program);
-    registerExplain(program);
-    // The two that read no config at all. They are here for the same reason they
-    // are in MCP_TOOLS: an agent meets `instructions` and `steps` BEFORE the
-    // repository is wired, and every generated skill's first line points at
-    // `loam instructions <workflow>`. This list and MCP_TOOLS are 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` now calls every advertised tool.
-    registerInstructions(program);
-    registerSteps(program);
-    if (authoring) {
-        registerNew(program);
-        registerRebase(program);
-        registerGherkin(program);
-        registerArchive(program);
-    }
+    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.
  */
-export async function runToolArgv(argv, authoring = false) {
+async function runToolArgv(argv, registrars) {
     const sinks = { stdout: [], stderr: [] };
     const previousExitCode = process.exitCode;
     const restoreConsole = captureConsole(sinks);
     process.exitCode = undefined;
     try {
-        await readProgram(sinks, authoring).parseAsync(["node", "loam", ...argv]);
+        await readProgram(sinks, registrars).parseAsync(["node", "loam", ...argv]);
     }
     catch (err) {
         if (err instanceof CommanderError) {

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

@@ -1 +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 { 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 { 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\";\n\nexport interface DispatchResult {\n  readonly stdout: string;\n  readonly stderr: string;\n  readonly code: number;\n}\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/**\n * The scoped program, output routed into `sinks`. configureOutput and\n * exitOverride are set BEFORE the register calls on purpose: commander copies\n * inherited settings onto a subcommand when it is created, so settings applied\n * after registration would leave every subcommand writing to the real stdout —\n * which for an MCP server is the protocol stream.\n */\nfunction readProgram(sinks: Sinks, authoring = false): 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  registerValidate(program);\n  registerStatus(program);\n  registerList(program);\n  registerShow(program);\n  registerDelta(program);\n  registerDiff(program);\n  registerExplore(program);\n  registerDependencies(program);\n  registerDoctor(program);\n  registerContext(program);\n  registerGate(program);\n  registerExplain(program);\n  // The two that read no config at all. They are here for the same reason they\n  // are in MCP_TOOLS: an agent meets `instructions` and `steps` BEFORE the\n  // repository is wired, and every generated skill's first line points at\n  // `loam instructions <workflow>`. This list and MCP_TOOLS are two copies of\n  // one roster, and nothing counted them against each other until a tool\n  // 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` now calls every advertised tool.\n  registerInstructions(program);\n  registerSteps(program);\n  if (authoring) {\n    registerNew(program);\n    registerRebase(program);\n    registerGherkin(program);\n    registerArchive(program);\n  }\n  return program;\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 */\nexport async function runToolArgv(\n  argv: readonly string[],\n  authoring = false,\n): Promise<DispatchResult> {\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, authoring).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"]}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../../src/commands/mcp/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,SAAS,EAAgB,MAAM,yBAAyB,CAAC;AAQlE;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG;IACrB,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO;IAChD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS;CAC1E,CAAC;AACX,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,OAAO,CAAU,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY;IACzC,MAAM,MAAM,GAAG,OAA6C,CAAC;IAC7D,MAAM,MAAM,GAAG,CAAC,IAAc,EAAE,EAAE,CAAC,CAAC,GAAG,KAAgB,EAAQ,EAAE;QAC/D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI;QACjC,CAAC,cAAc,EAAE,QAAQ,CAAC;QAC1B,CAAC,cAAc,EAAE,QAAQ,CAAC;KAClB,EAAE,CAAC;QACX,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,kEAAkE;YAClE,2DAA2D;YAC3D,IAAI,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,UAAU;gBAAE,SAAS;YACjD,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,EAAE;QACV,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,QAAQ;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;IAC/D,CAAC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,yBAAyB,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAKjG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAoB;IAC5C,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAC9B,CAAC,QAAQ,EAAE,cAAc,CAAC;IAC1B,CAAC,MAAM,EAAE,YAAY,CAAC;IACtB,CAAC,MAAM,EAAE,YAAY,CAAC;IACtB,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,MAAM,EAAE,YAAY,CAAC;IACtB,CAAC,SAAS,EAAE,eAAe,CAAC;IAC5B,CAAC,cAAc,EAAE,oBAAoB,CAAC;IACtC,CAAC,QAAQ,EAAE,cAAc,CAAC;IAC1B,CAAC,SAAS,EAAE,eAAe,CAAC;IAC5B,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,MAAM,EAAE,YAAY,CAAC;IACtB,CAAC,SAAS,EAAE,eAAe,CAAC;IAC5B,CAAC,cAAc,EAAE,oBAAoB,CAAC;IACtC,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,KAAK,EAAE,WAAW,CAAC;IACpB,CAAC,QAAQ,EAAE,cAAc,CAAC;IAC1B,CAAC,SAAS,EAAE,eAAe,CAAC;IAC5B,CAAC,SAAS,EAAE,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,OAAO,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjE,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;;YACpD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,wDAAwD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACvJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,KAAY,EAAE,UAAgC;IACjE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,OAAO,CAAC,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC;QACtB,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3C,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;KAC5C,CAAC,CAAC;IACH,KAAK,MAAM,QAAQ,IAAI,UAAU;QAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAK,GAAuB,SAAS;IAC9D,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,WAAW,CAAC,IAAuB,EAAE,UAAgC;IAClF,MAAM,KAAK,GAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAChD,MAAM,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC1C,MAAM,cAAc,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC7E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;YAClC,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,uEAAuE;gBACvE,wEAAwE;gBACxE,sEAAsE;gBACtE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;oBAAE,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;YACtE,CAAC;iBAAM,CAAC;gBACN,sEAAsE;gBACtE,qEAAqE;gBACrE,aAAa,CAAC,gBAAgB,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,qEAAqE;YACrE,mDAAmD;YACnD,aAAa,CAAC,UAAU,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;YAAS,CAAC;QACT,cAAc,EAAE,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,CAAC,QAAQ,GAAG,gBAAgB,CAAC;IACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC","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"]}