@canonical/pragma-cli 0.31.0 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
-  "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.31.0",
+  "description": "Next-generation CLI and MCP kernel for Canonical's design system (pragma v2).",
+  "version": "0.32.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -31,66 +31,51 @@
     "url": "https://github.com/canonical/pragma/issues"
   },
   "homepage": "https://github.com/canonical/pragma#readme",
-  "imports": {
-    "#config": "./src/config/index.ts",
-    "#constants": "./src/constants.ts",
-    "#error": "./src/error/index.ts",
-    "#package-manager": "./src/package-manager/index.ts",
-    "#pipeline": "./src/pipeline/index.ts",
-    "#testing": "./src/testing/index.ts",
-    "#tui": "./src/tui/index.ts"
-  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
     "build:compile": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
-    "prepublishOnly": "bun run build",
     "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
     "check:webarchitect": "webarchitect tool-ts",
     "check:fix": "bun run check:biome:fix && bun run check:ts",
     "check:biome": "biome check",
     "check:biome:fix": "biome check --write",
     "check:ts": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "bun run test:vitest && bun run test:perf",
+    "test:vitest": "vitest run --coverage",
+    "test:perf": "vitest run --config vitest.perf.config.ts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:compile": "bun run src/compile-validation.runner.ts"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.31.0",
-    "@canonical/typescript-config": "^0.31.0",
-    "@canonical/webarchitect": "^0.31.0",
-    "@types/bun": "^1.3.10",
-    "@types/node": "^24.12.0",
-    "@types/react": "^19.2.14",
-    "expect-type": "^1.3.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "eval": "bun run src/testing/eval/report.ts"
   },
   "dependencies": {
-    "@canonical/anatomy-dsl": "^0.2.2",
-    "@canonical/cli-core": "^0.31.0",
-    "@canonical/code-standards": "^0.1.2",
-    "@canonical/design-system": "^0.1.2",
-    "@canonical/harnesses": "^0.31.0",
-    "@canonical/ke": "^0.31.0",
-    "@canonical/ke-graphql": "^0.31.0",
-    "@canonical/summon": "^0.31.0",
-    "@canonical/summon-application": "^0.31.0",
-    "@canonical/summon-component": "^0.31.0",
-    "@canonical/summon-core": "^0.31.0",
-    "@canonical/summon-package": "^0.31.0",
-    "@canonical/task": "^0.31.0",
+    "@canonical/harnesses": "^0.32.0",
+    "@canonical/ke": "^0.32.0",
+    "@canonical/ke-graphql": "^0.32.0",
+    "@canonical/summon-application": "^0.32.0",
+    "@canonical/summon-component": "^0.32.0",
+    "@canonical/summon-core": "^0.32.0",
+    "@canonical/summon-package": "^0.32.0",
+    "@canonical/task": "^0.32.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "ink": "^6.8.0",
+    "graphql": "17.0.0-rc.0",
     "oxigraph": "^0.5.0",
-    "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "d4a67ebe42e62b8cf3de77f42f537309ca88d672"
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@canonical/biome-config": "^0.32.0",
+    "@canonical/typescript-config": "^0.32.0",
+    "@canonical/webarchitect": "^0.32.0",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "gitHead": "5b279d8150e3988c68c6c2a741046bcd425624ca"
 }

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", "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", "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.verb.ts

@@ -0,0 +1,150 @@
+/**
+ * `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);
+  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 ;",
+    "             ds:name ?name ;",
+    "             ds:tier ?tier .",
+    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 --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 ?? "",
+      name: row.name ?? "",
+      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,
+};