@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/testing/behavioral/staleCommands.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Stale-command gate: the published README and every doc under `docs/` must be
+ * free of the retired v1 vocabulary. This is an ENFORCED test, not a lint — a
+ * doc that reintroduces a removed command (or the retired `--llm` flag) fails
+ * the build. The live `--format llm` form is deliberately NOT banned.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/** The package root (`packages/cli/pragma/`), resolved from this test's URL. */
+const packageRoot = fileURLToPath(new URL("../../../", import.meta.url));
+
+/** Recursively collect every `.md` file under a directory. */
+function collectMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...collectMarkdown(full));
+    else if (entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+/** One retired pattern and a human-readable reason for the failure message. */
+interface BannedPattern {
+  readonly pattern: RegExp;
+  readonly reason: string;
+}
+
+/** The retired v1 vocabulary. The live `--format llm` form is intentionally absent. */
+const BANNED: readonly BannedPattern[] = [
+  {
+    pattern: /\bupdate-refs\b/,
+    reason: "retired `update-refs` (now `sources update`)",
+  },
+  { pattern: /pragma\s+llm\b/, reason: "retired `llm` tool" },
+  { pattern: /pragma\s+data\b/, reason: "retired `data` noun (now `sources`)" },
+  {
+    pattern: /pragma\s+tokens\b/,
+    reason: "retired plural `tokens` noun (now singular `token`)",
+  },
+  {
+    pattern: /\btokens_(list|lookup|sample|add-config)\b/,
+    reason: "retired plural `tokens_*` tools (now `token_*`)",
+  },
+  {
+    pattern: /--llm\b/,
+    reason:
+      "retired `--llm` flag (now the `--format llm` form, auto-detected when piped)",
+  },
+  {
+    pattern: /--all-tiers\b/,
+    reason:
+      "retired `--all-tiers` flag (L-OPEN-9: `block list` is the declared, unfiltered story — there is no tier filter to escape)",
+  },
+  {
+    pattern: /\btoken[ _]add-config\b/,
+    reason:
+      "removed `token add-config` command / `token_add-config` tool (L-OPEN-9: a mutation the declared read grammar has no verb for)",
+  },
+];
+
+// Every shipped doc must be free of retired vocabulary: the README plus every
+// page under `docs/`. CHANGELOG.md (at the package root, outside `docs/`) is
+// DELIBERATELY exempt — its migration table legitimately cites the retired
+// names (`data`, `update-refs`, plural `tokens`) to tell readers what they
+// became, so scanning it would false-positive on that historical vocabulary.
+const files = [
+  join(packageRoot, "README.md"),
+  ...collectMarkdown(join(packageRoot, "docs")),
+];
+
+describe("stale-command gate — docs never mention retired v1 commands", () => {
+  for (const file of files) {
+    const rel = relative(packageRoot, file);
+    it(`${rel} is free of retired commands`, () => {
+      const content = readFileSync(file, "utf-8");
+      for (const { pattern, reason } of BANNED) {
+        expect(pattern.test(content), `${rel}: ${reason}`).toBe(false);
+      }
+    });
+  }
+});

package/src/testing/eval/__snapshots__/eval.test.ts.snap

@@ -2,6 +2,11 @@
 
 exports[`eval harness — seed gate > runs the full seed (stable + read-noun) cases clean 1`] = `
 [
+  {
+    "id": "content-block-list-is-channel-independent",
+    "kind": "content",
+    "passed": true,
+  },
   {
     "id": "content-canonical-graph-has-4-components",
     "kind": "content",
@@ -57,11 +62,6 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "content",
     "passed": true,
   },
-  {
-    "id": "content-normal-channel-drops-beta-only-block",
-    "kind": "content",
-    "passed": true,
-  },
   {
     "id": "content-standard-list-length-equals-category-count-sum",
     "kind": "content",
@@ -103,7 +103,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "prompt-set-tier-maps-to-config-tier",
+    "id": "prompt-set-tier-maps-to-config-set",
     "kind": "prompt",
     "passed": true,
   },
@@ -113,7 +113,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "prompt-tokens-config-maps-to-token-add-config",
+    "id": "prompt-tokens-config-maps-to-nothing",
     "kind": "prompt",
     "passed": true,
   },
@@ -138,7 +138,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "tool-config-tier-is-plan-first",
+    "id": "tool-config-set-is-plan-first",
     "kind": "tool",
     "passed": true,
   },
@@ -183,7 +183,7 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "tool-token-add-config-is-plan-first",
+    "id": "tool-token-noun-is-read-only",
     "kind": "tool",
     "passed": true,
   },

package/src/testing/eval/cases/assembly.ts

@@ -163,23 +163,30 @@ export const assemblyEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "prompt-set-tier-maps-to-config-tier",
+    id: "prompt-set-tier-maps-to-config-set",
     kind: "prompt",
-    input: '"Set the active tier" should map to `config_tier`.',
+    input: '"Set the active tier" should map to `config_set` (B3).',
     async expect({ mcp }) {
-      assertIntentTool(await mcp.listTools(), "config_tier", /tier/i);
+      assertIntentTool(await mcp.listTools(), "config_set", /tier/i);
     },
   },
   {
-    id: "prompt-tokens-config-maps-to-token-add-config",
+    id: "prompt-tokens-config-maps-to-nothing",
     kind: "prompt",
     input:
-      '"Generate a terrazzo tokens config" should map to `token_add-config`.',
+      '"Generate a terrazzo tokens config" maps to NO tool — `token_add-config` was removed in L-OPEN-9, and the token noun is read-only.',
     async expect({ mcp }) {
-      assertIntentTool(
-        await mcp.listTools(),
-        "token_add-config",
-        /token|terrazzo/i,
+      // The inverse of an intent-mapping case, and the point of the ruling: an
+      // agent asked to write a tokens config finds nothing in the catalog that
+      // claims to do it, rather than a verb the declared grammar cannot express.
+      const tools = await mcp.listTools();
+      assert.ok(
+        !tools.some(
+          (tool) =>
+            tool.name === "token_add-config" ||
+            /terrazzo|tokens\.config/i.test(String(tool.description ?? "")),
+        ),
+        "no tool may still offer to write a tokens config",
       );
     },
   },

package/src/testing/eval/cases/effectful.ts

@@ -70,12 +70,15 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "tool-config-tier-is-plan-first",
+    id: "tool-config-set-is-plan-first",
     kind: "tool",
     input:
-      "config_tier without `confirm` returns a plan (planOnly) and writes nothing — the uniform plan-first mutation contract.",
+      "config_set without `confirm` returns a plan (planOnly) and writes nothing — the uniform plan-first mutation contract.",
     async expect({ mcp }) {
-      const result = await mcp.callTool("config_tier", { path: "apps/lxd" });
+      const result = await mcp.callTool("config_set", {
+        key: "tier",
+        value: "apps/lxd",
+      });
       assert.equal(result.ok, true);
       const meta = result.meta as { planOnly?: boolean };
       assert.equal(meta.planOnly, true);
@@ -167,18 +170,23 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "tool-token-add-config-is-plan-first",
+    id: "tool-token-noun-is-read-only",
     kind: "tool",
     input:
-      "token_add-config (needsStore mutation) without `confirm` returns a plan naming tokens.config.mjs and writes nothing.",
+      "the `token` noun exposes only reads — `token_add-config` (the tokens.config.mjs writer) was REMOVED in L-OPEN-9, not ported.",
     async expect() {
       await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
-        const result = await mcp.callTool("token_add-config");
-        assert.equal(result.ok, true);
-        const meta = result.meta as { planOnly?: boolean };
-        assert.equal(meta.planOnly, true);
-        const data = result.data as { plan: string[] };
-        assert.match(data.plan.join("\n"), /tokens\.config\.mjs/);
+        // This case used to pin `token_add-config`'s plan-first contract. The
+        // verb is gone, so it pins the ruling instead: the read surface is
+        // declared content and carries no mutation. (The plan-first MECHANIC is
+        // still covered by `tool-config-set-is-plan-first` and
+        // `tool-upgrade-is-plan-first`.)
+        const tools = (await mcp.listTools()).map((tool) => tool.name);
+        assert.ok(!tools.includes("token_add-config"));
+        assert.deepEqual(
+          tools.filter((name) => name.startsWith("token")).sort(),
+          ["token_list", "token_lookup", "token_sample"],
+        );
       });
     },
   },
@@ -186,14 +194,21 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     id: "tool-tier-lookup-lists-scoped-blocks",
     kind: "tool",
     input:
-      "tier_lookup {name:apps/lxd} resolves the tier and lists the blocks scoped to it (LXD Panel).",
+      "tier_lookup {name:[apps/lxd]} resolves the tier and expands the blocks scoped to it (LXD Panel).",
     async expect() {
       await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
-        const result = await mcp.callTool("tier_lookup", { name: "apps/lxd" });
+        // The declared pack lookup (L-OPEN-9): variadic names in, the uniform
+        // `{ results, errors }` lookup envelope out, blocks as an expand.
+        const result = await mcp.callTool("tier_lookup", {
+          name: ["apps/lxd"],
+        });
         assert.equal(result.ok, true);
-        const data = result.data as { name: string; blocks: string[] };
-        assert.equal(data.name, "apps/lxd");
-        assert.ok(data.blocks.includes("LXD Panel"));
+        const data = result.data as {
+          results: { name: string; blocks: { name: string }[] }[];
+        };
+        const tier = data.results[0];
+        assert.equal(tier?.name, "apps/lxd");
+        assert.ok(tier?.blocks.some((block) => block.name === "LXD Panel"));
       });
     },
   },

package/src/testing/eval/cases/readNouns.ts

@@ -90,16 +90,19 @@ export const readNounEvalCases: readonly EvalCase[] = [
     id: "content-canonical-graph-has-4-components",
     kind: "content",
     input:
-      "the canonical fixture graph carries exactly 4 ds:Component individuals, including Button and Beta Widget.",
+      "the canonical fixture graph carries 4 ds:Component individuals (Button, Modal, LXD Panel, Beta Widget); block_list also surfaces the untiered Button Icon subcomponent (A2).",
     async expect() {
       await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
-        const result = await mcp.callTool("block_list", { allTiers: true });
+        const result = await mcp.callTool("block_list");
         const names = (result.data as { name: string }[])
           .map((r) => r.name)
           .sort();
+        // The declared list takes no arguments and filters nothing: the 4 tiered
+        // components plus the untiered Button Icon subcomponent (A2).
         assert.deepEqual(names, [
           "Beta Widget",
           "Button",
+          "Button Icon",
           "LXD Panel",
           "Modal",
         ]);
@@ -165,25 +168,27 @@ export const readNounEvalCases: readonly EvalCase[] = [
     },
   },
   {
-    id: "content-normal-channel-drops-beta-only-block",
+    id: "content-block-list-is-channel-independent",
     kind: "content",
     input:
-      "the normal channel (CANONICAL_CONFIG) excludes the beta-only block; the prerelease channel (ALL_VISIBLE_CONFIG) includes it.",
+      "block_list returns the SAME rows on the normal channel (CANONICAL_CONFIG) and the prerelease one (ALL_VISIBLE_CONFIG) — including the beta-only block, which the normal channel used to hide (L-OPEN-9).",
     async expect() {
-      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
-        const normal = await mcp.callTool("block_list", { allTiers: true });
-        const normalNames = (normal.data as { name: string }[]).map(
-          (r) => r.name,
-        );
-        assert.ok(!normalNames.includes("Beta Widget"));
-      });
-      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
-        const prerelease = await mcp.callTool("block_list", { allTiers: true });
-        const prereleaseNames = (prerelease.data as { name: string }[]).map(
-          (r) => r.name,
-        );
-        assert.ok(prereleaseNames.includes("Beta Widget"));
-      });
+      const namesUnder = async (
+        config: typeof CANONICAL_CONFIG | typeof ALL_VISIBLE_CONFIG,
+      ): Promise<string[]> => {
+        let names: string[] = [];
+        await withCanonicalFixture(config, async (mcp) => {
+          const result = await mcp.callTool("block_list");
+          names = (result.data as { name: string }[]).map((r) => r.name).sort();
+        });
+        return names;
+      };
+      const normal = await namesUnder(CANONICAL_CONFIG);
+      const prerelease = await namesUnder(ALL_VISIBLE_CONFIG);
+      // The signed-off consequence: an experimental block is visible to
+      // everyone, on every channel, until filtering returns in declared form.
+      assert.ok(normal.includes("Beta Widget"));
+      assert.deepEqual(normal, prerelease);
     },
   },
   {

package/src/testing/eval/cases/stable.ts

@@ -110,7 +110,11 @@ export const stableEvalCases: readonly EvalCase[] = [
       try {
         const widgetModule: CapabilityModule = {
           name: "widget",
-          verbs: compilePack(WIDGET_PACK, "test:widget", WIDGET_PREFIXES),
+          verbs: compilePack(
+            WIDGET_PACK,
+            { label: "test:widget", origin: "package" },
+            WIDGET_PREFIXES,
+          ),
         };
         const mcp = await projectMcp([widgetModule], fixture.cwd);
         try {

package/src/testing/eval/eval.test.ts

@@ -70,5 +70,11 @@ describe("eval harness — seed gate", () => {
     expect(report.cases.length).toBeGreaterThanOrEqual(35);
     expect(report.cases.length).toBeLessThanOrEqual(60);
     expect(normalize(report.cases)).toMatchSnapshot();
-  });
+    // Explicit timeout, like the other suite-level gates: this drives every
+    // seed case through a real runtime AND a real MCP server, and since a
+    // preview now performs its reads for real rather than answering from a
+    // mock, the effectful cases pay genuine IO. Measured 3.7s before that
+    // change and 5.4s after, so the vitest 5s default fails it on cost the
+    // PR intends to pay — not on a defect. 60s leaves room for CI contention.
+  }, 60_000);
 });

package/src/testing/fixtures/fixtureCapability.ts

@@ -7,7 +7,7 @@
 
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { $, gen, succeed, writeFile } from "@canonical/task";
+import { $, gen, readFile, succeed, writeFile } from "@canonical/task";
 import type { CapabilityModule } from "../../kernel/spec/types.js";
 
 /** A synthetic module: noun `widget`, three verbs (one hidden). */
@@ -173,3 +173,203 @@ export const fixtureEffectsModule: CapabilityModule = {
     },
   ],
 };
+
+/**
+ * A synthetic module for the HONEST-preview guards (PR7). `probe graft` READS a
+ * file before writing beside it, so a run whose source is missing dies on its
+ * first effect. The mock previewer answered that read with a placeholder string
+ * and reported a confident plan with exit 0 — the structural false positive
+ * PRA-104 indicts. Under `runPreview` the read is real, so `--dry-run` (and the
+ * MCP plan-first twin) fail exactly where and how the run would. Test-only (D8)
+ * — never listed in `capabilities/index.ts`.
+ */
+export const fixturePreviewModule: CapabilityModule = {
+  name: "fixture-preview",
+  verbs: [
+    {
+      path: ["probe", "graft"],
+      summary: "Copy a file's content into a sibling.",
+      params: [
+        {
+          kind: "string",
+          name: "source",
+          doc: "The file to read.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: false, openWorldHint: false },
+        },
+      },
+      run: (p) =>
+        gen(function* () {
+          const { source } = p as { source: string };
+          const content = yield* $(readFile(source));
+          yield* $(writeFile(`${source}.grafted`, content));
+          return { grafted: source };
+        }),
+    },
+  ],
+};
+
+/**
+ * A synthetic module that exercises every RENDER path of `emitReference` (D8 —
+ * never listed in `src/capabilities/index.ts`). Distinct from `fixtureModule`,
+ * which only exercises `emitSurface`: this one carries the doc-only shapes the
+ * reference generator reads and the machine surface ignores — a rich `doc`,
+ * examples with and without notes, a {@link DisclosureSpec}, every param kind
+ * as a flag (including a repeatable `string[]` flag), an OPTIONAL variadic
+ * positional, a destructive mutation AND a non-destructive one (the two
+ * `formatToolAnnotations` mutation branches), a visible MCP-withheld verb, a
+ * self-verb, a hidden verb the emitter must drop, and — so `renderNonToolSurface`
+ * renders both its optional bullets — an `mcpResources` template surface and an
+ * `mcpPrompts` native-prompt surface. The `register` hooks are no-ops: the
+ * reference emitter reads only `mcpResources.surface.templates` and the presence
+ * of `mcpPrompts`, never invoking either.
+ */
+export const fixtureReferenceModule: CapabilityModule = {
+  name: "fixture-reference",
+  verbs: [
+    {
+      path: ["gizmo", "scan"],
+      summary: "Scan the gizmos.",
+      doc: "Scan every gizmo under the active scope, optionally narrowing to named targets. Reads nothing off disk.",
+      params: [
+        {
+          kind: "string[]",
+          name: "targets",
+          doc: "Gizmo names to scan (all when omitted).",
+          positional: true,
+        },
+        {
+          kind: "enum",
+          name: "mode",
+          doc: "Scan mode.",
+          values: ["fast", "slow"],
+          default: "fast",
+        },
+        { kind: "number", name: "limit", doc: "Maximum gizmos to scan." },
+        { kind: "string", name: "label", doc: "Label to stamp on the report." },
+        { kind: "string[]", name: "include", doc: "Extra globs to include." },
+        { kind: "boolean", name: "deep", doc: "Recurse into sub-gizmos." },
+      ],
+      output: { formatters: passthroughFormatters },
+      examples: [
+        { cmd: "pragma gizmo scan", note: "scan everything" },
+        { cmd: "pragma gizmo scan alpha --mode slow" },
+      ],
+      disclosure: { levels: ["summary", "detailed"], default: "summary" },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ scanned: true }),
+    },
+    {
+      path: ["gizmo", "wipe"],
+      summary: "Wipe a gizmo.",
+      params: [
+        {
+          kind: "string",
+          name: "path",
+          doc: "The gizmo path to wipe.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: true,
+        mutates: true,
+        destructive: true,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ wiped: true }),
+    },
+    {
+      path: ["gizmo", "tidy"],
+      summary: "Tidy the gizmo cache.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        destructive: false,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ tidied: true }),
+    },
+    {
+      path: ["gizmo", "local"],
+      summary: "A visible gizmo verb withheld from MCP.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "CLI-only local helper" },
+      },
+      run: async () => ({ local: true }),
+    },
+    {
+      path: ["ping"],
+      summary: "Ping the gizmo host.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ pong: true }),
+    },
+    {
+      path: ["gizmo", "hidden"],
+      summary: "Hidden gizmo probe.",
+      hidden: true,
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "internal probe" },
+      },
+      run: async () => ({ ok: true }),
+    },
+  ],
+  // A non-tool MCP surface, so `renderNonToolSurface` emits its Resources bullet.
+  // `register` is a no-op — the emitter reads only `surface.templates`.
+  mcpResources: {
+    surface: { templates: ["gizmo:{+uri}"] },
+    register: () => {},
+  },
+  // A native prompt surface, so `renderNonToolSurface` emits its Prompts bullet.
+  mcpPrompts: { register: () => {} },
+};

package/src/testing/fixtures/graph/canonical.ts

@@ -6,9 +6,12 @@
  * `block` content-parity + `ontology`/`graph inspect` tests are protected
  * against) byte-for-byte and EXTENDS it with the entities the other bundled
  * read nouns (`standard`, `modifier`, `token`, `tier`) need, plus two more
- * blocks that exercise tier-chain inheritance and channel visibility (PR3's
- * hand-written `block list`, Risk5). Because `BLOCK_TTL` is reused verbatim,
- * Button/Modal content can never drift between PR3's fixture and this one.
+ * blocks that used to exercise tier-chain inheritance and channel visibility
+ * (PR3's hand-written `block list`, Risk5). Those two now serve the opposite
+ * purpose: L-OPEN-9 removed the filtering, so a tier-scoped and a
+ * channel-gated block are what prove the declared list hides NEITHER. Because
+ * `BLOCK_TTL` is reused verbatim, Button/Modal content can never drift between
+ * PR3's fixture and this one.
  *
  * Composed as one Turtle document, so ONE store answers every read noun:
  * `block`/`ontology`/`graph inspect` were already provable on `BLOCK_TTL`