@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/mcp/tools/registerTools.test.ts

@@ -15,8 +15,13 @@ import {
   RECIPE_STORY,
   RECIPE_TTL,
 } from "#testing";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../domains/token/featureFlag.js";
 import type { McpErrorPayload } from "../types.js";
 
+// token_list, token_lookup, and token_sample are gated behind the token
+// read-surface feature flag.
+const EXPECTED_TOOL_COUNT = TOKEN_READ_SURFACE_ENABLED ? 34 : 31;
+
 let client: Client;
 let cleanup: () => Promise<void>;
 
@@ -57,9 +62,9 @@ function parseData(result: Record<string, unknown>): unknown {
 // =============================================================================
 
 describe("tool listing", () => {
-  it("registers 30 tools", async () => {
+  it("registers the expected number of tools", async () => {
     const { tools } = await client.listTools();
-    expect(tools).toHaveLength(30);
+    expect(tools).toHaveLength(EXPECTED_TOOL_COUNT);
   });
 
   it("all tools have descriptions", async () => {
@@ -80,8 +85,10 @@ describe("tool listing", () => {
     expect(names).toContain("standard_categories");
     expect(names).toContain("modifier_list");
     expect(names).toContain("modifier_lookup");
-    expect(names).toContain("token_list");
-    expect(names).toContain("token_lookup");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(names).toContain("token_list");
+      expect(names).toContain("token_lookup");
+    }
     expect(names).toContain("tier_list");
     expect(names).toContain("config_show");
     expect(names).toContain("config_tier");
@@ -102,7 +109,9 @@ describe("tool listing", () => {
     // Sample tools
     expect(names).toContain("block_sample");
     expect(names).toContain("standard_sample");
-    expect(names).toContain("token_sample");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(names).toContain("token_sample");
+    }
     expect(names).toContain("modifier_sample");
   });
 
@@ -112,6 +121,67 @@ describe("tool listing", () => {
       expect(tool.name).not.toMatch(/^pragma_/);
     }
   });
+
+  // Golden surface: the full built-in tool set plus bundled packs, in
+  // registration order. The per-(noun, verb) reserved-guard flip must leave
+  // this byte-identical AND order-identical — registration order is the tool
+  // surface a client sees.
+  it("has a stable built-in tool surface", async () => {
+    const names = (await client.listTools()).tools.map((tool) => tool.name);
+
+    expect(names).toEqual([
+      "block_list",
+      "block_lookup",
+      "block_sample",
+      "modifier_list",
+      "modifier_lookup",
+      "modifier_sample",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token_list", "token_lookup"] : []),
+      "tokens_add_config",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token_sample"] : []),
+      "config_show",
+      "config_tier",
+      "config_channel",
+      "ontology_list",
+      "ontology_show",
+      "graph_query",
+      "graph_inspect",
+      "skill_list",
+      "skill_lookup",
+      "doctor",
+      "info",
+      "capabilities",
+      "llm",
+      "create_component",
+      "create_package",
+      "create_application",
+      "create_domain",
+      "create_route",
+      "create_wrapper",
+      // Bundled packs register after the built-in tools: `tier_list` and the
+      // whole `standard` noun are served by bundled story packs — the
+      // hand-written tier and standard domains were deleted.
+      "tier_list",
+      "standard_list",
+      "standard_lookup",
+      "standard_categories",
+      "standard_sample",
+    ]);
+  });
+
+  it("serves the standard tools from the bundled pack, not built-ins", async () => {
+    const { tools } = await client.listTools();
+    const standardList = tools.find((tool) => tool.name === "standard_list");
+    // Pack-compiled tool descriptions carry no story-pack suffix here only
+    // because the bundled pack curates them; the giveaway is the derived
+    // `search`/`category` params on the pack projection.
+    const params = Object.keys(
+      (standardList?.inputSchema as { properties?: object })?.properties ?? {},
+    );
+    expect(params).toContain("category");
+    expect(params).toContain("search");
+    expect(params).toContain("condensed");
+  });
 });
 
 // =============================================================================
@@ -419,7 +489,7 @@ describe("modifier_lookup", () => {
 // Token tools
 // =============================================================================
 
-describe("token_list", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_list", () => {
   it("returns tokens", async () => {
     const result = await client.callTool({
       name: "token_list",
@@ -430,7 +500,7 @@ describe("token_list", () => {
   });
 });
 
-describe("token_lookup", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_lookup", () => {
   it("returns token with theme values", async () => {
     const result = await client.callTool({
       name: "token_lookup",
@@ -468,10 +538,11 @@ describe("tier_list", () => {
       name: "tier_list",
       arguments: {},
     });
-    const data = parseData(result) as { path: string }[];
+    // The bundled tier pack names the field `name` (its `ds:name` value).
+    const data = parseData(result) as { name: string }[];
     expect(data.length).toBeGreaterThan(0);
-    const paths = data.map((t) => t.path);
-    expect(paths).toContain("global");
+    const names = data.map((t) => t.name);
+    expect(names).toContain("global");
   });
 });
 
@@ -714,7 +785,7 @@ describe("create_component", () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "react",
+        variant: "react",
         componentPath: "src/components/Button",
       },
     });
@@ -729,7 +800,7 @@ describe("create_component", () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "svelte",
+        variant: "svelte",
         componentPath: "src/lib/components/Toggle",
       },
     });
@@ -738,11 +809,11 @@ describe("create_component", () => {
     expect((data.generator as { name: string }).name).toBe("component/svelte");
   });
 
-  it("returns error for invalid framework", async () => {
+  it("returns error for invalid variant", async () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "angular",
+        variant: "angular",
         componentPath: "src/components/Button",
       },
     });
@@ -784,7 +855,7 @@ describe("llm", () => {
     expect(data.context.counts.blocks).toBeGreaterThan(0);
     expect(data.context.counts.standards).toBeGreaterThan(0);
     expect(data.context.namespaces.length).toBeGreaterThan(0);
-    expect(data.decisionTrees).toHaveLength(5);
+    expect(data.decisionTrees).toHaveLength(TOKEN_READ_SURFACE_ENABLED ? 5 : 4);
     expect(data.commandReference.length).toBeGreaterThan(0);
   });
 });
@@ -798,7 +869,9 @@ describe("error handling", () => {
     const notFoundCalls = [
       { name: "block_lookup", arguments: { names: ["X"] } },
       { name: "modifier_lookup", arguments: { names: ["X"] } },
-      { name: "token_lookup", arguments: { names: ["X"] } },
+      ...(TOKEN_READ_SURFACE_ENABLED
+        ? [{ name: "token_lookup", arguments: { names: ["X"] } }]
+        : []),
       { name: "standard_lookup", arguments: { names: ["X"] } },
     ] as const;
 
@@ -872,7 +945,7 @@ describe("ontology_show", () => {
     const envelope = parseEnvelope(result);
     expect(envelope.ok).toBe(true);
     expect(envelope.condensed).toBe(true);
-    expect(envelope.text).toEqual(expect.stringContaining("## ds:"));
+    expect(envelope.text).toEqual(expect.stringContaining("## Ontology ds:"));
   });
 });
 
@@ -995,7 +1068,7 @@ describe("story-pack tools", () => {
       const tools = (await scoped.client.listTools()).tools.map(
         (tool) => tool.name,
       );
-      expect(tools).toHaveLength(32);
+      expect(tools).toHaveLength(EXPECTED_TOOL_COUNT + 2);
       expect(tools).toContain("recipe_list");
       expect(tools).toContain("recipe_lookup");
 
@@ -1105,9 +1178,9 @@ describe("capabilities", () => {
     expect(toolNames).toContain("block_list");
     expect(toolNames).toContain("capabilities");
     expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
-    expect(data.counts.total).toBe(30);
+    expect(data.counts.total).toBe(EXPECTED_TOOL_COUNT);
     expect(data.counts.read).toBeGreaterThan(0);
-    expect(data.counts.write).toBe(5);
+    expect(data.counts.write).toBe(9);
     expect(data.counts.orientation).toBe(2);
     expect(data.counts.diagnostic).toBe(2);
     expect(data.version).toBeDefined();
@@ -1188,14 +1261,17 @@ describe("condensed parameter", () => {
     expect((envelope.text as string).length).toBeGreaterThan(0);
   });
 
-  it("token_lookup returns condensed text", async () => {
-    const result = await client.callTool({
-      name: "token_lookup",
-      arguments: { names: ["color.primary"], condensed: true },
-    });
-    const envelope = parseEnvelope(result);
-    expect(envelope.ok).toBe(true);
-    expect(envelope.condensed).toBe(true);
-    expect(typeof envelope.text).toBe("string");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup returns condensed text",
+    async () => {
+      const result = await client.callTool({
+        name: "token_lookup",
+        arguments: { names: ["color.primary"], condensed: true },
+      });
+      const envelope = parseEnvelope(result);
+      expect(envelope.ok).toBe(true);
+      expect(envelope.condensed).toBe(true);
+      expect(typeof envelope.text).toBe("string");
+    },
+  );
 });

package/src/pipeline/collectCommands.test.ts

@@ -1,8 +1,16 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { PragmaContext } from "../domains/shared/context.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
+import {
+  deriveReservedVerbs,
+  isReserved,
+  nounVerbFromPath,
+  nounVerbFromToolName,
+} from "../domains/shared/stories/pack/index.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../domains/token/featureFlag.js";
+import { allSpecs } from "../mcp/tools/index.js";
 import createTestRuntime from "../testing/helpers/createTestRuntime.js";
-import collectCommands from "./collectCommands.js";
+import collectCommands, { builtInCommands } from "./collectCommands.js";
 
 let runtime: PragmaRuntime;
 
@@ -34,4 +42,146 @@ describe("collectCommands", () => {
     expect(paths).toContain("graph query");
     expect(paths).toContain("graph inspect");
   });
+
+  // Golden surface: the full built-in command set, in emission order. The
+  // per-(noun, verb) reserved-guard flip must not add, drop, rename, or REORDER
+  // a single built-in command — order drives help output and registration.
+  // `tier list` and the whole `standard` noun are no longer here: the
+  // hand-written domains were deleted and are served by bundled story packs
+  // (asserted below).
+  it("has a stable built-in command surface", () => {
+    const paths = builtInCommands(makeCtx()).map((command) =>
+      command.path.join(" "),
+    );
+
+    expect(paths).toEqual([
+      "config tier",
+      "config channel",
+      "config trace",
+      "config framework",
+      "config show",
+      "create component",
+      "create package",
+      "create application",
+      "create domain",
+      "create route",
+      "create wrapper",
+      "setup",
+      "setup lsp",
+      "setup mcp",
+      "setup completions",
+      "setup skills",
+      "modifier list",
+      "modifier lookup",
+      "modifier sample",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token list", "token lookup"] : []),
+      "tokens add-config",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token sample"] : []),
+      "block list",
+      "block lookup",
+      "block sample",
+      "ontology list",
+      "ontology show",
+      "graph query",
+      "graph inspect",
+      "graphql build",
+      "graphql check",
+      "graphql serve",
+      "skill list",
+      "skill lookup",
+      "doctor",
+      "info",
+      "upgrade",
+      "llm",
+      "capabilities",
+    ]);
+  });
+
+  it("serves `tier list` from the bundled pack, not a built-in", () => {
+    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
+      c.path.join(" "),
+    );
+    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
+
+    expect(builtInPaths).not.toContain("tier list");
+    expect(allPaths).toContain("tier list");
+  });
+
+  it("serves the whole `standard` noun from the bundled pack", () => {
+    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
+      c.path.join(" "),
+    );
+    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
+
+    const standardVerbs = [
+      "standard list",
+      "standard lookup",
+      "standard categories",
+      "standard sample",
+    ];
+    for (const path of standardVerbs) {
+      expect(builtInPaths).not.toContain(path);
+      expect(allPaths).toContain(path);
+    }
+  });
+});
+
+// Cross-surface skew invariant (FIX 2 / R4-F1): the CLI and MCP surfaces both
+// derive their reserved map through the single shared deriveReservedVerbs, so
+// they MUST agree on every leaf read (noun, verb) reservation. If they drifted,
+// a pack migrating a `list`/`lookup` verb could be admitted on one surface and
+// blocked on the other. Operational nouns legitimately differ (graphql/setup/
+// upgrade are CLI-only), so the invariant is scoped to the read verbs that
+// packs actually emit.
+describe("cross-surface reserved-verb parity", () => {
+  const READ_VERBS = ["list", "lookup"] as const;
+
+  it("CLI and MCP reserve the same list/lookup verbs for every leaf read noun", () => {
+    // Both surfaces derive reservations from BUILT-INS only (production reserves
+    // from built-ins, before appending packs), so a bundled/config/package pack
+    // never inflates the reserved map. Using collectCommands here would fold the
+    // bundled tier pack into the CLI side and break the symmetry.
+    const cliPairs = builtInCommands(makeCtx()).map((command) =>
+      nounVerbFromPath(command.path),
+    );
+    const mcpPairs = allSpecs.map((spec) => nounVerbFromToolName(spec.name));
+
+    const cliReserved = deriveReservedVerbs(cliPairs);
+    const mcpReserved = deriveReservedVerbs(mcpPairs);
+
+    // FIX 1 on the real CLI surface: operational nouns own no list/lookup, so
+    // they are reserved wholesale — a pack emitting `list` stays blocked.
+    for (const noun of ["config", "graph", "graphql", "setup", "create"]) {
+      expect(isReserved(cliReserved, noun, "list")).toBe(true);
+    }
+
+    // Leaf read nouns: those that own a `list`/`lookup` verb on either surface.
+    const readNouns = new Set(
+      [...cliPairs, ...mcpPairs]
+        .filter(([, verb]) => verb === "list" || verb === "lookup")
+        .map(([noun]) => noun),
+    );
+
+    // Sanity: the real leaf-migration targets are present, so this asserts
+    // something (a silently empty set would make the test vacuous). `tier`
+    // and `standard` are no longer here — both were cut over to bundled
+    // packs, so they are correctly absent from the built-in reserved
+    // surface on both sides. The token noun only owns read verbs while its
+    // feature flag is on.
+    const expectedReadNouns = ["block", "modifier"];
+    if (TOKEN_READ_SURFACE_ENABLED) expectedReadNouns.push("token");
+    for (const noun of expectedReadNouns) {
+      expect(readNouns.has(noun)).toBe(true);
+    }
+    expect(readNouns.has("standard")).toBe(false);
+
+    for (const noun of readNouns) {
+      for (const verb of READ_VERBS) {
+        expect(
+          isReserved(cliReserved, noun, verb),
+          `CLI/MCP disagree on ${noun} ${verb}`,
+        ).toBe(isReserved(mcpReserved, noun, verb));
+      }
+    }
+  });
 });

package/src/pipeline/collectCommands.ts

@@ -14,31 +14,27 @@ import { commands as modifierCommands } from "../domains/modifier/index.js";
 import { commands as ontologyCommands } from "../domains/ontology/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
-import { compilePackCommands } from "../domains/shared/stories/pack/index.js";
+import {
+  compilePackCommands,
+  deriveReservedVerbs,
+  nounVerbFromPath,
+} from "../domains/shared/stories/pack/index.js";
 import { commands as skillCommands } from "../domains/skill/index.js";
-import { commands as standardCommands } from "../domains/standard/index.js";
-import { commands as tierCommands } from "../domains/tier/index.js";
 import { commands as tokenCommands } from "../domains/token/index.js";
 
 /**
- * Collect all CLI command definitions from domain modules.
- *
- * Extracted from runCli so the completions server can import
- * the command list independently without running the full CLI pipeline.
+ * The built-in (hand-written domain) command surface, in emission order.
  *
- * @param ctx - The pragma context providing store, config, and global flags.
- * @returns The full array of command definitions for all domains.
+ * Excludes story-pack commands (bundled, config, or package). Exported so the
+ * reserved-verb derivation and its tests share the exact input production uses
+ * — the reserved map is built from built-ins only, never from packs.
  */
-export default function collectCommands(
-  ctx: PragmaContext,
-): CommandDefinition[] {
-  const builtIn: CommandDefinition[] = [
+export function builtInCommands(ctx: PragmaContext): CommandDefinition[] {
+  return [
     ...configCommands(ctx),
     ...createCommands(),
     ...setupCommands(),
-    ...standardCommands(ctx),
     ...modifierCommands(ctx),
-    ...tierCommands(ctx),
     ...tokenCommands(ctx),
     ...blockCommands(ctx),
     ...ontologyCommands(ctx),
@@ -51,10 +47,29 @@ export default function collectCommands(
     buildLlmCommand(ctx),
     buildCapabilitiesCommand(),
   ];
+}
 
-  // Story packs project onto the same surface; built-in nouns are reserved.
-  const reservedNouns = new Set(
-    builtIn.map((command) => command.path.at(0) ?? ""),
+/**
+ * Collect all CLI command definitions: built-in domains plus story packs.
+ *
+ * Extracted from runCli so the completions server can import the command list
+ * independently without running the full CLI pipeline.
+ *
+ * Story packs (bundled transitional packs, plus config- and package-declared
+ * stories) project onto the same surface. Leaf read nouns reserve only the
+ * (noun, verb) pairs they own, so a pack can add a verb no built-in owns and,
+ * once a built-in leaf is deleted, its bundled pack takes over the freed noun;
+ * operational nouns (config, graph, setup, …) stay reserved wholesale.
+ *
+ * @param ctx - The pragma context providing store, config, and global flags.
+ * @returns The full array of command definitions for all domains.
+ */
+export default function collectCommands(
+  ctx: PragmaContext,
+): CommandDefinition[] {
+  const builtIn = builtInCommands(ctx);
+  const reserved = deriveReservedVerbs(
+    builtIn.map((command) => nounVerbFromPath(command.path)),
   );
-  return [...builtIn, ...compilePackCommands(ctx, reservedNouns)];
+  return [...builtIn, ...compilePackCommands(ctx, reserved)];
 }

package/src/pipeline/createProgram.test.ts

@@ -36,9 +36,13 @@ describe("createProgram", () => {
       }
     )._events.beforeAllHelp({ command: program, write });
 
+    // Assert on single-chalk-span strings so the check is robust whether or
+    // not color is enabled (CI renders with color; ANSI resets would otherwise
+    // split a multi-word phrase like "Usage: pragma").
     expect(write).toHaveBeenCalledWith(
-      expect.stringContaining("Usage: pragma <command> [options]"),
+      expect.stringContaining("For AI agents"),
     );
+    expect(write).toHaveBeenCalledWith(expect.stringContaining("Global flags"));
   });
 
   it("uses llm root help when llm is enabled", async () => {

package/src/pipeline/createProgram.ts

@@ -1,7 +1,6 @@
 import {
   type CommandDefinition,
   detectRenderMode,
-  formatHelp,
   formatLlmHelp,
   type HandleResultOptions,
   registerAll,
@@ -9,6 +8,7 @@ import {
 import { Command } from "commander";
 import { PROGRAM_DESCRIPTION, PROGRAM_NAME, VERSION } from "../constants.js";
 import type { PragmaContext } from "../domains/shared/context.js";
+import formatRootHelp from "./rootHelp.js";
 
 /**
  * Build and configure the top-level Commander program.
@@ -57,7 +57,7 @@ export default function createProgram(
     if (ctx.globalFlags.llm) {
       return formatLlmHelp(PROGRAM_NAME, commands);
     }
-    return formatHelp(PROGRAM_NAME, PROGRAM_DESCRIPTION, commands);
+    return formatRootHelp(PROGRAM_NAME, PROGRAM_DESCRIPTION, commands);
   });
 
   program.helpOption("-h, --help", "Show help");

package/src/pipeline/firstRun.test.ts

@@ -0,0 +1,80 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import ensureFirstRun from "./firstRun.js";
+
+let xdg: string;
+let savedXdg: string | undefined;
+let lines: string[];
+
+const write = (line: string) => {
+  lines.push(line);
+};
+
+beforeEach(() => {
+  savedXdg = process.env.XDG_CONFIG_HOME;
+  xdg = mkdtempSync(join(tmpdir(), "pragma-firstrun-"));
+  process.env.XDG_CONFIG_HOME = xdg;
+  lines = [];
+});
+
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = savedXdg;
+  rmSync(xdg, { recursive: true, force: true });
+});
+
+const configPath = () => join(xdg, "pragma", "config.json");
+
+describe("ensureFirstRun", () => {
+  it("creates the global config with defaults and greets on first run", async () => {
+    await ensureFirstRun(write);
+
+    expect(existsSync(configPath())).toBe(true);
+    expect(JSON.parse(readFileSync(configPath(), "utf-8"))).toEqual({});
+
+    const text = lines.join("\n");
+    expect(text).toContain("pre-release pragma CLI");
+    expect(text).toContain("github.com/canonical/pragma");
+    expect(text).toContain(configPath());
+    expect(text).toContain("pragma.config.json");
+  });
+
+  it("is silent and leaves the config untouched on subsequent runs", async () => {
+    await ensureFirstRun(write);
+    lines = [];
+
+    await ensureFirstRun(write);
+
+    expect(lines).toEqual([]);
+    expect(readFileSync(configPath(), "utf-8")).toBe("{}\n");
+  });
+
+  it("never overwrites an existing config", async () => {
+    await ensureFirstRun(write);
+    const custom = '{ "channel": "experimental" }\n';
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(configPath(), custom);
+    lines = [];
+
+    await ensureFirstRun(write);
+
+    expect(readFileSync(configPath(), "utf-8")).toBe(custom);
+    expect(lines).toEqual([]);
+  });
+
+  it("degrades to a warning instead of throwing when the config cannot be created", async () => {
+    // Point XDG at a path whose parent is a FILE, so mkdir must fail.
+    const blocker = join(xdg, "blocker");
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(blocker, "not a directory");
+    process.env.XDG_CONFIG_HOME = join(blocker, "nested");
+
+    await expect(ensureFirstRun(write)).resolves.toBeUndefined();
+    // Exactly one warning line and no welcome banner: creation is attempted
+    // before the greeting, so a failure degrades to a single stderr warning.
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain("could not create the global pragma config");
+    expect(lines.join("\n")).not.toContain("pre-release pragma CLI");
+  });
+});