@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/bin.ts

@@ -1,20 +1,301 @@
 #!/usr/bin/env bun
 /**
- * CLI entry point for `pragma`.
+ * CLI entry point for `pragma` (v2 kernel).
  *
- * Detects local vs global install, warns if shadowed, then delegates
- * to the pipeline orchestrator.
+ * The composition root. Ordered early exits keep the hot paths minimal and
+ * side-effect-free: `mcp` 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
+ * program from the capabilities and dispatch. Heavy modules are dynamic-imported
+ * so `--help`/`__complete` load neither zod nor any verb run body.
  *
- * @note Impure
+ * @note Impure — reads argv/env, writes stdout/stderr, sets the exit code.
  */
 
-import "./embedWasm.js";
-import { detectLocalInstall } from "./package-manager/index.js";
-import runCli from "./pipeline/runCli.js";
+import type { Command } from "commander";
+import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "./constants.js";
 
-const localWarning = detectLocalInstall();
-if (localWarning) {
-  console.warn(localWarning);
+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") {
+    const [{ serveMcp }, { capabilities }] = await Promise.all([
+      import("./kernel/project/mcp/serve.js"),
+      import("./capabilities/index.js"),
+    ]);
+    await serveMcp(capabilities);
+    return;
+  }
+
+  // 2. Completion resolver — storeless, before first-run so no banner leaks.
+  //    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
+  //    candidates → zero bytes); the entity tier reads the active pack's index
+  //    (storeless), never the store; `runComplete` never throws.
+  if (argv[0] === "__complete") {
+    const [{ runComplete }, { indexCompletionEnv }, { capabilities }] =
+      await Promise.all([
+        import("./kernel/completion/complete.js"),
+        import("./kernel/completion/entitySource.js"),
+        import("./capabilities/index.js"),
+      ]);
+    const words = argv[1] === "--" ? argv.slice(2) : argv.slice(1);
+    const matches = await runComplete(
+      words,
+      capabilities,
+      indexCompletionEnv(process.cwd()),
+    );
+    if (matches.length > 0) process.stdout.write(`${matches.join("\n")}\n`);
+    return;
+  }
+
+  // 2b. Internal store smoke probe — boots the embedded pack (oxigraph WASM +
+  //     pack cache). Not a user command; the WASM-embed smoke test spawns it.
+  if (argv[0] === "__store-probe") {
+    const { runStoreProbe } = await import("./kernel/runtime/probe.js");
+    process.stdout.write(`${await runStoreProbe()}\n`);
+    return;
+  }
+
+  const { parseGlobalFlags, 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")) {
+    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.
+  if (!explicitHelp) {
+    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
+    await ensureFirstRun();
+  }
+
+  // 6. Build the command tree.
+  const [{ buildProgram }, { capabilities }] = await Promise.all([
+    import("./kernel/project/cli/buildProgram.js"),
+    import("./capabilities/index.js"),
+  ]);
+  const args = stripGlobalFlags(argv);
+
+  // 7. 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("-"))) {
+    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`,
+    );
+    return;
+  }
+
+  // A real command merges config-declared story packs into the tree (DISPATCH
+  // only); `--help` stays on the static, storeless capabilities so its budget
+  // and the golden hold. An invalid config story surfaces as a rendered error.
+  let modules = capabilities;
+  if (!explicitHelp) {
+    try {
+      const { loadEffectiveModules } = await import(
+        "./kernel/packs/collect.js"
+      );
+      modules = await loadEffectiveModules(capabilities, process.cwd());
+    } catch (error) {
+      await renderStartupError(error, globalFlags.format === "json");
+      return;
+    }
+  }
+  const verbs = modules.flatMap((module) => [...module.verbs]);
+
+  const program = buildProgram(verbs, {
+    globalFlags,
+    programName: BIN_NAME,
+    description: PROGRAM_DESCRIPTION,
+    version: VERSION,
+  });
+  // Silence Commander's default stderr writer on EVERY command, not just the
+  // root — otherwise a bad subcommand/option prints Commander's raw `error: …`
+  // line alongside (and duplicating) the designed diagnostic.
+  silenceCommanderErrors(program);
+
+  try {
+    await program.parseAsync(args, { from: "user" });
+  } catch (error) {
+    await handleProgramError(error, argv, globalFlags.format === "json", verbs);
+  }
+}
+
+/**
+ * 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
+ * dispatch uses, so a bad `stories` entry surfaces identically to a run error.
+ */
+async function renderStartupError(
+  error: unknown,
+  jsonMode: boolean,
+): Promise<void> {
+  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 pragmaError =
+    error instanceof PragmaError
+      ? error
+      : PragmaError.internalError(
+          error instanceof Error ? error.message : String(error),
+        );
+  process.stderr.write(
+    `${jsonMode ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
+  );
+  process.exitCode = mapExitCode(pragmaError.code);
+}
+
+/** Silence Commander's built-in stderr writer on a command and all descendants. */
+function silenceCommanderErrors(command: Command): void {
+  command.configureOutput({ writeErr: () => {} });
+  for (const child of command.commands) silenceCommanderErrors(child);
+}
+
+/**
+ * Map a thrown parse error onto stderr + an exit code. Verb run errors are
+ * handled inside dispatch; this catches Commander parse failures.
+ */
+async function handleProgramError(
+  error: unknown,
+  argv: readonly string[],
+  jsonMode: boolean,
+  verbs: import("./kernel/spec/types.js").VerbSpec[],
+): Promise<void> {
+  const { CommanderError } = await import("commander");
+
+  if (error instanceof CommanderError) {
+    if (
+      error.code === "commander.helpDisplayed" ||
+      error.code === "commander.version" ||
+      error.code === "commander.help"
+    ) {
+      process.exitCode = 0;
+      return;
+    }
+    if (error.code === "commander.unknownCommand") {
+      const { nounVerbMap, resolveUnknownCommand } = await import(
+        "./kernel/project/cli/suggest.js"
+      );
+      const { stripGlobalFlags } = await import(
+        "./kernel/project/cli/globalFlags.js"
+      );
+      const positionals = stripGlobalFlags(argv).filter(
+        (arg) => !arg.startsWith("-"),
+      );
+      const unknown = resolveUnknownCommand(positionals, nounVerbMap(verbs));
+      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.
+        const [
+          { PragmaError },
+          { renderErrorPlain, renderErrorJson },
+          { 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 unknownError = PragmaError.unknownVerb(unknown.token, {
+          suggestions,
+        });
+        process.stderr.write(
+          `${jsonMode ? renderErrorJson(unknownError) : renderErrorPlain(unknownError)}\n`,
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
+
+    // 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`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+
+  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 pragmaError =
+    error instanceof PragmaError
+      ? error
+      : PragmaError.internalError(
+          error instanceof Error ? error.message : String(error),
+        );
+  process.stderr.write(
+    `${jsonMode ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
+  );
+  process.exitCode = mapExitCode(pragmaError.code);
 }
 
-await runCli(process.argv);
+await main();

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

@@ -0,0 +1,79 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { OWL_EXPORT_TTL } from "../../testing/fixtures/graph/owlExport.js";
+import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
+import type { BlockRow } from "./blockList.verb.js";
+import { blockModule } from "./index.js";
+
+const listVerb = blockModule.verbs.find(
+  (verb) => verbKey(verb.path) === "block list",
+) as VerbSpec;
+
+const names = (rows: BlockRow[]): string[] =>
+  rows.map((row) => row.name).sort();
+
+/**
+ * The OWL-export fixture ships an UNTIERED `ds:Component` (`ds:datePicker`, no
+ * `ds:tier`) beside a tiered one (`ds:button`). The pre-fix `block list` gated
+ * on a REQUIRED `ds:tier` triple pattern, so `--all-tiers` — which drops the
+ * FILTER but not the pattern — still hid the untiered block, contradicting the
+ * flag's promise to show every block (A2). A tier-scoped view legitimately
+ * omits an untiered block (it joins the list through its tier); `--all-tiers`
+ * is the escape that reveals it.
+ */
+describe("block list — untiered blocks under --all-tiers (A2)", () => {
+  describe("no tier configured", () => {
+    let runtime: PragmaRuntime;
+    let dispose: () => Promise<void>;
+
+    beforeAll(async () => {
+      const fixture = await bootFixtureRuntime({ ttl: OWL_EXPORT_TTL });
+      runtime = fixture.runtime;
+      dispose = fixture.dispose;
+    });
+    afterAll(() => dispose());
+
+    it("the default view still omits the untiered block", async () => {
+      const rows = (await listVerb.run({}, runtime)) as BlockRow[];
+      expect(names(rows)).toEqual(["Button"]);
+    });
+
+    it("--all-tiers reveals the untiered block", async () => {
+      const rows = (await listVerb.run(
+        { allTiers: true },
+        runtime,
+      )) as BlockRow[];
+      expect(names(rows)).toEqual(["Button", "Date Picker"]);
+    });
+  });
+
+  describe("a tier IS configured", () => {
+    let runtime: PragmaRuntime;
+    let dispose: () => Promise<void>;
+
+    beforeAll(async () => {
+      const fixture = await bootFixtureRuntime({
+        ttl: OWL_EXPORT_TTL,
+        config: { tier: "global", channel: "normal" },
+      });
+      runtime = fixture.runtime;
+      dispose = fixture.dispose;
+    });
+    afterAll(() => dispose());
+
+    it("a scoped tier lists its tiered block, not the untiered one", async () => {
+      const rows = (await listVerb.run({}, runtime)) as BlockRow[];
+      expect(names(rows)).toEqual(["Button"]);
+    });
+
+    it("--all-tiers overrides the scope and reveals the untiered block", async () => {
+      const rows = (await listVerb.run(
+        { allTiers: true },
+        runtime,
+      )) as BlockRow[];
+      expect(names(rows)).toContain("Date Picker");
+    });
+  });
+});

package/src/capabilities/block/blockList.verb.ts

@@ -0,0 +1,163 @@
+/**
+ * `block list` — the ONE hand-written read (Risk5).
+ *
+ * A block list is config-filtered in ways packs cannot express declaratively:
+ * the tier CHAIN (a tier makes its whole parent chain visible), the channel
+ * (release-level visibility), and the `--all-tiers` escape. Everything else in
+ * PR3 is a declarative pack; this verb ports that behaviour directly. It reads
+ * the effective tier/channel from config and runs one generated SELECT (no user
+ * input in the query — the tier is config, the channel a closed enum).
+ */
+
+import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
+import type {
+  ColumnDef,
+  RenderListOptions,
+} from "../../kernel/render/contracts.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import {
+  renderListLlm,
+  renderListPlain,
+} from "../../kernel/render/renderers.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { Formatters, VerbSpec } from "../../kernel/spec/types.js";
+import { buildChannelFilter, buildTierFilter } from "./tierChain.js";
+
+/** One block summary row. */
+export interface BlockRow {
+  readonly uri: string;
+  readonly name: string;
+  readonly type: string;
+  readonly tier: string;
+  readonly modifiers: string;
+}
+
+/** Local name of an IRI (`…/global` → `global`; `…#Thing` → `Thing`). */
+function localName(uri: string): string {
+  const hash = uri.lastIndexOf("#");
+  if (hash !== -1) return uri.slice(hash + 1);
+  const slash = uri.lastIndexOf("/");
+  return slash !== -1 ? uri.slice(slash + 1) : uri;
+}
+
+/** Normalize a block's rdf:type to one of the four block kinds. */
+function normalizeType(typeUri: string | undefined): BlockRow["type"] {
+  const local = localName(typeUri ?? "").toLowerCase();
+  return local === "pattern" || local === "layout" || local === "subcomponent"
+    ? local
+    : "component";
+}
+
+const listColumns: ColumnDef<BlockRow>[] = [
+  { key: "name", label: "Name" },
+  { key: "type", label: "Type" },
+  { key: "tier", label: "Tier" },
+  { key: "modifiers", label: "Modifiers", showWhenEmpty: false },
+  { key: "uri", label: "IRI" },
+];
+
+const listOptions: RenderListOptions<BlockRow> = {
+  heading: "Blocks",
+  columns: listColumns,
+  prefixes: DEFAULT_PREFIX_MAP,
+  // Zero blocks is a calm success (exit 0), not an error — the list is scoped by
+  // the active tier chain and channel, so the message names that scope and the
+  // hint offers the escape hatches (a cold store fails earlier with
+  // STORE_UNAVAILABLE, so reaching here means the store is built).
+  emptyMessage: "No blocks found under the current tier and channel.",
+  emptyHint:
+    "Use --all-tiers to ignore the tier filter, or run `pragma sources update` if the store is empty.",
+};
+
+const listFormatters: Formatters<BlockRow[]> = {
+  plain: (rows) => renderListPlain(rows, listOptions),
+  llm: (rows) => renderListLlm(rows, listOptions),
+  json: (rows) => JSON.stringify(rows, null, 2),
+};
+
+/** Build the config-filtered block SELECT for the resolved tier/channel. */
+function buildQuery(
+  tier: string | undefined,
+  channel: import("../../kernel/config/types.js").Channel,
+  allTiers: boolean,
+): string {
+  const tierFilter = allTiers ? "" : buildTierFilter(tier);
+  const channelFilter = buildChannelFilter(channel);
+  // Under --all-tiers, `ds:name`/`ds:tier` become OPTIONAL so a real block that
+  // ships without either is no longer hidden — the flag promises "all blocks",
+  // yet the pre-fix query gated on those as REQUIRED patterns, dropping the
+  // FILTER but not the pattern (A2). In the scoped/default view they stay
+  // required: a block joins the list through its tier, so an untiered block is
+  // intentionally out of a tier-scoped view (and --all-tiers is the escape).
+  const nameTierPatterns = allTiers
+    ? [
+        "  OPTIONAL { ?component ds:name ?name }",
+        "  OPTIONAL { ?component ds:tier ?tier }",
+      ]
+    : ["  ?component ds:name ?name ; ds:tier ?tier ."];
+  return [
+    "SELECT ?component ?type ?name ?tier",
+    '       (GROUP_CONCAT(DISTINCT ?modName; separator=", ") AS ?modifiers)',
+    "WHERE {",
+    "  VALUES ?type { ds:Component ds:Pattern ds:Layout ds:Subcomponent }",
+    "  ?component a ?type .",
+    ...nameTierPatterns,
+    tierFilter ? `  ${tierFilter}` : "",
+    `  ${channelFilter}`,
+    "  OPTIONAL { ?component ds:hasModifierFamily ?mod . ?mod ds:name ?modName }",
+    "}",
+    "GROUP BY ?component ?type ?name ?tier",
+    "ORDER BY ?name",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+const listVerb: VerbSpec<Record<string, unknown>, BlockRow[]> = {
+  path: ["block", "list"],
+  summary: "List blocks visible under the current tier and channel.",
+  doc: "List design system blocks visible under the active tier chain and channel. Optionally list across every tier, ignoring the tier filter.",
+  params: [
+    {
+      kind: "boolean",
+      name: "allTiers",
+      doc: "Show blocks from all tiers, ignoring the tier filter.",
+    },
+  ],
+  output: { formatters: listFormatters },
+  examples: [
+    { cmd: "pragma block list" },
+    { cmd: "pragma block list --all-tiers" },
+    { cmd: "pragma block list --format llm" },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: async (params: Record<string, unknown>, rt: PragmaRuntime) => {
+    const layers = await rt.loadConfig();
+    const query = buildQuery(
+      layers.config.tier,
+      layers.config.channel,
+      params.allTiers === true,
+    );
+    const rows = await runSelect(rt, query, "block");
+    return rows.map((row) => ({
+      uri: row.component ?? "",
+      // An unnamed block still needs a token to show — fall back to its IRI's
+      // local name rather than rendering a blank row (A2).
+      name: row.name ?? localName(row.component ?? ""),
+      type: normalizeType(row.type),
+      tier: localName(row.tier ?? ""),
+      modifiers: row.modifiers ?? "",
+    }));
+  },
+};
+
+/** The hand-written `block list` verb. */
+export const blockListVerb = asVerb(listVerb);

package/src/capabilities/block/index.ts

@@ -0,0 +1,25 @@
+/**
+ * The `block` capability module — a COMPOSITE: the hand-written `block list`
+ * (tier chain + channel + --all-tiers) plus the bundled pack's GraphQL `lookup`.
+ *
+ * This is the one noun where a declarative pack and a hand-written verb share a
+ * module; the pack ships lookup-only, so there is no `(noun, verb)` collision.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { blockListVerb } from "./blockList.verb.js";
+import { blockPack } from "./pack.js";
+
+/** The `block` capability module (`list` hand-written, `lookup` from the pack). */
+export const blockModule: CapabilityModule = {
+  name: "block",
+  verbs: [
+    blockListVerb,
+    ...compilePack(blockPack, "bundled:block", DEFAULT_PREFIX_MAP),
+  ],
+  // The bundled design-system domain colophon (authored on the flagship UI-block
+  // noun), surfaced by `pragma colophon` after pragma's own.
+  colophon: blockPack.colophon,
+};