@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,195 @@
+/**
+ * Assembly-level eval cases (PR7 nouns) — the orientation surface `capabilities`
+ * + `instructions` + native prompts add ABOVE per-noun tools.
+ *
+ * These run over the shared `env.mcp` (the live catalog), so they cost no fixture
+ * boot: the catalog, the tool descriptions, the instructions, and the handshake
+ * capabilities are all storeless. The NL-intent ("prompt") cases assert that an
+ * agent following the annotated catalog would reach the right tool — the payoff
+ * of the orientation surface. Data-backed prompt/graph cases live in
+ * `cases/effectful.ts`. R2: no noun list is hard-coded — the catalog is read live.
+ */
+
+import assert from "node:assert/strict";
+import { capabilities } from "../../../capabilities/index.js";
+import { emitSurface } from "../../../kernel/spec/emitSurface.js";
+import type { EvalCase } from "../harness.js";
+
+/** Assert an intent maps to a tool by checking that tool's advertised description. */
+function assertIntentTool(
+  tools: { name: string; description?: string }[],
+  tool: string,
+  pattern: RegExp,
+): void {
+  const found = tools.find((t) => t.name === tool);
+  assert.ok(found, `expected a \`${tool}\` tool in the catalog`);
+  assert.match(String(found?.description ?? ""), pattern);
+}
+
+export const assemblyEvalCases: readonly EvalCase[] = [
+  {
+    id: "tool-capabilities-annotates-every-live-tool",
+    kind: "tool",
+    input:
+      "the `capabilities` tool catalogs EVERY live tool, each with a non-empty use_when hint.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("capabilities");
+      const data = result.data as {
+        tools: { name: string; use_when: string }[];
+      };
+      const live = (await mcp.listTools()).map((t) => t.name).sort();
+      assert.deepEqual(
+        data.tools.map((t) => t.name).sort(),
+        live,
+        "capabilities catalog must cover exactly the live tool set",
+      );
+      for (const tool of data.tools) {
+        assert.ok(
+          tool.use_when.length > 0,
+          `tool ${tool.name} has an empty use_when`,
+        );
+      }
+    },
+  },
+  {
+    id: "content-capabilities-counts-derived-from-categories",
+    kind: "content",
+    input:
+      "the capabilities counts are derived (total == tools.length; category sizes sum to total; orientation=1, diagnostic=2).",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("capabilities");
+      const data = result.data as {
+        tools: unknown[];
+        counts: {
+          total: number;
+          read: number;
+          write: number;
+          orientation: number;
+          diagnostic: number;
+        };
+      };
+      const { counts } = data;
+      assert.equal(counts.total, data.tools.length);
+      assert.equal(
+        counts.read + counts.write + counts.orientation + counts.diagnostic,
+        counts.total,
+      );
+      assert.equal(counts.orientation, 1);
+      assert.equal(counts.diagnostic, 2);
+    },
+  },
+  {
+    id: "content-capabilities-selfconsistent-with-emitsurface",
+    kind: "content",
+    input:
+      "the capabilities catalog tool set equals emitSurface(capabilities).mcpSurface.tools (grammar self-consistency).",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("capabilities");
+      const data = result.data as { tools: { name: string }[] };
+      assert.deepEqual(
+        data.tools.map((t) => t.name).sort(),
+        [...emitSurface(capabilities).mcpSurface.tools].sort(),
+      );
+    },
+  },
+  {
+    id: "content-instructions-present-and-mentions-discovery",
+    kind: "content",
+    input:
+      "the server sends handshake instructions that mention `capabilities` and the discovery flow.",
+    async expect({ mcp }) {
+      const instructions = mcp.instructions();
+      assert.ok(instructions, "expected server instructions at initialize");
+      assert.match(String(instructions), /capabilities/);
+      assert.match(String(instructions).toLowerCase(), /discovery/);
+    },
+  },
+  {
+    id: "content-handshake-advertises-tools-resources-prompts",
+    kind: "content",
+    input:
+      "the initialize handshake advertises the tools, resources, AND prompts capabilities.",
+    async expect({ mcp }) {
+      const caps = mcp.serverCapabilities();
+      assert.ok(caps?.tools, "expected a tools capability");
+      assert.ok(caps?.resources, "expected a resources capability");
+      assert.ok(caps?.prompts, "expected a prompts capability");
+    },
+  },
+  {
+    id: "content-capabilities-covers-listtools",
+    kind: "content",
+    input:
+      "every tool the server lists appears in the capabilities catalog (no live tool is invisible to orientation).",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("capabilities");
+      const cataloged = new Set(
+        (result.data as { tools: { name: string }[] }).tools.map((t) => t.name),
+      );
+      for (const tool of await mcp.listTools()) {
+        assert.ok(
+          cataloged.has(tool.name),
+          `tool ${tool.name} is not in the capabilities catalog`,
+        );
+      }
+    },
+  },
+  {
+    id: "prompt-scaffold-maps-to-create-component",
+    kind: "prompt",
+    input: '"Scaffold a new component" should map to `create_component`.',
+    async expect({ mcp }) {
+      assertIntentTool(await mcp.listTools(), "create_component", /component/i);
+    },
+  },
+  {
+    id: "prompt-environment-maps-to-doctor",
+    kind: "prompt",
+    input: '"What is wrong with my environment?" should map to `doctor`.',
+    async expect({ mcp }) {
+      assertIntentTool(
+        await mcp.listTools(),
+        "doctor",
+        /diagnos|environment|health/i,
+      );
+    },
+  },
+  {
+    id: "prompt-sparql-maps-to-graph-query",
+    kind: "prompt",
+    input: '"Run an arbitrary SPARQL query" should map to `graph_query`.',
+    async expect({ mcp }) {
+      assertIntentTool(await mcp.listTools(), "graph_query", /sparql/i);
+    },
+  },
+  {
+    id: "prompt-set-tier-maps-to-config-tier",
+    kind: "prompt",
+    input: '"Set the active tier" should map to `config_tier`.',
+    async expect({ mcp }) {
+      assertIntentTool(await mcp.listTools(), "config_tier", /tier/i);
+    },
+  },
+  {
+    id: "prompt-tokens-config-maps-to-token-add-config",
+    kind: "prompt",
+    input:
+      '"Generate a terrazzo tokens config" should map to `token_add-config`.',
+    async expect({ mcp }) {
+      assertIntentTool(
+        await mcp.listTools(),
+        "token_add-config",
+        /token|terrazzo/i,
+      );
+    },
+  },
+  {
+    id: "prompt-browse-prompts-maps-to-prompt-list",
+    kind: "prompt",
+    input:
+      '"Browse the available workflow prompts" should map to `prompt_list`.',
+    async expect({ mcp }) {
+      assertIntentTool(await mcp.listTools(), "prompt_list", /prompt/i);
+    },
+  },
+];

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

@@ -0,0 +1,245 @@
+/**
+ * Effectful eval cases (PR6 + PR7 nouns): the SPARQL escape hatch, the plan-first
+ * mutations, the diagnostic self-verb, and the store-backed prompt content.
+ *
+ * Storeless cases (plan-first previews, doctor shape, invalid-query) run over the
+ * shared `env.mcp` (no fixture cost). Data-backed cases build their OWN canonical
+ * fixture (the `cases/readNouns.ts` pattern), so they stay independent of the
+ * shared env. Anchor VALUES come from the canonical fixture this package controls;
+ * noun/tool names are read from the live surface (R2).
+ */
+
+import assert from "node:assert/strict";
+import { capabilities } from "../../../capabilities/index.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../../fixtures/graph/canonical.js";
+import { bootFixtureRuntime } from "../../helpers/fixtureGraph.js";
+import { projectMcp } from "../../helpers/projectMcp.js";
+import type { EvalCase } from "../harness.js";
+
+/** Run one case's body against a fresh canonical fixture, always disposing. */
+async function withCanonicalFixture(
+  config: typeof CANONICAL_CONFIG | typeof ALL_VISIBLE_CONFIG,
+  body: (mcp: Awaited<ReturnType<typeof projectMcp>>) => Promise<void>,
+): Promise<void> {
+  const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL, config });
+  try {
+    const mcp = await projectMcp(capabilities, fixture.cwd);
+    try {
+      await body(mcp);
+    } finally {
+      await mcp.cleanup();
+    }
+  } finally {
+    await fixture.dispose();
+  }
+}
+
+export const effectfulEvalCases: readonly EvalCase[] = [
+  {
+    id: "tool-graph-query-counts-components",
+    kind: "tool",
+    input:
+      "graph_query (the real PR6 verb, closing graph-query-deferred) counts exactly 4 ds:Component individuals in the canonical graph.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("graph_query", {
+          sparql: "SELECT (COUNT(*) AS ?c) WHERE { ?comp a ds:Component }",
+        });
+        assert.equal(result.ok, true);
+        // graph_query returns the serialized QueryResult ({ type, bindings, … }).
+        const data = result.data as { bindings: { c: string }[] };
+        assert.equal(Number(data.bindings[0]?.c), 4);
+      });
+    },
+  },
+  {
+    id: "tool-graph-query-invalid-is-invalid-input",
+    kind: "tool",
+    input:
+      "graph_query with a syntax error returns INVALID_INPUT (exit-2 class), not a crash.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("graph_query", {
+        sparql: "NOT VALID SPARQL {{{",
+      });
+      assert.equal(result.ok, false);
+      assert.equal((result.error as { code: string }).code, "INVALID_INPUT");
+    },
+  },
+  {
+    id: "tool-config-tier-is-plan-first",
+    kind: "tool",
+    input:
+      "config_tier 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" });
+      assert.equal(result.ok, true);
+      const meta = result.meta as { planOnly?: boolean };
+      assert.equal(meta.planOnly, true);
+    },
+  },
+  {
+    id: "tool-doctor-reports-check-tallies",
+    kind: "tool",
+    input:
+      "doctor returns a { checks, passed, failed, skipped } diagnostic report where the tallies sum to the checks.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("doctor");
+      assert.equal(result.ok, true);
+      const data = result.data as {
+        checks: unknown[];
+        passed: number;
+        failed: number;
+        skipped: number;
+      };
+      assert.ok(Array.isArray(data.checks), "expected a checks array");
+      assert.equal(
+        data.passed + data.failed + data.skipped,
+        data.checks.length,
+      );
+    },
+  },
+  {
+    id: "tool-upgrade-is-plan-first",
+    kind: "tool",
+    input:
+      "upgrade without `confirm` returns a plan (planOnly) — the CLI self-upgrade never runs on a discovery call.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("upgrade");
+      assert.equal(result.ok, true);
+      const meta = result.meta as { planOnly?: boolean };
+      assert.equal(meta.planOnly, true);
+    },
+  },
+  {
+    id: "tool-prompt-list-resolves-authored-prompts",
+    kind: "tool",
+    input:
+      "prompt_list (needsStore) resolves the authored ds:Prompt entities, each carrying its arguments.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("prompt_list");
+        const data = result.data as { prompts: { name: string }[] };
+        assert.ok(
+          data.prompts.some((p) => p.name === "build-a-block"),
+          "expected the build-a-block prompt",
+        );
+      });
+    },
+  },
+  {
+    id: "content-native-prompts-list-nonempty",
+    kind: "content",
+    input:
+      "the native MCP prompts/list is non-empty over a graph with ds:Prompt entities, each with a description.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const prompts = await mcp.listPrompts();
+        assert.ok(prompts.length > 0, "expected native prompts");
+        for (const prompt of prompts) {
+          assert.ok(
+            prompt.description,
+            `prompt ${prompt.name} lacks a description`,
+          );
+        }
+      });
+    },
+  },
+  {
+    id: "content-native-prompt-get-fills-arguments",
+    kind: "content",
+    input:
+      "prompts/get materializes the body store-backed and substitutes {{arg}} placeholders.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const result = await mcp.getPrompt("build-a-block", {
+          blockName: "Button",
+        });
+        const first = result.messages[0] as {
+          content: { text: string };
+        };
+        assert.match(first.content.text, /Button/);
+        assert.ok(!first.content.text.includes("{{blockName}}"));
+      });
+    },
+  },
+  {
+    id: "tool-token-add-config-is-plan-first",
+    kind: "tool",
+    input:
+      "token_add-config (needsStore mutation) without `confirm` returns a plan naming tokens.config.mjs and writes nothing.",
+    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/);
+      });
+    },
+  },
+  {
+    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).",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        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"));
+      });
+    },
+  },
+  {
+    id: "tool-block-sample-returns-exemplars",
+    kind: "tool",
+    input:
+      "block_sample (the no-argument PR7 sample) returns complete block exemplars for shape discovery.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("block_sample");
+        assert.equal(result.ok, true);
+        const data = result.data as { samples: unknown[]; totalCount: number };
+        assert.ok(data.samples.length > 0, "expected at least one exemplar");
+        assert.ok(data.totalCount >= data.samples.length);
+      });
+    },
+  },
+  {
+    id: "tool-modifier-sample-returns-exemplars",
+    kind: "tool",
+    input:
+      "modifier_sample (the no-argument PR7 sample) returns complete modifier exemplars for shape discovery.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("modifier_sample");
+        assert.equal(result.ok, true);
+        const data = result.data as { samples: unknown[]; totalCount: number };
+        assert.ok(data.samples.length > 0, "expected at least one exemplar");
+        assert.ok(data.totalCount >= data.samples.length);
+      });
+    },
+  },
+  {
+    id: "tool-token-sample-returns-exemplars",
+    kind: "tool",
+    input:
+      "token_sample (the no-argument PR7 sample) returns complete token exemplars for shape discovery.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("token_sample");
+        assert.equal(result.ok, true);
+        const data = result.data as { samples: unknown[]; totalCount: number };
+        assert.ok(data.samples.length > 0, "expected at least one exemplar");
+        assert.ok(data.totalCount >= data.samples.length);
+      });
+    },
+  },
+];

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

@@ -0,0 +1,232 @@
+/**
+ * Read-noun eval seed cases (commit 4) — extends `cases/stable.ts` once PR3's
+ * read nouns are live. Representative, NOT exhaustive (PR7 populates the full
+ * MCP eval matrix); each case builds its OWN fixture via `bootFixtureRuntime`
+ * so it stays independent of `eval.test.ts`'s shared env.
+ *
+ * Anchor VALUES (Button, `importance`->`primary`, `code/function/purity`, 4
+ * components) come from the ported canonical fixture graph
+ * (`testing/fixtures/graph/canonical.ts`), which THIS package controls — not
+ * from PR3's noun/verb/tool SET, which is read from the live surface
+ * elsewhere (`liveReadSurface.ts`) per R2.
+ */
+
+import assert from "node:assert/strict";
+import { capabilities } from "../../../capabilities/index.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../../fixtures/graph/canonical.js";
+import { bootFixtureRuntime } from "../../helpers/fixtureGraph.js";
+import { projectMcp } from "../../helpers/projectMcp.js";
+import type { EvalCase } from "../harness.js";
+
+/** Run one case's body against a fresh canonical fixture, always disposing. */
+async function withCanonicalFixture(
+  config: typeof CANONICAL_CONFIG | typeof ALL_VISIBLE_CONFIG,
+  body: (mcp: Awaited<ReturnType<typeof projectMcp>>) => Promise<void>,
+): Promise<void> {
+  const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL, config });
+  try {
+    const mcp = await projectMcp(capabilities, fixture.cwd);
+    try {
+      await body(mcp);
+    } finally {
+      await mcp.cleanup();
+    }
+  } finally {
+    await fixture.dispose();
+  }
+}
+
+export const readNounEvalCases: readonly EvalCase[] = [
+  {
+    id: "tool-block-lookup-button-has-modifier-families",
+    kind: "tool",
+    input:
+      "block_lookup {name:[Button]} resolves name===Button and carries modifierFamilies.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("block_lookup", { name: ["Button"] });
+        assert.equal(result.ok, true);
+        const entity = (result.data as { results: Record<string, unknown>[] })
+          .results[0];
+        assert.equal(entity?.name, "Button");
+        assert.ok(
+          Array.isArray(entity?.modifierFamilies) &&
+            (entity.modifierFamilies as unknown[]).length > 0,
+          "expected a non-empty modifierFamilies array",
+        );
+      });
+    },
+  },
+  {
+    id: "tool-standard-lookup-has-dos-and-donts",
+    kind: "tool",
+    input:
+      "standard_lookup {name:[react/component/props], detail:detailed} has non-empty dos and donts.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("standard_lookup", {
+          name: ["react/component/props"],
+          detail: "detailed",
+        });
+        assert.equal(result.ok, true);
+        const entity = (result.data as { results: Record<string, unknown>[] })
+          .results[0];
+        assert.ok(
+          (entity?.dos as unknown[])?.length > 0,
+          "expected non-empty dos",
+        );
+        assert.ok(
+          (entity?.donts as unknown[])?.length > 0,
+          "expected non-empty donts",
+        );
+      });
+    },
+  },
+  {
+    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.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("block_list", { allTiers: true });
+        const names = (result.data as { name: string }[])
+          .map((r) => r.name)
+          .sort();
+        assert.deepEqual(names, [
+          "Beta Widget",
+          "Button",
+          "LXD Panel",
+          "Modal",
+        ]);
+      });
+    },
+  },
+  {
+    id: "content-code-function-purity-description-mentions-pure",
+    kind: "content",
+    input: "the code/function/purity standard's description contains 'pure'.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("standard_lookup", {
+          name: ["code/function/purity"],
+        });
+        const entity = (result.data as { results: Record<string, unknown>[] })
+          .results[0];
+        assert.match(String(entity?.description ?? ""), /pure/i);
+      });
+    },
+  },
+  {
+    id: "content-importance-family-includes-primary",
+    kind: "content",
+    input: "the modifier family `importance` includes the value `primary`.",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const result = await mcp.callTool("modifier_lookup", {
+          name: ["importance"],
+        });
+        const entity = (result.data as { results: Record<string, unknown>[] })
+          .results[0];
+        const values = (entity?.values as { name: string }[] | undefined)?.map(
+          (v) => v.name,
+        );
+        assert.ok(
+          values?.includes("primary"),
+          `expected "primary" in ${values}`,
+        );
+      });
+    },
+  },
+  {
+    id: "content-standard-list-length-equals-category-count-sum",
+    kind: "content",
+    input:
+      "standard_list length equals the sum of standard_categories counts (the cross-surface count-parity invariant).",
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const list = await mcp.callTool("standard_list");
+        const categories = await mcp.callTool("standard_categories");
+        const listLength = (list.data as unknown[]).length;
+        const categorySum = (categories.data as { count: string }[]).reduce(
+          (sum, row) => sum + Number(row.count),
+          0,
+        );
+        assert.ok(
+          listLength > 0,
+          "standard_list must be non-empty for the count-parity invariant to be meaningful",
+        );
+        assert.equal(listLength, categorySum);
+      });
+    },
+  },
+  {
+    id: "content-normal-channel-drops-beta-only-block",
+    kind: "content",
+    input:
+      "the normal channel (CANONICAL_CONFIG) excludes the beta-only block; the prerelease channel (ALL_VISIBLE_CONFIG) includes it.",
+    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"));
+      });
+    },
+  },
+  {
+    id: "disclosure-block-lookup-detailed-adds-anatomy",
+    kind: "disclosure",
+    input:
+      "block_lookup {name:[Button], detail:summary} omits anatomyDsl; {detail:detailed} includes it.",
+    async expect() {
+      await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
+        const summary = await mcp.callTool("block_lookup", {
+          name: ["Button"],
+          detail: "summary",
+        });
+        const detailed = await mcp.callTool("block_lookup", {
+          name: ["Button"],
+          detail: "detailed",
+        });
+        const summaryEntity = (
+          summary.data as { results: Record<string, unknown>[] }
+        ).results[0];
+        const detailedEntity = (
+          detailed.data as { results: Record<string, unknown>[] }
+        ).results[0];
+        assert.equal(summaryEntity?.anatomyDsl, undefined);
+        assert.equal(
+          detailedEntity?.anatomyDsl,
+          "root: button; children: label, icon",
+        );
+      });
+    },
+  },
+  {
+    id: "prompt-block-question-maps-to-block-lookup",
+    kind: "prompt",
+    input:
+      '"What is the anatomy of the Button component?" should map to `block_lookup`.',
+    async expect() {
+      await withCanonicalFixture(CANONICAL_CONFIG, async (mcp) => {
+        const tools = await mcp.listTools();
+        const blockLookup = tools.find((t) => t.name === "block_lookup");
+        assert.ok(blockLookup, "expected a block_lookup tool in the catalog");
+        assert.match(String(blockLookup?.description ?? ""), /block/i);
+      });
+    },
+  },
+];