@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/llm/data/toolCatalog.ts

@@ -1,5 +1,7 @@
 /** Tool catalog with behavioral hints for agent orientation. */
 
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
+
 export interface ToolEntry {
   readonly name: string;
   readonly category: "read" | "write" | "orientation" | "diagnostic";
@@ -49,18 +51,22 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when:
       "Need values and usage details for specific modifier families by name",
   },
-  {
-    name: "token_list",
-    category: "read",
-    use_when:
-      "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
-  },
-  {
-    name: "token_lookup",
-    category: "read",
-    use_when:
-      "Need theme values and resolution details for specific tokens by name or IRI",
-  },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          name: "token_list",
+          category: "read",
+          use_when:
+            "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
+        },
+        {
+          name: "token_lookup",
+          category: "read",
+          use_when:
+            "Need theme values and resolution details for specific tokens by name or IRI",
+        },
+      ] as const)
+    : []),
   {
     name: "tier_list",
     category: "read",
@@ -101,23 +107,33 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when: "Discovering agent skills provided by installed packages",
   },
   {
-    name: "block_sample",
+    name: "skill_lookup",
     category: "read",
     use_when:
-      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
+      "Loading full SKILL.md instructions for a specific agent skill by name",
   },
   {
-    name: "standard_sample",
+    name: "block_sample",
     category: "read",
     use_when:
-      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
+      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
   },
   {
-    name: "token_sample",
+    name: "standard_sample",
     category: "read",
     use_when:
-      "See actual token data shapes (with theme values) before querying — returns random instances each call",
+      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
   },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          name: "token_sample",
+          category: "read",
+          use_when:
+            "See actual token data shapes (with theme values) before querying — returns random instances each call",
+        },
+      ] as const)
+    : []),
   {
     name: "modifier_sample",
     category: "read",
@@ -154,6 +170,27 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when:
       "Scaffolding a new npm package with proper monorepo configuration",
   },
+  {
+    name: "create_application",
+    category: "write",
+    use_when:
+      "Scaffolding a new React application with SSR, routing, and optional Relay",
+  },
+  {
+    name: "create_domain",
+    category: "write",
+    use_when: "Scaffolding a new domain module inside an existing application",
+  },
+  {
+    name: "create_route",
+    category: "write",
+    use_when: "Scaffolding a new route inside an existing application",
+  },
+  {
+    name: "create_wrapper",
+    category: "write",
+    use_when: "Scaffolding a new wrapper component inside an application",
+  },
 
   // — Orientation —————————————————————————————————————————————————————————————
   {

package/src/domains/llm/formatters/orientation.ts

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { LlmData } from "../types.js";
 
 /**
@@ -22,8 +23,11 @@ export default function renderLlmOrientation(data: LlmData): string {
   lines.push("");
   lines.push("## Context");
   lines.push(`tier: ${tierDisplay} | channel: ${ctx.channel}`);
+  const tokenCount = TOKEN_READ_SURFACE_ENABLED
+    ? `, ${ctx.counts.tokens} tokens`
+    : "";
   lines.push(
-    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families, ${ctx.counts.tokens} tokens`,
+    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families${tokenCount}`,
   );
   lines.push(`namespaces: ${ctx.namespaces.join(", ")}`);
   lines.push("");

package/src/domains/llm/llmCommand.test.ts

@@ -3,6 +3,7 @@ import type { Store } from "@canonical/ke";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { createTestStore, DS_ALL_TTL } from "#testing";
 import type { PragmaContext } from "../shared/context.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
 import { buildLlmCommand } from "./commands/index.js";
 import type { LlmData } from "./types.js";
 
@@ -72,14 +73,21 @@ describe("buildLlmCommand", () => {
     expect(value.context.namespaces.length).toBeGreaterThan(0);
   });
 
-  it("includes all 5 decision trees", async () => {
+  it("includes all decision trees", async () => {
     const ctx = makeCtx();
     const cmd = buildLlmCommand(ctx);
     const { value, text } = await executeOutput(cmd, ctx);
-    expect(value.decisionTrees).toHaveLength(5);
+    // "Find a token" is gated behind the token read-surface feature flag.
+    expect(value.decisionTrees).toHaveLength(
+      TOKEN_READ_SURFACE_ENABLED ? 5 : 4,
+    );
     expect(text).toContain("Build a block");
     expect(text).toContain("Audit standards");
-    expect(text).toContain("Find a token");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(text).toContain("Find a token");
+    } else {
+      expect(text).not.toContain("Find a token");
+    }
     expect(text).toContain("Explore the design system");
     expect(text).toContain("Configure");
   });

package/src/domains/llm/mcp/specs.ts

@@ -5,6 +5,7 @@
 import { VERSION } from "#constants";
 import { buildFilterConfig } from "../../shared/filters/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import {
   COMMAND_REFERENCE,
   DECISION_TREES,
@@ -43,14 +44,12 @@ function buildCapabilitiesData(): CapabilitiesData {
       {
         stage: 2,
         tool: "*_sample",
-        purpose:
-          "Call block_sample, standard_sample, token_sample, or modifier_sample to see real data shapes before querying. Prevents guessing at property names.",
+        purpose: `Call block_sample, standard_sample,${TOKEN_READ_SURFACE_ENABLED ? " token_sample," : ""} or modifier_sample to see real data shapes before querying. Prevents guessing at property names.`,
       },
       {
         stage: 3,
         tool: "domain tools",
-        purpose:
-          "Query specific entities — block_list, standard_lookup, token_list, etc. Use the use_when hints above to pick the right tool.",
+        purpose: `Query specific entities — block_list, standard_lookup, ${TOKEN_READ_SURFACE_ENABLED ? "token_list, " : ""}etc. Use the use_when hints above to pick the right tool.`,
       },
     ],
     tools: TOOL_CATALOG,

package/src/domains/llm/operations/collectContext.test.ts

@@ -0,0 +1,64 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { FilterConfig } from "../../shared/types/index.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
+import { renderLlmOrientation } from "../formatters/index.js";
+import type { LlmData } from "../types.js";
+import collectContext from "./collectContext.js";
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+const config: FilterConfig = { tier: undefined, channel: "prerelease" };
+
+/** Extract the `## Context` data lines from a rendered orientation doc. */
+function contextBlock(rendered: string): string {
+  const lines = rendered.split("\n");
+  const start = lines.indexOf("## Context");
+  const block: string[] = [];
+  for (let i = start + 1; i < lines.length && lines[i] !== ""; i++) {
+    block.push(lines[i] ?? "");
+  }
+  return block.join("\n");
+}
+
+describe("collectContext", () => {
+  it("assembles counts and namespaces from the store", async () => {
+    const ctx = await collectContext(store, config);
+
+    expect(ctx.tier).toBeUndefined();
+    expect(ctx.channel).toBe("prerelease");
+    expect(ctx.counts.blocks).toBeGreaterThan(0);
+    expect(ctx.counts.standards).toBeGreaterThan(0);
+    expect(ctx.counts.modifierFamilies).toBeGreaterThan(0);
+    expect(ctx.counts.tokens).toBeGreaterThan(0);
+    expect(ctx.namespaces.length).toBeGreaterThan(0);
+  });
+
+  it("renders a stable `## Context` block", async () => {
+    const data: LlmData = {
+      context: await collectContext(store, config),
+      decisionTrees: [],
+      commandReference: [],
+    };
+
+    // The token count only renders while the token read surface is enabled.
+    const tokenSegment = TOKEN_READ_SURFACE_ENABLED ? ", 2 tokens" : "";
+    expect(contextBlock(renderLlmOrientation(data))).toBe(
+      [
+        "tier: (none) | channel: prerelease",
+        `data: 5 blocks, 3 standards, 2 modifier families${tokenSegment}`,
+        "namespaces: cs, ds",
+      ].join("\n"),
+    );
+  });
+});

package/src/domains/llm/operations/collectContext.ts

@@ -1,18 +1,16 @@
 import type { Store } from "@canonical/ke";
-import { listBlocks } from "../../block/operations/index.js";
-import { listModifiers } from "../../modifier/operations/index.js";
+import { collectEntityCounts } from "../../info/operations/index.js";
 import { listOntologies } from "../../ontology/operations/index.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
 import type { FilterConfig } from "../../shared/types/index.js";
-import { listStandards } from "../../standard/operations/index.js";
-import { listTokens } from "../../token/operations/index.js";
 import type { LlmContext } from "../types.js";
 
 /**
  * Collects dynamic context for the `pragma llm` orientation output.
  *
- * Queries the store in parallel for block, standard, modifier, token, and
- * ontology counts, and combines them with tier/channel config state.
+ * Queries the store in parallel for entity counts (via
+ * {@link collectEntityCounts}) and ontology namespaces, and combines them
+ * with tier/channel config state.
  *
  * @note Queries ke store
  *
@@ -24,11 +22,8 @@ export default async function collectContext(
   store: Store,
   config: FilterConfig,
 ): Promise<LlmContext> {
-  const [blocks, standards, modifiers, tokens, ontologies] = await Promise.all([
-    listBlocks(store, config),
-    listStandards(store),
-    listModifiers(store),
-    listTokens(store),
+  const [counts, ontologies] = await Promise.all([
+    collectEntityCounts(store, config),
     listOntologies(store),
   ]);
 
@@ -36,12 +31,7 @@ export default async function collectContext(
     tier: config.tier,
     tierChain: resolveTierChain(config.tier),
     channel: config.channel,
-    counts: {
-      blocks: blocks.length,
-      standards: standards.length,
-      modifierFamilies: modifiers.length,
-      tokens: tokens.length,
-    },
+    counts,
     namespaces: ontologies.map((o) => o.prefix),
   };
 }

package/src/domains/modifier/commands/list.ts

@@ -1,42 +1,9 @@
-/**
- * Wires the `pragma modifier list` CLI command.
- *
- * Lists all modifier families with their allowed values. Throws a
- * structured recovery error when no families are found.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { listFormatters } from "../formatters/index.js";
-import { modifierConfig } from "../modifierConfig.js";
-import { resolveModifierList } from "../orchestration/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { modifierListStory } from "../stories.js";
 
+/** Wire the `pragma modifier list` CLI command from the modifier list story. */
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["modifier", "list"],
-    description: "List all modifier families",
-    parameters: [],
-    meta: {
-      examples: ["pragma modifier list", "pragma modifier list --llm"],
-    },
-    async execute() {
-      const resolution = await resolveModifierList(ctx);
-
-      return createOutputResult([...resolution.items], {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Modifiers",
-            domain: "modifier",
-            items: data,
-            columns: modifierConfig.listColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, modifierListStory);
 }

package/src/domains/modifier/commands/lookup.ts

@@ -1,85 +1,14 @@
-/**
- * Wires the `pragma modifier lookup <name...>` CLI command.
- *
- * Retrieves a single modifier family by name and renders its values.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import {
-  createInkLookupOptions,
-  lookupFormatters,
-} from "../formatters/index.js";
-import type { lookupModifier } from "../operations/index.js";
-import { resolveModifierLookup } from "../orchestration/index.js";
-
-interface ModifierLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupModifier>>>;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { modifierLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma modifier lookup <name...>` CLI command from the
+ * modifier lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["modifier", "lookup"],
-    description: "Look up a modifier family and its values",
-    parameters: [
-      {
-        name: "names",
-        description: "Modifier family names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma modifier lookup importance",
-        "pragma modifier lookup importance density",
-        "pragma modifier lookup importance --llm",
-      ],
-    },
-    async execute(params: Record<string, unknown>) {
-      const names = normalizeNames(params.names, params.name);
-      const contract = await resolveModifierLookup(ctx.store, names);
-
-      return createOutputResult<ModifierLookupOutput>(
-        { result: contract.result },
-        {
-          plain: ({ result }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (family) => family,
-            }),
-          ink: ({ result }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "modifier",
-              options: createInkLookupOptions(),
-            }),
-        },
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
+  return compileLookupCommand(ctx, modifierLookupStory);
 }

package/src/domains/modifier/commands/sample.ts

@@ -11,6 +11,7 @@ import {
 } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import parseSampleCount from "../../shared/parseSampleCount.js";
 import type { ModifierFamily, SampleOutput } from "../../shared/types/index.js";
 import { sampleFormatters } from "../formatters/index.js";
 import { sampleModifiers } from "../operations/index.js";
@@ -37,7 +38,7 @@ export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
       examples: ["pragma modifier sample", "pragma modifier sample --count 3"],
     },
     async execute(params) {
-      const count = Number(params.count ?? 2);
+      const count = parseSampleCount(params.count);
       const result = await sampleModifiers(ctx.store, count);
 
       const output: SampleOutput<ModifierFamily> = {

package/src/domains/modifier/mcp/specs.ts

@@ -1,99 +1,25 @@
 /**
- * MCP tool specs for the modifier domain.
+ * MCP tool specs for the modifier domain — modifier_list, modifier_lookup,
+ * modifier_sample.
  *
- * Declarative definitions — no MCP imports. The adapter layer
- * converts these into registered MCP tools via `registerFromSpec()`.
+ * The list and lookup tools are compiled from the modifier read stories in
+ * `../stories.ts`; only the sample tool is spec'd by hand. The adapter
+ * layer converts these into registered MCP tools via `registerFromSpec()`.
  */
 
-import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
-  listFormatters as modifierListFmt,
-  lookupFormatters as modifierLookupFmt,
-  sampleFormatters as modifierSampleFmt,
-} from "../formatters/index.js";
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { sampleFormatters as modifierSampleFmt } from "../formatters/index.js";
 import { sampleModifiers } from "../operations/index.js";
-import {
-  resolveModifierList,
-  resolveModifierLookup,
-} from "../orchestration/index.js";
+import { modifierListStory, modifierLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "modifier_list",
-    description: "List all modifier families with their values.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const resolution = await resolveModifierList(rt);
-
-      if (condensed) {
-        const text = modifierListFmt.llm([...resolution.items]);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return {
-        data: resolution.items,
-        meta: { count: resolution.items.length },
-      };
-    },
-  },
-
-  {
-    name: "modifier_lookup",
-    description: "Get one or more modifier families and their values.",
-    params: {
-      names: {
-        type: "string[]",
-        description: "Modifier family names or IRIs to look up",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { names, condensed }) {
-      const contract = await resolveModifierLookup(rt.store, names as string[]);
-      const result = contract.result;
-
-      if (condensed) {
-        const textParts = result.results.map((family) =>
-          modifierLookupFmt.llm(family),
-        );
-
-        if (result.errors.length > 0) {
-          textParts.push(
-            [
-              "### Errors",
-              ...result.errors.map(
-                (error) => `- ${error.query}: ${error.message}`,
-              ),
-            ].join("\n"),
-          );
-        }
-
-        return {
-          condensed: true,
-          text: textParts.join("\n\n"),
-          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.results.length } };
-    },
-  },
+  compileReadTool(modifierListStory),
+  compileLookupTool(modifierLookupStory),
   {
     name: "modifier_sample",
     description:
@@ -121,12 +47,7 @@ const specs: readonly ToolSpec[] = [
       ];
 
       if (condensed) {
-        const text = modifierSampleFmt.llm({ ...result, nextSteps });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
+        return condense(modifierSampleFmt.llm({ ...result, nextSteps }));
       }
 
       return {

package/src/domains/modifier/operations/lookup.ts

@@ -28,7 +28,7 @@ export default async function lookupModifier(
 
   const result = await store.query(
     buildQuery(`
-      SELECT ?family (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
+      SELECT ?family ?familyName (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
       WHERE {
         ?family a ${P.ds}ModifierFamily ;
                 ${P.ds}name ?familyName .
@@ -39,7 +39,7 @@ export default async function lookupModifier(
                ${P.ds}name ?valueName .
         }
       }
-      GROUP BY ?family
+      GROUP BY ?family ?familyName
     `),
   );
 
@@ -61,7 +61,9 @@ export default async function lookupModifier(
   const b = result.bindings[0] as (typeof result.bindings)[number];
   return {
     uri: (b.family ?? "") as URI,
-    name,
+    // Return the canonical stored name, not the raw user query (which may
+    // differ in casing).
+    name: b.familyName ?? name,
     values: b.values ? b.values.split("|").filter(Boolean) : [],
   };
 }

package/src/domains/modifier/orchestration/resolveModifierLookup.ts

@@ -18,11 +18,12 @@ export default async function resolveModifierLookup(
   const lookupResult: LookupResult<ModifierFamily> =
     names.length > 0
       ? await lookupMany(names, (query) => lookupModifier(store, query))
-      : { results: [], errors: [] };
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
 
   const result: LookupResult<ModifierFamily> = {
     results: lookupResult.results,
     errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
   };
 
   return {

package/src/domains/modifier/stories.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { modifierListStory, modifierLookupStory } from "./stories.js";
+
+describe("modifierListStory", () => {
+  it("renders the ink list view", () => {
+    const view = modifierListStory.renderInk?.([]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Modifiers");
+  });
+});
+
+describe("modifierLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = modifierLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+});