@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/standard/stories.ts

@@ -0,0 +1,151 @@
+/**
+ * Standard read stories — the single declaration of `standard list` and
+ * `standard lookup` for both surfaces.
+ *
+ * The story kernel compiles these into the CLI commands and MCP tools,
+ * so descriptions, parameters, resolution, and rendering live here once.
+ */
+
+import { createListView, createLookupView } from "#tui";
+import type { LookupStory, ReadStory } from "../shared/stories/index.js";
+import type { StandardDetailed } from "../shared/types/index.js";
+import {
+  createInkLookupOptions,
+  listFormatters,
+  lookupFormatters,
+  type StandardListOutput,
+  type StandardLookupInput,
+} from "./formatters/index.js";
+import {
+  resolveStandardList,
+  resolveStandardLookup,
+} from "./orchestration/index.js";
+import { standardConfig } from "./standardConfig.js";
+import type { StandardListResolution } from "./types.js";
+
+/** The `standard list` / `standard_list` read story. */
+export const standardListStory: ReadStory<
+  StandardListResolution,
+  StandardListOutput
+> = {
+  noun: "standard",
+  verb: "list",
+  description: "List all code standards",
+  toolDescription:
+    "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
+  params: [
+    {
+      name: "category",
+      type: "string",
+      description: "Filter by category",
+      toolDescription: "Filter by category name",
+    },
+    {
+      name: "search",
+      type: "string",
+      description: "Search in name and description",
+    },
+    {
+      name: "digest",
+      type: "boolean",
+      description: "Show description and first example for each standard",
+      default: false,
+    },
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full dos/donts for each standard",
+      default: false,
+    },
+  ],
+  examples: [
+    "pragma standard list",
+    "pragma standard list --category react",
+    'pragma standard list --search "folder"',
+    "pragma standard list --digest",
+    "pragma standard list --detailed",
+    "pragma standard list --llm",
+  ],
+  resolve: (rt, params) =>
+    resolveStandardList(rt, {
+      category: params.category as string | undefined,
+      search: params.search as string | undefined,
+      digest: params.digest === true,
+      detailed: params.detailed === true,
+    }),
+  toOutput: (resolution) => ({
+    items: resolution.items,
+    details: resolution.details,
+    disclosure: resolution.disclosure,
+  }),
+  formatters: listFormatters,
+  toEnvelope: (resolution) => {
+    if (resolution.disclosure.level === "summary") {
+      return {
+        data: resolution.items,
+        meta: { count: resolution.items.length },
+      };
+    }
+    const output: StandardListOutput = {
+      items: resolution.items,
+      details: resolution.details,
+      disclosure: resolution.disclosure,
+    };
+    return {
+      data: JSON.parse(listFormatters.json(output)),
+      meta: {
+        count: resolution.items.length,
+        disclosure: resolution.disclosure.level,
+      },
+    };
+  },
+  renderInk: (output) =>
+    createListView({
+      heading: "Standards",
+      domain: "standard",
+      items: output.items,
+      columns: standardConfig.listColumns,
+    }),
+};
+
+/** The `standard lookup` / `standard_lookup` read story. */
+export const standardLookupStory: LookupStory<
+  StandardDetailed,
+  StandardLookupInput
+> = {
+  noun: "standard",
+  description: "Look up detailed information for a standard by name or IRI",
+  toolDescription:
+    "Get detailed information about one or more code standards including dos and donts with code examples.",
+  namesDescription: "Standard names or IRIs",
+  namesToolDescription: "Standard names or IRIs to look up",
+  detailedParam: {
+    description: "Include dos and donts with code blocks",
+    toolDescription:
+      "Return full details with dos/donts (default: true for MCP)",
+  },
+  examples: [
+    "pragma standard lookup react/component/folder-structure",
+    "pragma standard lookup react/component/folder-structure react/component/props",
+    "pragma standard lookup react/component/folder-structure --detailed",
+    "pragma standard lookup react/component/folder-structure --llm",
+    "pragma standard lookup cs:react_props",
+  ],
+  resolve: async (rt, names) => {
+    const contract = await resolveStandardLookup(rt.store, names);
+    return contract.result;
+  },
+  toFmtInput: (standard, view) => ({ standard, detailed: view.detailed }),
+  formatters: lookupFormatters,
+  project: (standard) => {
+    const { uri, name, category, description } = standard;
+    return { uri, name, category, description };
+  },
+  renderInk: (result, view) =>
+    createLookupView({
+      results: result.results,
+      errors: result.errors,
+      domain: "standard",
+      options: createInkLookupOptions(view.detailed),
+    }),
+};

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

@@ -1,59 +1,9 @@
-/**
- * Wires the `pragma tier list` CLI command.
- *
- * Lists all tiers defined in the design system ontology. Throws a
- * structured recovery error when no tiers are found.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { ColumnDef } from "../../shared/contracts.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import type { TierEntry } from "../../shared/types/tier.js";
-import { listFormatters } from "../formatters/index.js";
-import { listTiers } from "../operations/index.js";
-
-const tierListColumns: readonly ColumnDef<TierEntry>[] = [
-  { key: "uri", label: "IRI" },
-  { key: "path", label: "Path" },
-  { key: "parent", label: "Parent" },
-];
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { tierListStory } from "../stories.js";
 
+/** Wire the `pragma tier list` CLI command from the tier list story. */
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["tier", "list"],
-    description: "List all tiers in the design system ontology",
-    parameters: [],
-    meta: {
-      examples: ["pragma tier list", "pragma tier list --llm"],
-    },
-    async execute() {
-      const tiers = await listTiers(ctx.store);
-
-      if (tiers.length === 0) {
-        throw PragmaError.emptyResults("tier", {
-          recovery: {
-            message:
-              "Ensure design system packages are installed: bun add -D @canonical/ds-global",
-          },
-        });
-      }
-
-      return createOutputResult(tiers, {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Tiers",
-            domain: "tier",
-            items: data,
-            columns: tierListColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, tierListStory);
 }

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

@@ -1,38 +1,12 @@
 /**
- * MCP tool specs for the tier domain.
+ * MCP tool specs for the tier domain — tier_list, compiled from the tier
+ * read story in `../stories.ts`.
  */
 
+import { compileReadTool } from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listFormatters as tierListFmt } from "../formatters/index.js";
-import { listTiers } from "../operations/index.js";
+import { tierListStory } from "../stories.js";
 
-const specs: readonly ToolSpec[] = [
-  {
-    name: "tier_list",
-    description: "List all tiers in the design system ontology with hierarchy.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listTiers(rt.store);
-
-      if (condensed) {
-        const text = tierListFmt.llm(result);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.length } };
-    },
-  },
-];
+const specs: readonly ToolSpec[] = [compileReadTool(tierListStory)];
 
 export default specs;

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

@@ -0,0 +1,22 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { tierListStory } from "./stories.js";
+
+const tier = {
+  uri: "https://ds.example/global" as URI,
+  path: "global",
+  depth: 0,
+};
+
+describe("tierListStory", () => {
+  it("renders the ink list view", () => {
+    const view = tierListStory.renderInk?.([tier]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Tiers");
+  });
+
+  it("rejects only empty results", () => {
+    expect(tierListStory.emptyError?.([], {})).toBeDefined();
+    expect(tierListStory.emptyError?.([tier], {})).toBeUndefined();
+  });
+});

package/src/domains/tier/stories.ts

@@ -0,0 +1,52 @@
+/**
+ * Tier read story — the single declaration of `tier list` for both
+ * surfaces.
+ *
+ * The story kernel compiles this into the CLI command and MCP tool,
+ * so description, resolution, and rendering live here once.
+ */
+
+import { PragmaError } from "#error";
+import { createListView } from "#tui";
+import type { ColumnDef } from "../shared/contracts.js";
+import type { ReadStory } from "../shared/stories/index.js";
+import type { TierEntry } from "../shared/types/index.js";
+import { listFormatters } from "./formatters/index.js";
+import { listTiers } from "./operations/index.js";
+
+const tierListColumns: readonly ColumnDef<TierEntry>[] = [
+  { key: "uri", label: "IRI" },
+  { key: "path", label: "Path" },
+  { key: "parent", label: "Parent" },
+];
+
+/** The `tier list` / `tier_list` read story. */
+export const tierListStory: ReadStory<TierEntry[], TierEntry[]> = {
+  noun: "tier",
+  verb: "list",
+  description: "List all tiers in the design system ontology",
+  toolDescription:
+    "List all tiers in the design system ontology with hierarchy.",
+  params: [],
+  examples: ["pragma tier list", "pragma tier list --llm"],
+  resolve: (rt) => listTiers(rt.store),
+  toOutput: (tiers) => tiers,
+  formatters: listFormatters,
+  toEnvelope: (tiers) => ({ data: tiers, meta: { count: tiers.length } }),
+  emptyError: (tiers) =>
+    tiers.length === 0
+      ? PragmaError.emptyResults("tier", {
+          recovery: {
+            message:
+              "Ensure semantic packages are resolvable — run `pragma doctor` to inspect package refs.",
+          },
+        })
+      : undefined,
+  renderInk: (tiers) =>
+    createListView({
+      heading: "Tiers",
+      domain: "tier",
+      items: tiers,
+      columns: tierListColumns,
+    }),
+};

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

@@ -7,6 +7,7 @@
 
 import { writeFileSync } from "node:fs";
 import { PragmaError } from "#error";
+import { lookupToolMeta } from "../../shared/lookupMany.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
   createLookupFormatters as createTokenLookupFmt,
@@ -101,7 +102,10 @@ const specs: readonly ToolSpec[] = [
         };
       }
 
-      return { data: result, meta: { count: result.results.length } };
+      return {
+        data: { results: result.results, errors: result.errors },
+        meta: lookupToolMeta(result),
+      };
     },
   },
 

package/src/domains/token/orchestration/resolveTokenLookup.ts

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

package/src/domains/trace/tracePlugin.test.ts

@@ -152,7 +152,7 @@ describe("createTracePlugin", () => {
 
     // bindings should be at most 2 (may be 0 with empty store)
     expect(record.bindings).toBeDefined();
-    expect(record.bindings!.length).toBeLessThanOrEqual(2);
+    expect(record.bindings?.length).toBeLessThanOrEqual(2);
   });
 
   it("generates a session ID when not provided", async () => {