@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -1,173 +1,14 @@
-/**
- * Wires the `pragma block lookup <name-or-uri...>` CLI command.
- *
- * Accepts a positional block name or IRI and optional aspect flags (anatomy,
- * modifiers, tokens, implementations). Delegates to {@link lookupBlock} for
- * data retrieval and {@link lookupFormatters} for output rendering.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-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 type { BlockDetailed } from "../../shared/types/index.js";
-import { createLookupOptions, lookupFormatters } from "../formatters/index.js";
-import { resolveAspects } from "../helpers/index.js";
-import { listBlocks } from "../operations/index.js";
-import {
-  buildBlockFilters,
-  resolveBlockLookup,
-} from "../orchestration/index.js";
-import type { AspectFlags } from "../types.js";
-
-interface BlockLookupOutput {
-  readonly result: LookupResult<BlockDetailed>;
-  readonly detailed: boolean;
-  readonly aspects: AspectFlags;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { blockLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma block lookup <name-or-uri...>` CLI command from the
+ * block lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["block", "lookup"],
-    description: "Look up block details",
-    parameters: [
-      {
-        name: "names",
-        description: "Block names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-        complete: async (partial: string) => {
-          const all = await listBlocks(ctx.store, ctx.config);
-          return all
-            .map((c) => c.name)
-            .filter((n) => n.toLowerCase().startsWith(partial.toLowerCase()));
-        },
-      },
-      {
-        name: "detailed",
-        description:
-          "Show full details including anatomy, modifiers, tokens, and implementations",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "anatomy",
-        description: "Show anatomy tree",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "modifiers",
-        description: "Show modifier values",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "tokens",
-        description: "Show token references",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "implementations",
-        description: "Show implementation paths",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    parameterGroups: {
-      "Aspect filters": ["anatomy", "modifiers", "tokens", "implementations"],
-    },
-    meta: {
-      examples: [
-        "pragma block lookup Button",
-        "pragma block lookup Button Card",
-        "pragma block lookup Button --detailed",
-        "pragma block lookup Button --anatomy --modifiers",
-        "pragma block lookup Button --detailed --llm",
-        "pragma block lookup ds:global.component.button",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const names = normalizeNames(params.names, params.name);
-      if (names.length === 0) {
-        throw PragmaError.invalidInput("names", "(empty)", {
-          recovery: {
-            message: "List available blocks.",
-            cli: "pragma block list",
-            mcp: { tool: "block_list" },
-          },
-        });
-      }
-
-      const detailed = params.detailed === true;
-      const aspectInput: Partial<AspectFlags> = {
-        anatomy: params.anatomy === true,
-        modifiers: params.modifiers === true,
-        tokens: params.tokens === true,
-        implementations: params.implementations === true,
-      };
-
-      const isAspectSelected =
-        aspectInput.anatomy ||
-        aspectInput.modifiers ||
-        aspectInput.tokens ||
-        aspectInput.implementations;
-      const showDetailed = detailed || (isAspectSelected ?? false);
-      const aspects = resolveAspects(aspectInput);
-
-      const contract = await resolveBlockLookup(
-        ctx.store,
-        names,
-        buildBlockFilters(ctx),
-      );
-
-      return createOutputResult<BlockLookupOutput>(
-        { result: contract.result, detailed: showDetailed, aspects },
-        {
-          plain: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (block) => ({
-                block,
-                detailed: isDetailed,
-                aspects: selectedAspects,
-              }),
-            }),
-          ink: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "block",
-              options: createLookupOptions(isDetailed, selectedAspects),
-            }),
-        },
-      );
-    },
-  };
-}
-
-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, blockLookupStory);
 }

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

@@ -1,201 +1,26 @@
 /**
- * MCP tool specs for the block domain — block_list, block_lookup.
+ * MCP tool specs for the block domain — block_list, block_lookup,
+ * block_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 block 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 blockListFmt,
-  lookupFormatters as blockLookupFmt,
-  sampleFormatters as blockSampleFmt,
-} from "../formatters/index.js";
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { sampleFormatters as blockSampleFmt } from "../formatters/index.js";
 import { sampleBlocks } from "../operations/index.js";
-import {
-  buildBlockFilters,
-  resolveBlockList,
-  resolveBlockLookup,
-} from "../orchestration/index.js";
+import { buildBlockFilters } from "../orchestration/index.js";
+import { blockListStory, blockLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "block_list",
-    description:
-      "List design system blocks visible under current tier and channel configuration.",
-    params: {
-      allTiers: {
-        type: "boolean",
-        description: "Show blocks from all tiers, ignoring tier filter",
-        optional: true,
-      },
-      digest: {
-        type: "boolean",
-        description: "Include implementations per block",
-        optional: true,
-      },
-      detailed: {
-        type: "boolean",
-        description: "Include full details per block",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { allTiers, digest, detailed, condensed }) {
-      const contract = await resolveBlockList(rt, {
-        allTiers: allTiers === true,
-        digest: digest === true,
-        detailed: detailed === true,
-      });
-
-      if (condensed) {
-        const text = blockListFmt.llm(contract.result.items);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      if (contract.result.disclosure.level === "detailed") {
-        return {
-          data: contract.result.items,
-          meta: {
-            count: contract.result.items.length,
-            disclosure: "detailed",
-            filters: contract.result.filters,
-          },
-        };
-      }
-
-      if (contract.result.disclosure.level === "digest") {
-        return {
-          data: contract.result.items,
-          meta: {
-            count: contract.result.items.length,
-            disclosure: "digest",
-            filters: contract.result.filters,
-          },
-        };
-      }
-
-      return {
-        data: contract.result.items,
-        meta: {
-          count: contract.result.items.length,
-          filters: contract.result.filters,
-        },
-      };
-    },
-  },
-
-  {
-    name: "block_lookup",
-    description:
-      "Get detailed information about one or more design system blocks including anatomy, modifiers, tokens, and applicable standards.",
-    params: {
-      names: {
-        type: "string[]",
-        description:
-          "Block names or IRIs to look up (e.g. ['Button', 'ds:global.component.card'])",
-        optional: false,
-      },
-      detailed: {
-        type: "boolean",
-        description: "Return full details (default: true for MCP)",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { names, detailed, condensed }) {
-      const queries = names as string[];
-      const showDetailed = (detailed as boolean | undefined) ?? true;
-      const contract = await resolveBlockLookup(
-        rt.store,
-        queries,
-        buildBlockFilters(rt),
-      );
-      const result = contract.result;
-
-      if (condensed) {
-        const textParts = result.results.map((block) =>
-          blockLookupFmt.llm({
-            block,
-            detailed: showDetailed,
-            aspects: {
-              anatomy: true,
-              modifiers: true,
-              tokens: true,
-              implementations: true,
-            },
-          }),
-        );
-
-        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)}`,
-        };
-      }
-
-      if (!showDetailed) {
-        const summaries = result.results.map(
-          ({
-            uri,
-            name,
-            type,
-            tier,
-            modifiers,
-            implementations,
-            nodeCount,
-            tokenCount,
-            summary,
-          }) => ({
-            uri,
-            name,
-            type,
-            tier,
-            modifiers,
-            implementations,
-            nodeCount,
-            tokenCount,
-            summary,
-          }),
-        );
-
-        return {
-          data: {
-            results: summaries,
-            errors: result.errors,
-          },
-          meta: { count: summaries.length },
-        };
-      }
-
-      return { data: result, meta: { count: result.results.length } };
-    },
-  },
+  compileReadTool(blockListStory),
+  compileLookupTool(blockLookupStory),
   {
     name: "block_sample",
     description:
@@ -224,12 +49,7 @@ const specs: readonly ToolSpec[] = [
       ];
 
       if (condensed) {
-        const text = blockSampleFmt.llm({ ...result, nextSteps });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
+        return condense(blockSampleFmt.llm({ ...result, nextSteps }));
       }
 
       return {

package/src/domains/block/orchestration/resolveBlockLookup.ts

@@ -19,12 +19,13 @@ export default async function resolveBlockLookup(
   const nested: LookupResult<BlockDetailed[]> =
     names.length > 0
       ? await lookupMany(names, (query) => lookupBlock(store, query, filters))
-      : { results: [], errors: [] };
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
 
   // lookupBlock returns BlockDetailed[] (multiple matches per name) — flatten
   const result: LookupResult<BlockDetailed> = {
     results: nested.results.flat(),
     errors: [...nested.errors, ...globErrors],
+    meta: nested.meta ?? { internalErrorCount: 0 },
   };
 
   return {

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { blockListStory, blockLookupStory } from "./stories.js";
+
+describe("blockListStory", () => {
+  it("renders the ink list view", () => {
+    const view = blockListStory.renderInk?.([]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Blocks");
+  });
+});
+
+describe("blockLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = blockLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+
+  it("implies detail from aspect flags on the CLI only", () => {
+    const resolveDetailed = blockLookupStory.resolveDetailed;
+    expect(resolveDetailed?.("cli", { anatomy: true })).toBe(true);
+    expect(resolveDetailed?.("cli", {})).toBe(false);
+    expect(resolveDetailed?.("mcp", {})).toBe(true);
+    expect(resolveDetailed?.("mcp", { detailed: false })).toBe(false);
+  });
+});

package/src/domains/block/stories.ts

@@ -0,0 +1,254 @@
+/**
+ * Block read stories — the single declaration of `block list` and
+ * `block 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 { PragmaError } from "#error";
+import { createListView, createLookupView } from "#tui";
+import type { ColumnDef } from "../shared/contracts.js";
+import {
+  type LookupStory,
+  type LookupStoryView,
+  type ReadStory,
+  requirePragmaContext,
+} from "../shared/stories/index.js";
+import type { BlockDetailed } from "../shared/types/index.js";
+import { blockConfig } from "./blockConfig.js";
+import {
+  createLookupOptions,
+  listFormatters,
+  lookupFormatters,
+} from "./formatters/index.js";
+import type { BlockLookupInput } from "./formatters/types.js";
+import { resolveAspects } from "./helpers/index.js";
+import { listBlocks } from "./operations/index.js";
+import {
+  buildBlockFilters,
+  resolveBlockList,
+  resolveBlockLookup,
+} from "./orchestration/index.js";
+import type { AspectFlags, BlockListContract } from "./types.js";
+
+type BlockListItems = BlockListContract["result"]["items"];
+
+const LIST_COLUMN_ORDER = ["name", "type", "tier", "modifiers", "uri"] as const;
+
+/** The `block list` / `block_list` read story. */
+export const blockListStory: ReadStory<BlockListContract, BlockListItems> = {
+  noun: "block",
+  verb: "list",
+  description: "List blocks in the design system",
+  toolDescription:
+    "List design system blocks visible under current tier and channel configuration.",
+  params: [
+    {
+      name: "allTiers",
+      type: "boolean",
+      description: "Show blocks from all tiers",
+      toolDescription: "Show blocks from all tiers, ignoring tier filter",
+      default: false,
+    },
+    {
+      name: "digest",
+      type: "boolean",
+      description: "Show enriched summary with implementations",
+      toolDescription: "Include implementations per block",
+      default: false,
+    },
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full details for each block",
+      toolDescription: "Include full details per block",
+      default: false,
+    },
+  ],
+  examples: [
+    "pragma block list",
+    "pragma block list --all-tiers",
+    "pragma block list --digest",
+    "pragma block list --detailed",
+    "pragma block list --llm",
+    "pragma block list --format json",
+  ],
+  resolve: (rt, params) =>
+    resolveBlockList(rt, {
+      allTiers: params.allTiers === true,
+      digest: params.digest === true,
+      detailed: params.detailed === true,
+    }),
+  toOutput: (contract) => contract.result.items,
+  formatters: listFormatters,
+  toEnvelope: (contract) => {
+    const { items, disclosure, filters } = contract.result;
+    if (disclosure.level === "summary") {
+      return { data: items, meta: { count: items.length, filters } };
+    }
+    return {
+      data: items,
+      meta: { count: items.length, disclosure: disclosure.level, filters },
+    };
+  },
+  renderInk: (items) =>
+    createListView({
+      heading: "Blocks",
+      domain: "block",
+      items,
+      columns: reorderColumns(blockConfig.listColumns, LIST_COLUMN_ORDER),
+    }),
+};
+
+/** The `block lookup` / `block_lookup` read story. */
+export const blockLookupStory: LookupStory<BlockDetailed, BlockLookupInput> = {
+  noun: "block",
+  description: "Look up block details",
+  toolDescription:
+    "Get detailed information about one or more design system blocks including anatomy, modifiers, tokens, and applicable standards.",
+  namesDescription: "Block names or IRIs",
+  namesToolDescription:
+    "Block names or IRIs to look up (e.g. ['Button', 'ds:global.component.card'])",
+  complete: async (partial, cmdCtx) => {
+    const ctx = requirePragmaContext(cmdCtx);
+    const all = await listBlocks(ctx.store, ctx.config);
+    return all
+      .map((block) => block.name)
+      .filter((name) => name.toLowerCase().startsWith(partial.toLowerCase()));
+  },
+  detailedParam: {
+    description:
+      "Show full details including anatomy, modifiers, tokens, and implementations",
+    toolDescription: "Return full details (default: true for MCP)",
+  },
+  params: [
+    {
+      name: "anatomy",
+      type: "boolean",
+      description: "Show anatomy tree",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "modifiers",
+      type: "boolean",
+      description: "Show modifier values",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "tokens",
+      type: "boolean",
+      description: "Show token references",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "implementations",
+      type: "boolean",
+      description: "Show implementation paths",
+      default: false,
+      surfaces: "cli",
+    },
+  ],
+  parameterGroups: {
+    "Aspect filters": ["anatomy", "modifiers", "tokens", "implementations"],
+  },
+  examples: [
+    "pragma block lookup Button",
+    "pragma block lookup Button Card",
+    "pragma block lookup Button --detailed",
+    "pragma block lookup Button --anatomy --modifiers",
+    "pragma block lookup Button --detailed --llm",
+    "pragma block lookup ds:global.component.button",
+  ],
+  resolve: async (rt, names) => {
+    const contract = await resolveBlockLookup(
+      rt.store,
+      names,
+      buildBlockFilters(rt),
+    );
+    return contract.result;
+  },
+  resolveDetailed: (surface, params) => {
+    if (surface === "mcp") {
+      return ((params.detailed as boolean | undefined) ?? true) === true;
+    }
+    return params.detailed === true || isAspectSelected(params);
+  },
+  toFmtInput: (block, view) => ({
+    block,
+    detailed: view.detailed,
+    aspects: resolveViewAspects(view),
+  }),
+  formatters: lookupFormatters,
+  project: (block) => {
+    const {
+      uri,
+      name,
+      type,
+      tier,
+      modifiers,
+      implementations,
+      nodeCount,
+      tokenCount,
+      summary,
+    } = block;
+    return {
+      uri,
+      name,
+      type,
+      tier,
+      modifiers,
+      implementations,
+      nodeCount,
+      tokenCount,
+      summary,
+    };
+  },
+  emptyNamesError: () =>
+    PragmaError.invalidInput("names", "(empty)", {
+      recovery: {
+        message: "List available blocks.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    }),
+  renderInk: (result, view) =>
+    createLookupView({
+      results: result.results,
+      errors: result.errors,
+      domain: "block",
+      options: createLookupOptions(view.detailed, resolveViewAspects(view)),
+    }),
+};
+
+function isAspectSelected(params: Record<string, unknown>): boolean {
+  return (
+    params.anatomy === true ||
+    params.modifiers === true ||
+    params.tokens === true ||
+    params.implementations === true
+  );
+}
+
+function resolveViewAspects(view: LookupStoryView): AspectFlags {
+  return resolveAspects({
+    anatomy: view.params.anatomy === true,
+    modifiers: view.params.modifiers === true,
+    tokens: view.params.tokens === true,
+    implementations: view.params.implementations === true,
+  });
+}
+
+function reorderColumns<T>(
+  columns: readonly ColumnDef<T>[],
+  order: readonly string[],
+): readonly ColumnDef<T>[] {
+  const byKey = new Map(columns.map((col) => [col.key, col]));
+  return order.flatMap((key) => {
+    const col = byKey.get(key as keyof T & string);
+    return col ? [col] : [];
+  });
+}