@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/bin.ts

@@ -1,9 +1,9 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 /**
  * CLI entry point for `pragma` (v2 kernel).
  *
  * The composition root. Ordered early exits keep the hot paths minimal and
- * side-effect-free: `mcp` serves over stdio (D9); `__complete` resolves
+ * side-effect-free: `mcp serve` serves over stdio (D9); `__complete` resolves
  * completions storelessly *before* first-run so the greeting never leaks into a
  * shell buffer; `--version` prints and exits. Otherwise: parse global flags,
  * reject a bad `--format`, run first-run onboarding, then build the Commander
@@ -14,13 +14,39 @@
  */
 
 import type { Command } from "commander";
-import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "./constants.js";
+import {
+  BIN_NAME,
+  DETAIL_LEVELS,
+  ISSUES_URL,
+  PROGRAM_DESCRIPTION,
+  VERSION,
+} from "./constants.js";
+
+/**
+ * The flags a bare invocation answers itself. `--version` returns earlier; the
+ * help form falls through to the front door, which IS its answer — so the
+ * unknown-flag guard must not mistake it for a typo. One spelling per flag:
+ * no `-h`/`-v` shorts exist anywhere on the surface.
+ */
+const ROOT_FLAGS = new Set(["--help", "--version"]);
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
 
-  // 1. MCP server entry (D9) — `pragma mcp` serves over stdio.
-  if (argv[0] === "mcp") {
+  // 1. MCP server entry (D9) — `pragma mcp serve` serves over stdio.
+  //    The exit is NARROW on purpose: argv must be EXACTLY those two tokens.
+  //    The server's startup has to stay minimal and stdio-pure (no first-run
+  //    banner, no config read, nothing on stdout but JSON-RPC), which is what
+  //    this shortcut buys — but the noun itself is ordinary grammar, so
+  //    `pragma mcp`, `pragma mcp --help` and `pragma mcp serve --help` fall
+  //    through to the same help machinery every other noun uses, and root
+  //    help's promise that `--help` works on any command becomes true.
+  //    Matching on a PREFIX would extend that purity budget to malformed argv
+  //    it was never bought for: `mcp serve extra` would serve instead of
+  //    letting Commander reject the excess argument, and `mcp serve --version`
+  //    would serve instead of answering the global flag. Anything suffixed
+  //    falls through to the ordinary grammar, which owns both jobs.
+  if (argv.length === 2 && argv[0] === "mcp" && argv[1] === "serve") {
     const [{ serveMcp }, { capabilities }] = await Promise.all([
       import("./kernel/project/mcp/serve.js"),
       import("./capabilities/index.js"),
@@ -29,7 +55,8 @@ async function main(): Promise<void> {
     return;
   }
 
-  // 2. Completion resolver — storeless, before first-run so no banner leaks.
+  // 2. Completion resolver — storeless, and reached before anything that could
+  //    print, so a completion request is never polluted by a hint.
   //    Protocol: `pragma __complete -- <words…>`; the first `--` is framing
   //    (tolerated absent) and is stripped here so a later bare `--` stays the
   //    user's end-of-options. Candidates go to stdout newline-delimited (zero
@@ -60,72 +87,138 @@ async function main(): Promise<void> {
     return;
   }
 
-  const { parseGlobalFlags, readRawFormat, stripGlobalFlags } = await import(
-    "./kernel/project/cli/globalFlags.js"
-  );
+  const {
+    findValuedVerbose,
+    parseGlobalFlags,
+    readRawDetail,
+    readRawFormat,
+    stripGlobalFlags,
+  } = await import("./kernel/project/cli/globalFlags.js");
   const globalFlags = parseGlobalFlags(argv);
 
   // 3. `--version` is global — print and exit wherever it appears.
-  if (argv.some((arg) => arg === "--version" || arg === "-v")) {
+  if (argv.some((arg) => arg === "--version")) {
     process.stdout.write(`${VERSION}\n`);
     return;
   }
 
-  // 4. Reject an unknown `--format` early (help still prints regardless).
-  const explicitHelp = argv.some((arg) => arg === "--help" || arg === "-h");
-  const rawFormat = readRawFormat(argv);
-  if (
-    !explicitHelp &&
-    rawFormat !== undefined &&
-    !["plain", "llm", "json", "text"].includes(rawFormat)
-  ) {
-    const [
-      { PragmaError },
-      { renderErrorPlain, renderErrorJson },
-      { mapExitCode },
-    ] = await Promise.all([
-      import("./kernel/error/PragmaError.js"),
-      import("./kernel/error/renderError.js"),
-      import("./kernel/project/cli/exitCodes.js"),
-    ]);
-    const error = PragmaError.invalidInput("format", rawFormat, {
-      validOptions: ["plain", "llm", "json"],
-    });
-    const rendered =
-      globalFlags.format === "json"
-        ? renderErrorJson(error)
-        : renderErrorPlain(error);
-    process.stderr.write(`${rendered}\n`);
-    process.exitCode = mapExitCode(error.code);
-    return;
-  }
-
-  // 5. First-run onboarding (stderr-only, failure-tolerant). Skipped on the
-  //    side-effect-free help path — `--help` here; `mcp`, `__complete`, and
-  //    `--version` already returned above — so help never seeds state.
+  // 4. Reject a bad global-flag value early (help still prints regardless):
+  //    an unknown `--format`, an unrecognized `--detail` level (which used to
+  //    be dropped silently — the same defect class as a filter that
+  //    evaporates), and a valued `--verbose=<x>` (the flag takes no value;
+  //    accepting-and-ignoring one would be a silent no-op).
+  const explicitHelp = argv.some((arg) => arg === "--help");
+  const jsonMode = globalFlags.format === "json";
   if (!explicitHelp) {
-    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
-    await ensureFirstRun();
+    const rawFormat = readRawFormat(argv);
+    if (
+      rawFormat !== undefined &&
+      !["plain", "llm", "json"].includes(rawFormat)
+    ) {
+      await rejectGlobalValue(
+        "format",
+        rawFormat,
+        ["plain", "llm", "json"],
+        jsonMode,
+      );
+      return;
+    }
+    const rawDetail = readRawDetail(argv);
+    if (
+      rawDetail !== undefined &&
+      !(DETAIL_LEVELS as readonly string[]).includes(rawDetail)
+    ) {
+      await rejectGlobalValue(
+        "detail",
+        rawDetail,
+        [...DETAIL_LEVELS],
+        jsonMode,
+      );
+      return;
+    }
+    const valuedVerbose = findValuedVerbose(argv);
+    if (valuedVerbose !== undefined) {
+      const { PragmaError } = await import("./kernel/error/PragmaError.js");
+      await renderStartupError(
+        new PragmaError({
+          code: "INVALID_INPUT",
+          message: `\`--verbose\` takes no value; \`${valuedVerbose}\` is not a flag of this program.`,
+          recovery: { message: "Use `--verbose` on its own." },
+        }),
+        jsonMode,
+      );
+      return;
+    }
   }
 
-  // 6. Build the command tree.
-  const [{ buildProgram }, { capabilities }] = await Promise.all([
-    import("./kernel/project/cli/buildProgram.js"),
-    import("./capabilities/index.js"),
-  ]);
+  // 5. Load the capability registry — the command tree's data. Commander and
+  //    the program builder are NOT loaded yet: the bare-invocation branch
+  //    below answers `--help` and the front door from the registry alone, so
+  //    the help fast path never pays for the parser it will not run.
+  const { capabilities } = await import("./capabilities/index.js");
   const args = stripGlobalFlags(argv);
 
-  // 7. A bare invocation (no command token — argv empty or only global flags)
+  // 6. A bare invocation (no command token — argv empty or only global flags)
   //    prints the curated front door instead of exiting silently. Uses the
   //    static capabilities — the front door never reads config or stories.
   if (!args.some((arg) => !arg.startsWith("-"))) {
+    // `args` is argv with the global flags already stripped, so a token still
+    // starting with `-` here is a flag this program does not have — EXCEPT the
+    // two the front door itself answers, which reach this branch by design.
+    // Commander rejects unknown flags below the root; without this the ROOT
+    // answered a typo with the front door and exit 0, so `pragma --detial
+    // standard` read as success.
+    const unknownFlag = args.find(
+      (arg) => arg.startsWith("-") && !ROOT_FLAGS.has(arg),
+    );
+    if (unknownFlag !== undefined) {
+      const [
+        { PragmaError },
+        { renderErrorPlain, renderErrorJson },
+        { mapExitCode },
+      ] = await Promise.all([
+        import("./kernel/error/PragmaError.js"),
+        import("./kernel/error/renderError.js"),
+        import("./kernel/project/cli/exitCodes.js"),
+      ]);
+      const error = new PragmaError({
+        code: "INVALID_INPUT",
+        message: `Unknown option "${unknownFlag}".`,
+        recovery: {
+          message: "Run with `--help` to see the available options.",
+        },
+      });
+      process.stderr.write(
+        `${
+          globalFlags.format === "json"
+            ? renderErrorJson(error)
+            : renderErrorPlain(error)
+        }\n`,
+      );
+      process.exitCode = mapExitCode(error.code);
+      return;
+    }
+
     const { formatRootHelp } = await import("./kernel/project/cli/rootHelp.js");
     const live = capabilities
       .flatMap((module) => [...module.verbs])
       .filter((verb) => !verb.hidden);
     process.stdout.write(
-      `${formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, live)}\n`,
+      `${formatRootHelp(
+        BIN_NAME,
+        PROGRAM_DESCRIPTION,
+        live,
+        VERSION,
+        ISSUES_URL,
+        globalFlags,
+      )}\n`,
     );
+    // The front door is a read, so it is where the un-set-up hint belongs: the
+    // machine's state is the presence of the global config, and nothing is
+    // written to discover it.
+    const { setupHintLines } = await import("./kernel/config/firstRun.js");
+    const hint = setupHintLines();
+    if (hint.length > 0) process.stderr.write(`\n${hint.join("\n")}\n`);
     return;
   }
 
@@ -143,10 +236,12 @@ async function main(): Promise<void> {
       );
       const effective = await loadEffectiveModules(capabilities, process.cwd());
       modules = effective.modules;
-      for (const problem of effective.problems) {
-        process.stderr.write(
-          `Ignored story ${problem.source}: ${problem.message}\n`,
-        );
+      if (globalFlags.quiet !== true) {
+        for (const problem of effective.problems) {
+          process.stderr.write(
+            `Ignored story ${problem.source}: ${problem.message}\n`,
+          );
+        }
       }
     } catch (error) {
       await renderStartupError(error, globalFlags.format === "json");
@@ -155,11 +250,31 @@ async function main(): Promise<void> {
   }
   const verbs = modules.flatMap((module) => [...module.verbs]);
 
+  // Module-owned noun mounts (CapabilityModule.cliProjection), keyed by the
+  // module's noun. A module's verbs all share their noun, so the module name
+  // is that noun for every module that declares a mount.
+  const mounts = new Map(
+    modules.flatMap((module) =>
+      module.cliProjection
+        ? [[module.name, module.cliProjection] as const]
+        : [],
+    ),
+  );
+
+  // A mount may defer its registration machinery behind `prepare()` (the
+  // fast paths import the projection hook without ever mounting) — resolve
+  // every deferred import before the tree is built, alongside the program
+  // builder's own deferred load.
+  const [{ buildProgram }] = await Promise.all([
+    import("./kernel/project/cli/buildProgram.js"),
+    ...[...mounts.values()].map((projection) => projection.prepare?.()),
+  ]);
   const program = buildProgram(verbs, {
     globalFlags,
     programName: BIN_NAME,
     description: PROGRAM_DESCRIPTION,
     version: VERSION,
+    mounts,
   });
   // Silence Commander's default stderr writer on EVERY command, not just the
   // root — otherwise a bad subcommand/option prints Commander's raw `error: …`
@@ -169,10 +284,30 @@ async function main(): Promise<void> {
   try {
     await program.parseAsync(args, { from: "user" });
   } catch (error) {
-    await handleProgramError(error, argv, globalFlags.format === "json", verbs);
+    await handleProgramError(error, argv, globalFlags.format, verbs);
   }
 }
 
+/**
+ * Reject an invalid global-flag value before dispatch: one renderer for the
+ * `--format`/`--detail` guards, so every validated global value flag fails
+ * with the same invalid-input shape and its valid list.
+ */
+async function rejectGlobalValue(
+  name: string,
+  value: string,
+  validOptions: readonly string[],
+  jsonMode: boolean,
+): Promise<void> {
+  const { PragmaError } = await import("./kernel/error/PragmaError.js");
+  await renderStartupError(
+    PragmaError.invalidInput(name, value, {
+      validOptions: [...validOptions],
+    }),
+    jsonMode,
+  );
+}
+
 /**
  * Render a startup error (e.g. an invalid config story pack) before the command
  * tree is built, mapping it to stderr + an exit code — the same envelope
@@ -216,7 +351,7 @@ function silenceCommanderErrors(command: Command): void {
 async function handleProgramError(
   error: unknown,
   argv: readonly string[],
-  jsonMode: boolean,
+  format: import("./constants.js").OutputFormat,
   verbs: import("./kernel/spec/types.js").VerbSpec[],
 ): Promise<void> {
   const { CommanderError } = await import("commander");
@@ -224,16 +359,66 @@ async function handleProgramError(
   if (error instanceof CommanderError) {
     if (
       error.code === "commander.helpDisplayed" ||
-      error.code === "commander.version" ||
-      error.code === "commander.help"
+      error.code === "commander.version"
     ) {
       process.exitCode = 0;
       return;
     }
-    if (error.code === "commander.unknownCommand") {
-      const { nounVerbMap, resolveUnknownCommand } = await import(
-        "./kernel/project/cli/suggest.js"
+    if (error.code === "commander.help") {
+      // Respect the help error's OWN exit code: `help({ error: true })` — a
+      // bare namespace with children, help written to stderr — carries 1;
+      // a stdout help carries 0.
+      process.exitCode = error.exitCode;
+      return;
+    }
+
+    // A parse failure whose argv still speaks a retired module grammar gets
+    // that module's designed migration error (the module authors the text;
+    // the kernel only routes). Currently: `create component --framework`
+    // (R1) — scoped to the ONE command that ever had the flag, so
+    // `create package --framework …` keeps its honest unknown-option error
+    // instead of a migration message about a grammar it never spoke — and
+    // scoped to the pre-terminator span: after `--` the spelling is an
+    // operand, not the retired flag, so the real parse error stands.
+    const { selectScanSpan, stripGlobalFlags } = await import(
+      "./kernel/project/cli/globalFlags.js"
+    );
+    const strippedArgs = stripGlobalFlags(argv);
+    const strippedPositionals = strippedArgs.filter(
+      (arg) => !arg.startsWith("-"),
+    );
+    if (
+      strippedPositionals[0] === "create" &&
+      strippedPositionals[1] === "component" &&
+      selectScanSpan(strippedArgs).some(
+        (arg) => arg === "--framework" || arg.startsWith("--framework="),
+      )
+    ) {
+      const [
+        { FRAMEWORK_FLAG_ERROR },
+        { PragmaError },
+        { renderErrorForFormat },
+      ] = await Promise.all([
+        import("./capabilities/create/messages.js"),
+        import("./kernel/error/PragmaError.js"),
+        import("./kernel/error/renderError.js"),
+      ]);
+      // Explicit --format json/llm envelope (the kernel's one gate+renderer
+      // decision); plain keeps the designed raw line.
+      const rendered = renderErrorForFormat(
+        new PragmaError({
+          code: "INVALID_INPUT",
+          message: FRAMEWORK_FLAG_ERROR.replace(/^error:\s*/i, ""),
+        }),
+        format,
       );
+      process.stderr.write(`${rendered ?? FRAMEWORK_FLAG_ERROR}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    if (error.code === "commander.unknownCommand") {
+      const { curatedSuggestions, nounVerbMap, resolveUnknownCommand } =
+        await import("./kernel/project/cli/suggest.js");
       const { stripGlobalFlags } = await import(
         "./kernel/project/cli/globalFlags.js"
       );
@@ -244,24 +429,28 @@ async function handleProgramError(
       if (unknown) {
         // Route through the same PragmaError + renderers as every other error,
         // so the plain path gets the `Error:` prefix and the shared "Did you
-        // mean?" list instead of a second, inline rendering.
+        // mean?" list instead of a second, inline rendering — and an explicit
+        // machine format gets the same envelope every other usage error
+        // emits (the kernel's one gate+renderer decision; plain and json
+        // bytes unchanged by construction).
         const [
           { PragmaError },
-          { renderErrorPlain, renderErrorJson },
+          { renderErrorForFormat, renderErrorPlain },
           { suggestNames },
         ] = await Promise.all([
           import("./kernel/error/PragmaError.js"),
           import("./kernel/error/renderError.js"),
           import("./kernel/project/cli/suggestNames.js"),
         ]);
-        const suggestions = suggestNames(unknown.token, [
-          ...unknown.candidates,
-        ]);
+        const curated = curatedSuggestions(unknown.token);
+        const suggestions = curated
+          ? [...curated]
+          : suggestNames(unknown.token, [...unknown.candidates]);
         const unknownError = PragmaError.unknownVerb(unknown.token, {
           suggestions,
         });
         process.stderr.write(
-          `${jsonMode ? renderErrorJson(unknownError) : renderErrorPlain(unknownError)}\n`,
+          `${renderErrorForFormat(unknownError, format) ?? renderErrorPlain(unknownError)}\n`,
         );
       }
       process.exitCode = 2;
@@ -269,19 +458,22 @@ async function handleProgramError(
     }
 
     // Other usage errors (missing argument, unknown option, bad choice). Under
-    // --format json these route through the same error envelope agents parse.
-    if (jsonMode) {
-      const [{ PragmaError }, { renderErrorJson }] = await Promise.all([
-        import("./kernel/error/PragmaError.js"),
-        import("./kernel/error/renderError.js"),
-      ]);
-      const message = error.message.replace(/^error:\s*/i, "");
-      process.stderr.write(
-        `${renderErrorJson(new PragmaError({ code: "INVALID_INPUT", message }))}\n`,
-      );
-    } else {
-      process.stderr.write(`${error.message}\n`);
-    }
+    // an explicit --format json/llm these route through the same error
+    // envelope agents parse (the kernel's one gate+renderer decision — the
+    // llm half used to split this one taxonomy class: an excess positional
+    // enveloped while an unknown option stayed raw prose).
+    const [{ PragmaError }, { renderErrorForFormat }] = await Promise.all([
+      import("./kernel/error/PragmaError.js"),
+      import("./kernel/error/renderError.js"),
+    ]);
+    const rendered = renderErrorForFormat(
+      new PragmaError({
+        code: "INVALID_INPUT",
+        message: error.message.replace(/^error:\s*/i, ""),
+      }),
+      format,
+    );
+    process.stderr.write(`${rendered ?? error.message}\n`);
     process.exitCode = 2;
     return;
   }
@@ -302,7 +494,7 @@ async function handleProgramError(
           error instanceof Error ? error.message : String(error),
         );
   process.stderr.write(
-    `${jsonMode ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
+    `${format === "json" ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
   );
   process.exitCode = mapExitCode(pragmaError.code);
 }

package/src/capabilities/block.parity.test.ts

@@ -17,8 +17,11 @@
  *   deleted `capabilities/block/parity.test.ts`. Button and Modal resolve with
  *   the same content a direct SPARQL oracle returns (summary, guidance,
  *   anatomy, tier, modifier families with values, properties, subcomponents).
- *   The fixture DECLARES whenToUse/whenNotToUse (which the live graph superseded
- *   with ds:usage), so those sections are exercised here.
+ *   The fixture declares the usage narrative the way the live graph does — one
+ *   `ds:usage` literal — so what is exercised here is the path a real install
+ *   takes. It formerly declared the retired whenToUse/whenNotToUse pair, and
+ *   that divergence is exactly why this suite could assert a "### When to use"
+ *   heading no install had rendered in months.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -138,9 +141,12 @@ ds:Component a owl:Class .
     try {
       const rows = (await verb("list").run({}, emptyRt)) as PackRow[];
       expect(rows).toEqual([]);
-      const plain = verb("list").output.formatters.plain(rows);
-      expect(plain).toContain("No blocks in the store.");
-      expect(plain).toContain("pragma sources update");
+      // The same semantics, on the empty-state seam: the calm message + its
+      // runnable hint now reach the user via stderr (`notice`), keeping
+      // plain stdout pure data.
+      const notice = verb("list").output.formatters.notice?.(rows);
+      expect(notice).toContain("No blocks in the store.");
+      expect(notice).toContain("pragma sources update");
     } finally {
       (await emptyRt.store.get()).store.dispose();
     }
@@ -156,10 +162,7 @@ describe("block lookup — Button content parity (GraphQL, detailed)", () => {
 
     // Guidance + anatomy sections — each cross-checked against the graph.
     expect(button.summary).toBe(await oracle(`${DS}button`, "ds:summary"));
-    expect(button.whenToUse).toBe(await oracle(`${DS}button`, "ds:whenToUse"));
-    expect(button.whenNotToUse).toBe(
-      await oracle(`${DS}button`, "ds:whenNotToUse"),
-    );
+    expect(button.usage).toBe(await oracle(`${DS}button`, "ds:usage"));
     expect(button.guidelines).toBe(
       await oracle(`${DS}button`, "ds:guidelines"),
     );
@@ -197,7 +200,13 @@ describe("block lookup — Button content parity (GraphQL, detailed)", () => {
     const out = (await verb("lookup").run({ name: ["Button"] }, rt)) as never;
     const llm = verb("lookup").output.formatters.llm(out);
     expect(llm).toContain("## Button");
-    expect(llm).toContain("### When to use");
+    expect(llm).toContain("### Usage");
+    // The usage literal's OWN headings are demoted below the section heading
+    // they now live under, so `### When to use` renders as a CHILD of Usage
+    // rather than a sibling that reads as an empty section.
+    expect(llm).toContain("#### When to use");
+    expect(llm).toContain("#### When not to use");
+    expect(llm).not.toContain("\n### When to use\n");
     expect(llm).toContain("### Anatomy (DSL)");
     expect(llm).toContain("### Modifier Families");
     expect(llm).toContain("primary");
@@ -210,7 +219,15 @@ describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
     expect(modal.uri).toBe(`${DS}modal`);
     expect(modal.name).toBe("Modal");
     expect(modal.summary).toBe(await oracle(`${DS}modal`, "ds:summary"));
-    expect(modal.whenToUse).toBe(await oracle(`${DS}modal`, "ds:whenToUse"));
+    // Modal asserts an EMPTY `ds:usage` — the shape 138 of the 264 live blocks
+    // have. It resolves (parity with the oracle) and renders NOTHING: an empty
+    // literal must not print a bare "### Usage" heading with no body under it.
+    expect(modal.usage).toBe(await oracle(`${DS}modal`, "ds:usage"));
+    expect(modal.usage).toBe("");
+    const modalLlm = verb("lookup").output.formatters.llm(
+      (await verb("lookup").run({ name: ["Modal"] }, rt)) as never,
+    );
+    expect(modalLlm).not.toContain("### Usage");
     const families = modal.modifierFamilies as {
       name: string;
       values?: string[];
@@ -234,7 +251,7 @@ describe("block lookup — disclosure trims to the base view at summary", () =>
     const button = out.results.at(0) as Record<string, unknown>;
     expect(button.name).toBe("Button");
     expect(button.summary).toBeDefined();
-    expect(button.whenToUse).toBeUndefined();
+    expect(button.usage).toBeUndefined();
     expect(button.anatomyDsl).toBeUndefined();
     expect(button.modifierFamilies).toBeUndefined();
     expect(button.figmaLink).toBeUndefined();