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

package/dist/cli.js

@@ -2,27 +2,36 @@
 import { Command, CommanderError } from "commander";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { registerInit } from "./commands/init.js";
-import { registerAdopt } from "./commands/adopt.js";
-import { registerList } from "./commands/list.js";
-import { registerNew } from "./commands/new.js";
-import { registerShow } from "./commands/show.js";
-import { registerStatus } from "./commands/status.js";
-import { registerDelta } from "./commands/delta.js";
-import { registerGherkin } from "./commands/gherkin.js";
-import { registerRebase } from "./commands/rebase.js";
-import { registerArchive } from "./commands/archive.js";
-import { registerUnarchive } from "./commands/unarchive.js";
-import { registerValidate } from "./commands/validate.js";
-import { registerVerify } from "./commands/verify.js";
-import { registerVouch } from "./commands/vouch.js";
+import { registerInit } from "./commands/init/init.js";
+import { registerAdopt } from "./commands/adopt/adopt.js";
+import { registerList } from "./commands/list/list.js";
+import { registerNew } from "./commands/new/new.js";
+import { registerSeed } from "./commands/seed/seed.js";
+import { registerShow } from "./commands/show/show.js";
+import { registerStatus } from "./commands/status/status.js";
+import { registerSubsystem } from "./commands/subsystem/subsystem.js";
+import { registerDelta } from "./commands/delta/delta.js";
+import { registerDiff } from "./commands/diff/diff.js";
+import { registerGherkin } from "./commands/gherkin/gherkin.js";
+import { registerRebase } from "./commands/rebase/rebase.js";
+import { registerArchive } from "./commands/archive/archive.js";
+import { registerUnarchive } from "./commands/unarchive/unarchive.js";
+import { registerValidate } from "./commands/validate/validate.js";
+import { registerVerify } from "./commands/verify/verify.js";
+import { registerVouch } from "./commands/vouch/vouch.js";
+import { registerGate } from "./commands/gate/gate.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerDependencies } from "./commands/dependencies.js";
+import { registerSteps } from "./commands/steps/steps.js";
 import { registerExplore } from "./commands/explore.js";
+import { registerContext } from "./commands/context/context.js";
+import { registerMcp } from "./commands/mcp/mcp.js";
+import { registerOpen } from "./commands/open.js";
 import { registerInstructions } from "./commands/instructions.js";
-import { registerMigrateOpenSpec } from "./commands/migrate-openspec.js";
-import { emitJsonError } from "./core/json.js";
-import { LOAM_VERSION } from "./core/version.js";
+import { registerExplain } from "./commands/explain/explain.js";
+import { registerMigrateOpenSpec } from "./commands/migrate-openspec/migrate-openspec.js";
+import { emitJsonError } from "./core/envelope/json.js";
+import { LOAM_VERSION } from "./core/envelope/version.js";
 /**
  * The whole CLI surface, as a program nobody has parsed yet.
  *
@@ -39,8 +48,12 @@ export function buildProgram() {
     const program = new Command();
     program
         .name("loam")
-        .description("Architecture-first spec framework for microservice fleets")
-        .version(LOAM_VERSION);
+        .description("Architecture-first semantic integrity and change governance for evolving software systems")
+        .version(LOAM_VERSION)
+        // The blank line is part of the attachment, not part of the text: commander
+        // writes this straight under the `Commands:` block, and two sentences flush
+        // against `help [command]` read as two more commands.
+        .addHelpText("after", `\n${HELP_EPILOG}`);
     // Make commander throw a CommanderError instead of process.exit()ing, so a
     // usage error (mistyped flag, unknown command) can still honour the envelope
     // invariant in the catch below instead of dying with an empty stdout.
@@ -49,10 +62,14 @@ export function buildProgram() {
     registerAdopt(program);
     registerList(program);
     registerExplore(program);
+    registerContext(program);
     registerNew(program);
+    registerSeed(program);
     registerShow(program);
     registerStatus(program);
+    registerSubsystem(program);
     registerDelta(program);
+    registerDiff(program);
     registerGherkin(program);
     registerRebase(program);
     registerArchive(program);
@@ -60,12 +77,89 @@ export function buildProgram() {
     registerValidate(program);
     registerVerify(program);
     registerVouch(program);
+    registerGate(program);
     registerDoctor(program);
     registerDependencies(program);
+    registerSteps(program);
+    registerMcp(program);
     registerInstructions(program);
+    registerExplain(program);
+    registerOpen(program);
     registerMigrateOpenSpec(program);
+    groupCommands(program);
     return program;
 }
+/**
+ * The two lines under the command list: where to start, and what to run when
+ * lost.
+ *
+ * {@link HELP_GROUPS} does nearly all of the orienting work — twenty-nine
+ * commands under seven headings, in the order of the work — but it stops one
+ * step short of the two facts a newcomer does not have. Nothing on the page
+ * said that `init` must run before any of the other twenty-eight, and nothing
+ * named the command that answers "what now"; the last thing a first
+ * `loam --help` printed was `help [command]`.
+ *
+ * Two lines, and no more, because the grouping is what does the work and a
+ * paragraph here would compete with it.
+ *
+ * Both lines name a command that PARSES, and that is not a style rule:
+ * `test/agent-commands-runnable.test.ts` takes this constant BY IMPORT and
+ * hands both invocations to the real program, exactly as it does the `init`
+ * first-hour lines. `loam init --create` is the form that works with no prior
+ * knowledge — bare `loam init` defaults `--docs` to a `.loam-docs` that does
+ * not exist yet and refuses, which is correct for a repo joining an existing
+ * docs repo and wrong as the first thing a newcomer is told to type.
+ */
+export const HELP_EPILOG = [
+    "New here? Run `loam init --create` first — every other command needs the docs repo it writes.",
+    "Lost? Run `loam doctor` — it prints the state, the resolved path, the finding code and a `fix:` line.",
+].join("\n");
+/**
+ * Which heading each command sits under in `loam --help`.
+ *
+ * The order is the order of the work: wire the repo, read the fleet, adopt what
+ * exists, change it, check it, ship it. It mirrors the six shipped workflow
+ * protocols (`loam instructions`) rather than inventing a second taxonomy, so a
+ * reader who has met one has met the other.
+ *
+ * Twenty-nine commands printed as one flat registration-ordered list tells a
+ * new reader nothing about which four to run first. NOTHING IS HIDDEN — a
+ * hidden command is a command an agent cannot discover, and every one of these
+ * still parses, still appears, and still carries the same flags. This is
+ * typography, not surface.
+ */
+const HELP_GROUPS = {
+    init: "Set up", seed: "Set up", doctor: "Set up", open: "Set up", mcp: "Set up",
+    list: "Read the fleet", status: "Read the fleet", show: "Read the fleet",
+    explore: "Read the fleet", context: "Read the fleet", dependencies: "Read the fleet",
+    explain: "Read the fleet", instructions: "Read the fleet", steps: "Read the fleet",
+    adopt: "Adopt what exists", vouch: "Adopt what exists",
+    new: "Change it", delta: "Change it", gherkin: "Change it", rebase: "Change it",
+    subsystem: "Change it",
+    validate: "Check it", diff: "Check it", verify: "Check it", gate: "Check it",
+    archive: "Ship it", unarchive: "Ship it",
+    "audit-openspec": "Migrate", "migrate-openspec": "Migrate",
+};
+/**
+ * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.
+ *
+ * The throw is the point. A thirtieth command added without a heading would
+ * otherwise land silently in an "unclassified" bucket at the bottom of the
+ * page, which is the drift this whole file's neighbours are written to prevent;
+ * `test/help-groups.test.ts` catches it at gate time, and this catches it the
+ * first time anybody runs the binary. Same discipline as
+ * `test/codes-drift.test.ts` applies to codes.
+ */
+function groupCommands(program) {
+    for (const command of program.commands) {
+        const group = HELP_GROUPS[command.name()];
+        if (group === undefined) {
+            throw new Error(`cli: command '${command.name()}' has no HELP_GROUPS heading — add one in src/cli.ts`);
+        }
+        command.helpGroup(group);
+    }
+}
 /** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */
 const PASS_THROUGH = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
 function main() {

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { Command, CommanderError } from \"commander\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { registerInit } from \"./commands/init.js\";\nimport { registerAdopt } from \"./commands/adopt.js\";\nimport { registerList } from \"./commands/list.js\";\nimport { registerNew } from \"./commands/new.js\";\nimport { registerShow } from \"./commands/show.js\";\nimport { registerStatus } from \"./commands/status.js\";\nimport { registerDelta } from \"./commands/delta.js\";\nimport { registerGherkin } from \"./commands/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase.js\";\nimport { registerArchive } from \"./commands/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive.js\";\nimport { registerValidate } from \"./commands/validate.js\";\nimport { registerVerify } from \"./commands/verify.js\";\nimport { registerVouch } from \"./commands/vouch.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerExplore } from \"./commands/explore.js\";\nimport { registerInstructions } from \"./commands/instructions.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec.js\";\nimport { emitJsonError } from \"./core/json.js\";\nimport { LOAM_VERSION } from \"./core/version.js\";\n\n/**\n * The whole CLI surface, as a program nobody has parsed yet.\n *\n * Exported because loam PRINTS commands — every `loam …` in AGENTS.md, in the\n * generated command and skill bodies, in a `doctor` finding's `fix` and in a\n * `status` next[] step is an instruction somebody (usually an agent) will type\n * back. The only way to prove one of those parses is to hand it to the program\n * that would receive it; a second copy of the registrations in a test agrees\n * with itself and with nothing else, which is exactly how\n * `Run \\`loam adopt <id>\\`` shipped as the first instruction a bound service\n * repo received. `test/agent-commands-runnable.test.ts` is the consumer.\n */\nexport function buildProgram(): Command {\n  const program = new Command();\n\n  program\n    .name(\"loam\")\n    .description(\"Architecture-first spec framework for microservice fleets\")\n    .version(LOAM_VERSION);\n\n  // Make commander throw a CommanderError instead of process.exit()ing, so a\n  // usage error (mistyped flag, unknown command) can still honour the envelope\n  // invariant in the catch below instead of dying with an empty stdout.\n  program.exitOverride();\n\n  registerInit(program);\n  registerAdopt(program);\n  registerList(program);\n  registerExplore(program);\n  registerNew(program);\n  registerShow(program);\n  registerStatus(program);\n  registerDelta(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerInstructions(program);\n  registerMigrateOpenSpec(program);\n\n  return program;\n}\n\n/** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */\nconst PASS_THROUGH = new Set([\"commander.help\", \"commander.helpDisplayed\", \"commander.version\"]);\n\nfunction main(): void {\n  const program = buildProgram();\n\n  // Set once a command's action actually runs: every subcommand declares its own\n  // `--json`, so past that point the parsed option is the authoritative answer.\n  let parsedJson: boolean | undefined;\n  program.hook(\"preAction\", (_thisCommand, actionCommand) => {\n    parsedJson = Boolean((actionCommand.optsWithGlobals() as { json?: boolean }).json);\n  });\n\n  /**\n   * Did this invocation ask for --json? Prefers the parsed option once an action\n   * has run; before that (commander usage errors abort mid-parse) falls back to\n   * scanning raw argv. The scan is a heuristic and cannot be made exact: a token\n   * spelled `--json` that was meant as an option VALUE (e.g. --title \"--json\")\n   * is indistinguishable from the flag in raw argv. It gets the common cases\n   * right: a `--json` token anywhere before a `--` terminator counts, and tokens\n   * after `--` never do.\n   */\n  const jsonRequested = (): boolean => {\n    if (parsedJson !== undefined) return parsedJson;\n    const argv = process.argv.slice(2);\n    const terminator = argv.indexOf(\"--\");\n    return (terminator === -1 ? argv : argv.slice(0, terminator)).includes(\"--json\");\n  };\n\n  program.parseAsync(process.argv).catch((err: unknown) => {\n    if (err instanceof CommanderError) {\n      // Help/version output was already written by commander — pass it through\n      // untouched with the exit code it always had.\n      //\n      // Anything else is a usage error (unknown option/command, missing or\n      // invalid argument). Commander has already printed its diagnostic to\n      // stderr, and that line stays: the invariant below is about stdout only.\n      if (!PASS_THROUGH.has(err.code) && jsonRequested()) {\n        emitJsonError(\"invalid-option\", err.message.replace(/^error: /, \"\"));\n      }\n      process.exitCode = err.exitCode;\n      return;\n    }\n    const message = err instanceof Error ? err.message : String(err);\n    // The envelope's one hard invariant is that stdout is JSON whenever --json\n    // was asked for — an unexpected throw must not be the exception to it.\n    if (jsonRequested()) {\n      emitJsonError(\"internal\", message);\n    } else {\n      console.error(message);\n      process.exitCode = 1;\n    }\n  });\n}\n\n/**\n * Was this file run, or merely imported? Realpath on both sides because the\n * installed entry point is reached through a symlink (`node_modules/.bin/loam`)\n * on every platform that has them, and a string compare against the link would\n * make the binary a no-op. A failure to resolve reads as \"not the entry\" only\n * for the import side; `process.argv[1]` that cannot be realpath'd is not a\n * loam invocation either.\n */\nfunction invokedDirectly(): boolean {\n  const entry = process.argv[1];\n  if (entry === undefined) return false;\n  try {\n    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));\n  } catch {\n    return false;\n  }\n}\n\nif (invokedDirectly()) main();\n"]}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { Command, CommanderError } from \"commander\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { registerInit } from \"./commands/init/init.js\";\nimport { registerAdopt } from \"./commands/adopt/adopt.js\";\nimport { registerList } from \"./commands/list/list.js\";\nimport { registerNew } from \"./commands/new/new.js\";\nimport { registerSeed } from \"./commands/seed/seed.js\";\nimport { registerShow } from \"./commands/show/show.js\";\nimport { registerStatus } from \"./commands/status/status.js\";\nimport { registerSubsystem } from \"./commands/subsystem/subsystem.js\";\nimport { registerDelta } from \"./commands/delta/delta.js\";\nimport { registerDiff } from \"./commands/diff/diff.js\";\nimport { registerGherkin } from \"./commands/gherkin/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase/rebase.js\";\nimport { registerArchive } from \"./commands/archive/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive/unarchive.js\";\nimport { registerValidate } from \"./commands/validate/validate.js\";\nimport { registerVerify } from \"./commands/verify/verify.js\";\nimport { registerVouch } from \"./commands/vouch/vouch.js\";\nimport { registerGate } from \"./commands/gate/gate.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerSteps } from \"./commands/steps/steps.js\";\nimport { registerExplore } from \"./commands/explore.js\";\nimport { registerContext } from \"./commands/context/context.js\";\nimport { registerMcp } from \"./commands/mcp/mcp.js\";\nimport { registerOpen } from \"./commands/open.js\";\nimport { registerInstructions } from \"./commands/instructions.js\";\nimport { registerExplain } from \"./commands/explain/explain.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec/migrate-openspec.js\";\nimport { emitJsonError } from \"./core/envelope/json.js\";\nimport { LOAM_VERSION } from \"./core/envelope/version.js\";\n\n/**\n * The whole CLI surface, as a program nobody has parsed yet.\n *\n * Exported because loam PRINTS commands — every `loam …` in AGENTS.md, in the\n * generated command and skill bodies, in a `doctor` finding's `fix` and in a\n * `status` next[] step is an instruction somebody (usually an agent) will type\n * back. The only way to prove one of those parses is to hand it to the program\n * that would receive it; a second copy of the registrations in a test agrees\n * with itself and with nothing else, which is exactly how\n * `Run \\`loam adopt <id>\\`` shipped as the first instruction a bound service\n * repo received. `test/agent-commands-runnable.test.ts` is the consumer.\n */\nexport function buildProgram(): Command {\n  const program = new Command();\n\n  program\n    .name(\"loam\")\n    .description(\"Architecture-first semantic integrity and change governance for evolving software systems\")\n    .version(LOAM_VERSION)\n    // The blank line is part of the attachment, not part of the text: commander\n    // writes this straight under the `Commands:` block, and two sentences flush\n    // against `help [command]` read as two more commands.\n    .addHelpText(\"after\", `\\n${HELP_EPILOG}`);\n\n  // Make commander throw a CommanderError instead of process.exit()ing, so a\n  // usage error (mistyped flag, unknown command) can still honour the envelope\n  // invariant in the catch below instead of dying with an empty stdout.\n  program.exitOverride();\n\n  registerInit(program);\n  registerAdopt(program);\n  registerList(program);\n  registerExplore(program);\n  registerContext(program);\n  registerNew(program);\n  registerSeed(program);\n  registerShow(program);\n  registerStatus(program);\n  registerSubsystem(program);\n  registerDelta(program);\n  registerDiff(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerGate(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerSteps(program);\n  registerMcp(program);\n  registerInstructions(program);\n  registerExplain(program);\n  registerOpen(program);\n  registerMigrateOpenSpec(program);\n\n  groupCommands(program);\n\n  return program;\n}\n\n/**\n * The two lines under the command list: where to start, and what to run when\n * lost.\n *\n * {@link HELP_GROUPS} does nearly all of the orienting work — twenty-nine\n * commands under seven headings, in the order of the work — but it stops one\n * step short of the two facts a newcomer does not have. Nothing on the page\n * said that `init` must run before any of the other twenty-eight, and nothing\n * named the command that answers \"what now\"; the last thing a first\n * `loam --help` printed was `help [command]`.\n *\n * Two lines, and no more, because the grouping is what does the work and a\n * paragraph here would compete with it.\n *\n * Both lines name a command that PARSES, and that is not a style rule:\n * `test/agent-commands-runnable.test.ts` takes this constant BY IMPORT and\n * hands both invocations to the real program, exactly as it does the `init`\n * first-hour lines. `loam init --create` is the form that works with no prior\n * knowledge — bare `loam init` defaults `--docs` to a `.loam-docs` that does\n * not exist yet and refuses, which is correct for a repo joining an existing\n * docs repo and wrong as the first thing a newcomer is told to type.\n */\nexport const HELP_EPILOG = [\n  \"New here? Run `loam init --create` first — every other command needs the docs repo it writes.\",\n  \"Lost? Run `loam doctor` — it prints the state, the resolved path, the finding code and a `fix:` line.\",\n].join(\"\\n\");\n\n/**\n * Which heading each command sits under in `loam --help`.\n *\n * The order is the order of the work: wire the repo, read the fleet, adopt what\n * exists, change it, check it, ship it. It mirrors the six shipped workflow\n * protocols (`loam instructions`) rather than inventing a second taxonomy, so a\n * reader who has met one has met the other.\n *\n * Twenty-nine commands printed as one flat registration-ordered list tells a\n * new reader nothing about which four to run first. NOTHING IS HIDDEN — a\n * hidden command is a command an agent cannot discover, and every one of these\n * still parses, still appears, and still carries the same flags. This is\n * typography, not surface.\n */\nconst HELP_GROUPS: Record<string, string> = {\n  init: \"Set up\", seed: \"Set up\", doctor: \"Set up\", open: \"Set up\", mcp: \"Set up\",\n  list: \"Read the fleet\", status: \"Read the fleet\", show: \"Read the fleet\",\n  explore: \"Read the fleet\", context: \"Read the fleet\", dependencies: \"Read the fleet\",\n  explain: \"Read the fleet\", instructions: \"Read the fleet\", steps: \"Read the fleet\",\n  adopt: \"Adopt what exists\", vouch: \"Adopt what exists\",\n  new: \"Change it\", delta: \"Change it\", gherkin: \"Change it\", rebase: \"Change it\",\n  subsystem: \"Change it\",\n  validate: \"Check it\", diff: \"Check it\", verify: \"Check it\", gate: \"Check it\",\n  archive: \"Ship it\", unarchive: \"Ship it\",\n  \"audit-openspec\": \"Migrate\", \"migrate-openspec\": \"Migrate\",\n};\n\n/**\n * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.\n *\n * The throw is the point. A thirtieth command added without a heading would\n * otherwise land silently in an \"unclassified\" bucket at the bottom of the\n * page, which is the drift this whole file's neighbours are written to prevent;\n * `test/help-groups.test.ts` catches it at gate time, and this catches it the\n * first time anybody runs the binary. Same discipline as\n * `test/codes-drift.test.ts` applies to codes.\n */\nfunction groupCommands(program: Command): void {\n  for (const command of program.commands) {\n    const group = HELP_GROUPS[command.name()];\n    if (group === undefined) {\n      throw new Error(`cli: command '${command.name()}' has no HELP_GROUPS heading — add one in src/cli.ts`);\n    }\n    command.helpGroup(group);\n  }\n}\n\n/** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */\nconst PASS_THROUGH = new Set([\"commander.help\", \"commander.helpDisplayed\", \"commander.version\"]);\n\nfunction main(): void {\n  const program = buildProgram();\n\n  // Set once a command's action actually runs: every subcommand declares its own\n  // `--json`, so past that point the parsed option is the authoritative answer.\n  let parsedJson: boolean | undefined;\n  program.hook(\"preAction\", (_thisCommand, actionCommand) => {\n    parsedJson = Boolean((actionCommand.optsWithGlobals() as { json?: boolean }).json);\n  });\n\n  /**\n   * Did this invocation ask for --json? Prefers the parsed option once an action\n   * has run; before that (commander usage errors abort mid-parse) falls back to\n   * scanning raw argv. The scan is a heuristic and cannot be made exact: a token\n   * spelled `--json` that was meant as an option VALUE (e.g. --title \"--json\")\n   * is indistinguishable from the flag in raw argv. It gets the common cases\n   * right: a `--json` token anywhere before a `--` terminator counts, and tokens\n   * after `--` never do.\n   */\n  const jsonRequested = (): boolean => {\n    if (parsedJson !== undefined) return parsedJson;\n    const argv = process.argv.slice(2);\n    const terminator = argv.indexOf(\"--\");\n    return (terminator === -1 ? argv : argv.slice(0, terminator)).includes(\"--json\");\n  };\n\n  program.parseAsync(process.argv).catch((err: unknown) => {\n    if (err instanceof CommanderError) {\n      // Help/version output was already written by commander — pass it through\n      // untouched with the exit code it always had.\n      //\n      // Anything else is a usage error (unknown option/command, missing or\n      // invalid argument). Commander has already printed its diagnostic to\n      // stderr, and that line stays: the invariant below is about stdout only.\n      if (!PASS_THROUGH.has(err.code) && jsonRequested()) {\n        emitJsonError(\"invalid-option\", err.message.replace(/^error: /, \"\"));\n      }\n      process.exitCode = err.exitCode;\n      return;\n    }\n    const message = err instanceof Error ? err.message : String(err);\n    // The envelope's one hard invariant is that stdout is JSON whenever --json\n    // was asked for — an unexpected throw must not be the exception to it.\n    if (jsonRequested()) {\n      emitJsonError(\"internal\", message);\n    } else {\n      console.error(message);\n      process.exitCode = 1;\n    }\n  });\n}\n\n/**\n * Was this file run, or merely imported? Realpath on both sides because the\n * installed entry point is reached through a symlink (`node_modules/.bin/loam`)\n * on every platform that has them, and a string compare against the link would\n * make the binary a no-op. A failure to resolve reads as \"not the entry\" only\n * for the import side; `process.argv[1]` that cannot be realpath'd is not a\n * loam invocation either.\n */\nfunction invokedDirectly(): boolean {\n  const entry = process.argv[1];\n  if (entry === undefined) return false;\n  try {\n    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));\n  } catch {\n    return false;\n  }\n}\n\nif (invokedDirectly()) main();\n"]}

package/dist/commands/adopt/adopt.js

@@ -0,0 +1,209 @@
+import { closeIds } from "../../core/c4/arch.js";
+import { loadConfig } from "../../core/envelope/config.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { emitJson, fail, NO_SERVICE_MESSAGE, repoPath, reportNoConfig } from "../../core/envelope/json.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { listFleetTree, listServices } from "../../core/repo/repo.js";
+import { findInTree, nearestTreeNames } from "../../core/repo/tree/find.js";
+import { servicePathsUnder } from "../../core/repo/paths.js";
+import { serviceBrief } from "../../core/brief/brief.js";
+import { docsRepoReady } from "../policy/gate.js";
+import { render } from "./render.js";
+/**
+ * Where `--subsystem` points the brief: the target directory inside the
+ * group for a service that does not exist yet, or nothing — with a warning —
+ * for one that already does, because adopt writes nothing and MOVES nothing
+ * (`loam subsystem move` is the verb that relocates). An unknown subsystem
+ * refuses with close-name hints, exactly as a mistyped service id warns: a
+ * typo here would brief a whole baseline into a group nobody has.
+ */
+async function subsystemTarget(docsDir, name, service, json) {
+    const tree = await listFleetTree(docsDir);
+    const hit = findInTree(tree, name);
+    if (hit === null) {
+        const close = nearestTreeNames(name, tree.subsystems.map((s) => s.name));
+        fail(json, "unknown-target", `No subsystem '${name}' in the tree.` +
+            (close.length > 0 ? ` Close names: ${close.join(", ")}.` : " `loam subsystem new` creates one; `loam subsystem list` shows what exists."));
+        return null;
+    }
+    if (hit.kind === "service") {
+        fail(json, "invalid-option", `--subsystem names the service '${name}' — a service never contains other services.`);
+        return null;
+    }
+    const filed = tree.services.find((s) => s.id === service);
+    if (filed !== undefined) {
+        return {
+            warning: `'${service}' already exists at ${repoPath(docsDir, filed.dir)}/ — --subsystem does not move a service ` +
+                `(\`loam subsystem move ${service} --into ${name}\` does), so the brief targets its existing directory.`,
+        };
+    }
+    return { at: servicePathsUnder(hit.subsystem.dir, service) };
+}
+/**
+ * What is suspicious about this invocation without being wrong.
+ *
+ * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it
+ * is the whole point of the command — so neither of these can be a refusal.
+ * But both used to be silent, and both produce the same outcome: a complete,
+ * validating baseline written under a directory name nobody meant. `adopt
+ * --service biling-service` briefed a phantom service beside the real
+ * `billing-service`, and an agent following the brief created it.
+ */
+async function invocationWarnings(docsDir, service, bound) {
+    const warnings = [];
+    if (bound !== undefined && bound !== service) {
+        warnings.push(`This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +
+            `That is legal — one repo can author another service's baseline — but \`loam vouch\`, ` +
+            `\`loam gherkin\` and \`loam verify --service\` all bind to '${bound}' here, so the baseline ` +
+            `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +
+            `adopt from '${service}''s own repository.`);
+    }
+    // "Does the service already exist" is enumeration MEMBERSHIP, not an
+    // existsSync of services/<id>/ at the root: a service filed into a subsystem
+    // exists wherever the tree walk found it, and the root probe read every
+    // filed service as new — the near-miss warning then accused its own name of
+    // being a typo. One enumeration answers both this and the near-miss list;
+    // a repo that refuses enumeration is a different problem, reported by every
+    // other command, and adopt has nothing useful to add to it.
+    let known = [];
+    try {
+        known = (await listServices(docsDir)).map((s) => s.id);
+    }
+    catch (err) {
+        if (!(err instanceof DocsRepoUnavailableError))
+            throw err;
+        return warnings;
+    }
+    if (known.includes(service))
+        return warnings;
+    const close = closeIds(service, known);
+    if (close.length > 0) {
+        warnings.push(`There is no services/${service}/ yet, but the docs repo already has ${close.join(", ")}. ` +
+            `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +
+            `writes a complete, validating baseline for a service that does not exist, and nothing ` +
+            `downstream can tell it from a real one. If it really is a new service, this is expected.`);
+    }
+    return warnings;
+}
+/**
+ * The half of the brief that is computed from THIS repository, for THIS
+ * service — what `--targets` keeps.
+ *
+ * Everything omitted is a module-level constant: `walk` and `walkClose` are the
+ * code-reading order, `frontmatter` the field rules, `checks` the named checks,
+ * `unchecked` the statements of what nothing checks, `rule` the never-overwrite
+ * instruction. None of them is a function of the service, so a fleet-wide
+ * adoption pays for the same bytes once per service — measured on the shipped
+ * example fleet, about 23 KB of the 42 KB brief, which is four fifths of what
+ * an agent reads and none of what it could not have read once.
+ *
+ * The keys are picked one by one rather than deleted from a rest — a field
+ * added to `Brief` later must land in the DEFAULT payload and stay out of this
+ * one until somebody decides it varies by service. Getting that wrong the
+ * other way round is how a narrowing flag silently becomes the full brief
+ * again.
+ */
+function narrowed(b) {
+    return { service: b.service, docsDir: b.docsDir, path: b.path, targets: b.targets, landscape: b.landscape };
+}
+/**
+ * The `full` pointer: the run that carries what `--targets` dropped, and the
+ * reason it is worth making.
+ *
+ * It is REQUIRED in the narrowed envelope, and the second sentence is why. The
+ * unchecked list is loam shipping, in the binary, the statements of what no
+ * check will ever tell you — the one thing standing between a green
+ * `loam validate` and being read as more than it means. Merely leaving it out
+ * would not read as "omitted for brevity"; it would read as "there is no such
+ * list", which is the failure `src/core/brief/unchecked.ts` exists to prevent
+ * and the one promise the brief keeps that no validator supplies. So the
+ * narrowed view never hides it — it says how many there are and where to read
+ * them.
+ *
+ * Every count comes off the brief that was just assembled, never off a number
+ * typed here: a literal would be correct until the next check is added and
+ * wrong silently forever after.
+ */
+function fullBrief(b) {
+    return (`loam adopt --service ${b.service} --json — everything this view leaves out: the ` +
+        `${b.walk.length}-stop code walk, the frontmatter rules, the ${b.checks.length} named checks, ` +
+        `and the ${b.unchecked.length} statements of what nothing checks. None of it varies by service, ` +
+        `so run it once for the system rather than once per service — but do run it: those ` +
+        `${b.unchecked.length} statements are the only place loam says where its checking stops.`);
+}
+export function registerAdopt(program) {
+    program
+        .command("adopt")
+        .description("Brief an agent to write one service's baseline docs from its code, and say what will be checked")
+        .option("--service <id>", "service to adopt (defaults to the configured service)")
+        .option("--subsystem <name>", "file the new service's baseline into this subsystem instead of the services/ root")
+        .option("--targets", "narrow the brief to what varies by service; the walk, the checks and the unchecked list are omitted, and a `full` field names the run that carries them")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts) => {
+        const json = opts.json === true;
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const config = loaded.config;
+        // This command writes nothing, but it briefs an agent to write a whole
+        // baseline — so a docsDir that does not exist is not a harmless read: it
+        // hands over eight target paths under a directory nobody has, at exit 0,
+        // with the near-miss warning below silently switched off (listServices
+        // throws, `invocationWarnings` swallows it and returns nothing). The same
+        // refusal every enumerating command owes; see docs-repo-gate.ts.
+        //
+        // `docs`, not `services`: a docs repo that has no services/ yet is exactly
+        // the repo adopt exists to fill, and refusing there would refuse the
+        // command's own first use.
+        if (!docsRepoReady(json, config.docsDir, "docs"))
+            return;
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+            return;
+        }
+        // The id becomes `services/<id>/` in a shared repo, so it goes through the
+        // one grammar before anything interpolates it into a path.
+        try {
+            assertServiceId(service, opts.service === undefined ? "service (loam.json)" : "--service");
+        }
+        catch (err) {
+            if (!(err instanceof InvalidIdError))
+                throw err;
+            fail(json, "invalid-option", err.message);
+            return;
+        }
+        const warnings = await invocationWarnings(config.docsDir, service, config.service);
+        let at;
+        if (opts.subsystem !== undefined) {
+            const target = await subsystemTarget(config.docsDir, opts.subsystem, service, json);
+            if (target === null)
+                return;
+            at = target.at;
+            if (target.warning !== undefined)
+                warnings.push(target.warning);
+        }
+        const brief = await serviceBrief(config.docsDir, service, at);
+        // Computed only under `--targets`, and it is what makes the narrowing
+        // legible from inside the payload: a consumer holding `full` knows there
+        // is more and what it is, and a consumer without it is holding all of it.
+        // The narrowing happens HERE, by omission, so the brief itself is
+        // unchanged and every field it can produce still exists.
+        const full = opts.targets === true ? fullBrief(brief) : undefined;
+        if (json) {
+            // Two separate emits rather than one conditional spread: the default
+            // payload is a frozen contract, and it must stay the same bytes in the
+            // same order whatever this flag grows into.
+            if (full !== undefined) {
+                emitJson({ command: "adopt", ...narrowed(brief), warnings, full });
+                return;
+            }
+            emitJson({ command: "adopt", ...brief, warnings });
+            return;
+        }
+        render(brief, warnings, full);
+    });
+}
+//# sourceMappingURL=adopt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../src/commands/adopt/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { closeIds } from \"../../core/c4/arch.js\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { InvalidIdError, assertServiceId, type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { emitJson, fail, NO_SERVICE_MESSAGE, repoPath, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listFleetTree, listServices } from \"../../core/repo/repo.js\";\nimport { findInTree, nearestTreeNames } from \"../../core/repo/tree/find.js\";\nimport { servicePathsUnder, type ServicePaths } from \"../../core/repo/paths.js\";\nimport { serviceBrief, type Brief } from \"../../core/brief/brief.js\";\nimport { docsRepoReady } from \"../policy/gate.js\";\nimport { render } from \"./render.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\n/**\n * `loam adopt` — the bootstrap flow, as a contract with an agent.\n *\n * It emits a BRIEF, not an extraction: the artifacts one service's baseline is\n * made of, the grammar each has to be written in, what the fleet already says\n * about the service, the checks that follow, and the checks that do not exist.\n * The agent reads the code; loam states the work and then judges the result.\n *\n * It writes nothing. A command that produced the documents it is asking for\n * would be doing the half of the job it exists to hand over.\n */\n\ninterface AdoptOptions {\n  service?: string;\n  subsystem?: string;\n  targets?: boolean;\n  json?: boolean;\n}\n\n/**\n * Where `--subsystem` points the brief: the target directory inside the\n * group for a service that does not exist yet, or nothing — with a warning —\n * for one that already does, because adopt writes nothing and MOVES nothing\n * (`loam subsystem move` is the verb that relocates). An unknown subsystem\n * refuses with close-name hints, exactly as a mistyped service id warns: a\n * typo here would brief a whole baseline into a group nobody has.\n */\nasync function subsystemTarget(\n  docsDir: DocsDir,\n  name: string,\n  service: PathableService,\n  json: boolean,\n): Promise<{ at?: ServicePaths; warning?: string } | null> {\n  const tree = await listFleetTree(docsDir);\n  const hit = findInTree(tree, name);\n  if (hit === null) {\n    const close = nearestTreeNames(name, tree.subsystems.map((s) => s.name));\n    fail(\n      json,\n      \"unknown-target\",\n      `No subsystem '${name}' in the tree.` +\n        (close.length > 0 ? ` Close names: ${close.join(\", \")}.` : \" `loam subsystem new` creates one; `loam subsystem list` shows what exists.\"),\n    );\n    return null;\n  }\n  if (hit.kind === \"service\") {\n    fail(json, \"invalid-option\", `--subsystem names the service '${name}' — a service never contains other services.`);\n    return null;\n  }\n  const filed = tree.services.find((s) => s.id === service);\n  if (filed !== undefined) {\n    return {\n      warning:\n        `'${service}' already exists at ${repoPath(docsDir, filed.dir)}/ — --subsystem does not move a service ` +\n        `(\\`loam subsystem move ${service} --into ${name}\\` does), so the brief targets its existing directory.`,\n    };\n  }\n  return { at: servicePathsUnder(hit.subsystem.dir, service) };\n}\n\n/**\n * What is suspicious about this invocation without being wrong.\n *\n * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it\n * is the whole point of the command — so neither of these can be a refusal.\n * But both used to be silent, and both produce the same outcome: a complete,\n * validating baseline written under a directory name nobody meant. `adopt\n * --service biling-service` briefed a phantom service beside the real\n * `billing-service`, and an agent following the brief created it.\n */\nasync function invocationWarnings(\n  docsDir: DocsDir,\n  service: PathableService,\n  bound: string | undefined,\n): Promise<string[]> {\n  const warnings: string[] = [];\n\n  if (bound !== undefined && bound !== service) {\n    warnings.push(\n      `This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +\n        `That is legal — one repo can author another service's baseline — but \\`loam vouch\\`, ` +\n        `\\`loam gherkin\\` and \\`loam verify --service\\` all bind to '${bound}' here, so the baseline ` +\n        `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +\n        `adopt from '${service}''s own repository.`,\n    );\n  }\n\n  // \"Does the service already exist\" is enumeration MEMBERSHIP, not an\n  // existsSync of services/<id>/ at the root: a service filed into a subsystem\n  // exists wherever the tree walk found it, and the root probe read every\n  // filed service as new — the near-miss warning then accused its own name of\n  // being a typo. One enumeration answers both this and the near-miss list;\n  // a repo that refuses enumeration is a different problem, reported by every\n  // other command, and adopt has nothing useful to add to it.\n  let known: string[] = [];\n  try {\n    known = (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return warnings;\n  }\n  if (known.includes(service)) return warnings;\n  const close = closeIds(service, known);\n  if (close.length > 0) {\n    warnings.push(\n      `There is no services/${service}/ yet, but the docs repo already has ${close.join(\", \")}. ` +\n        `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +\n        `writes a complete, validating baseline for a service that does not exist, and nothing ` +\n        `downstream can tell it from a real one. If it really is a new service, this is expected.`,\n    );\n  }\n  return warnings;\n}\n\n/**\n * The half of the brief that is computed from THIS repository, for THIS\n * service — what `--targets` keeps.\n *\n * Everything omitted is a module-level constant: `walk` and `walkClose` are the\n * code-reading order, `frontmatter` the field rules, `checks` the named checks,\n * `unchecked` the statements of what nothing checks, `rule` the never-overwrite\n * instruction. None of them is a function of the service, so a fleet-wide\n * adoption pays for the same bytes once per service — measured on the shipped\n * example fleet, about 23 KB of the 42 KB brief, which is four fifths of what\n * an agent reads and none of what it could not have read once.\n *\n * The keys are picked one by one rather than deleted from a rest — a field\n * added to `Brief` later must land in the DEFAULT payload and stay out of this\n * one until somebody decides it varies by service. Getting that wrong the\n * other way round is how a narrowing flag silently becomes the full brief\n * again.\n */\nfunction narrowed(b: Brief): Pick<Brief, \"service\" | \"docsDir\" | \"path\" | \"targets\" | \"landscape\"> {\n  return { service: b.service, docsDir: b.docsDir, path: b.path, targets: b.targets, landscape: b.landscape };\n}\n\n/**\n * The `full` pointer: the run that carries what `--targets` dropped, and the\n * reason it is worth making.\n *\n * It is REQUIRED in the narrowed envelope, and the second sentence is why. The\n * unchecked list is loam shipping, in the binary, the statements of what no\n * check will ever tell you — the one thing standing between a green\n * `loam validate` and being read as more than it means. Merely leaving it out\n * would not read as \"omitted for brevity\"; it would read as \"there is no such\n * list\", which is the failure `src/core/brief/unchecked.ts` exists to prevent\n * and the one promise the brief keeps that no validator supplies. So the\n * narrowed view never hides it — it says how many there are and where to read\n * them.\n *\n * Every count comes off the brief that was just assembled, never off a number\n * typed here: a literal would be correct until the next check is added and\n * wrong silently forever after.\n */\nfunction fullBrief(b: Brief): string {\n  return (\n    `loam adopt --service ${b.service} --json — everything this view leaves out: the ` +\n    `${b.walk.length}-stop code walk, the frontmatter rules, the ${b.checks.length} named checks, ` +\n    `and the ${b.unchecked.length} statements of what nothing checks. None of it varies by service, ` +\n    `so run it once for the system rather than once per service — but do run it: those ` +\n    `${b.unchecked.length} statements are the only place loam says where its checking stops.`\n  );\n}\n\nexport function registerAdopt(program: Command): void {\n  program\n    .command(\"adopt\")\n    .description(\"Brief an agent to write one service's baseline docs from its code, and say what will be checked\")\n    .option(\"--service <id>\", \"service to adopt (defaults to the configured service)\")\n    .option(\"--subsystem <name>\", \"file the new service's baseline into this subsystem instead of the services/ root\")\n    .option(\"--targets\", \"narrow the brief to what varies by service; the walk, the checks and the unchecked list are omitted, and a `full` field names the run that carries them\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: AdoptOptions) => {\n      const json = opts.json === true;\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      // This command writes nothing, but it briefs an agent to write a whole\n      // baseline — so a docsDir that does not exist is not a harmless read: it\n      // hands over eight target paths under a directory nobody has, at exit 0,\n      // with the near-miss warning below silently switched off (listServices\n      // throws, `invocationWarnings` swallows it and returns nothing). The same\n      // refusal every enumerating command owes; see docs-repo-gate.ts.\n      //\n      // `docs`, not `services`: a docs repo that has no services/ yet is exactly\n      // the repo adopt exists to fill, and refusing there would refuse the\n      // command's own first use.\n      if (!docsRepoReady(json, config.docsDir, \"docs\")) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      // The id becomes `services/<id>/` in a shared repo, so it goes through the\n      // one grammar before anything interpolates it into a path.\n      try {\n        assertServiceId(service, opts.service === undefined ? \"service (loam.json)\" : \"--service\");\n      } catch (err) {\n        if (!(err instanceof InvalidIdError)) throw err;\n        fail(json, \"invalid-option\", err.message);\n        return;\n      }\n\n      const warnings = await invocationWarnings(config.docsDir, service, config.service);\n      let at: ServicePaths | undefined;\n      if (opts.subsystem !== undefined) {\n        const target = await subsystemTarget(config.docsDir, opts.subsystem, service, json);\n        if (target === null) return;\n        at = target.at;\n        if (target.warning !== undefined) warnings.push(target.warning);\n      }\n      const brief = await serviceBrief(config.docsDir, service, at);\n      // Computed only under `--targets`, and it is what makes the narrowing\n      // legible from inside the payload: a consumer holding `full` knows there\n      // is more and what it is, and a consumer without it is holding all of it.\n      // The narrowing happens HERE, by omission, so the brief itself is\n      // unchanged and every field it can produce still exists.\n      const full = opts.targets === true ? fullBrief(brief) : undefined;\n      if (json) {\n        // Two separate emits rather than one conditional spread: the default\n        // payload is a frozen contract, and it must stay the same bytes in the\n        // same order whatever this flag grows into.\n        if (full !== undefined) {\n          emitJson({ command: \"adopt\", ...narrowed(brief), warnings, full });\n          return;\n        }\n        emitJson({ command: \"adopt\", ...brief, warnings });\n        return;\n      }\n      render(brief, warnings, full);\n    });\n}\n"]}