@canonical/pragma-cli 0.29.0 → 0.31.0

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/enrichBlocks.ts

@@ -14,12 +14,15 @@ export default async function enrichBlocks(
   filters: FilterConfig,
   disclosure: Disclosure,
 ): Promise<readonly (BlockListDigest | BlockDetailed)[]> {
+  // Look up by each summary's stable unique URI, not its display name: names
+  // recur across tiers/packages, so a by-name lookup returns every same-named
+  // block and taking the first match collapses distinct blocks onto one.
   const nested = await Promise.all(
-    summaries.map((summary) => lookupBlock(store, summary.name, filters)),
+    summaries.map((summary) => lookupBlock(store, summary.uri, filters)),
   );
-  // lookupBlock returns BlockDetailed[] — take the first match per summary
+  // lookupBlock returns BlockDetailed[] — the URI resolves to exactly one match
   const details: BlockDetailed[] = nested.flatMap((matches) =>
-    matches[0] ? [matches[0]] : [],
+    matches.at(0) ? [matches[0] as BlockDetailed] : [],
   );
 
   if (disclosure.level === "detailed") {

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,260 @@
+/**
+ * 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);
+    const lower = partial.toLowerCase();
+    // Block names recur across tiers/packages; dedupe so completion offers each
+    // name once.
+    const unique = new Set(
+      all
+        .map((block) => block.name)
+        .filter((name) => name.toLowerCase().startsWith(lower)),
+    );
+    return [...unique];
+  },
+  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] : [];
+  });
+}

package/src/domains/config/commands/channel.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Store } from "@canonical/ke";
@@ -18,13 +18,24 @@ function makeCtx(cwd: string): PragmaContext {
 
 describe("config channel command", () => {
   let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "pragma-cmd-channel-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-channel-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
   });
 
   afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
     rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
   });
 
   it("sets channel to experimental", async () => {
@@ -45,10 +56,26 @@ describe("config channel command", () => {
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
       const text = result.render.plain(result.value);
-      expect(text).toBe('Set channel to "prerelease".');
+      expect(text).toContain('Set channel to "prerelease".');
     }
   });
 
+  it("rejects a value combined with --reset", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildChannelCommand(ctx);
+    await expect(
+      cmd.execute({ value: "experimental", reset: true }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  it("rejects an explicit empty-string value", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildChannelCommand(ctx);
+    await expect(cmd.execute({ value: "" }, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+    });
+  });
+
   it("resets channel via --reset flag", async () => {
     writeFileSync(
       join(dir, "pragma.config.json"),
@@ -72,7 +99,7 @@ describe("config channel command", () => {
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
       const text = result.render.plain(result.value);
-      expect(text).toBe("Reset channel to default.");
+      expect(text).toContain("Reset channel to default.");
     }
   });
 

package/src/domains/config/commands/channel.ts

@@ -3,13 +3,15 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { readConfig } from "#config";
+import { PragmaError } from "#error";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { channelFormatters } from "../formatters/index.js";
 import { validateChannel } from "../operations/index.js";
 import { setChannelTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
 
 /**
  * Build the `pragma config channel` command definition.
@@ -40,6 +42,7 @@ export default function buildChannelCommand(
         type: "boolean",
         default: false,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: [
@@ -50,18 +53,32 @@ export default function buildChannelCommand(
     execute: async (
       params: Record<string, unknown>,
     ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
       const reset = params.reset === true;
       const value = params.value as string | undefined;
 
+      // Contradictory input: a value AND --reset. Reject rather than silently
+      // letting one win.
+      if (reset && value !== undefined) {
+        throw PragmaError.invalidInput("channel", value, {
+          recovery: {
+            message: "Pass either a channel value or --reset, not both.",
+          },
+        });
+      }
+
       if (reset) {
-        await runTask(setChannelTask(ctx.cwd, undefined));
+        const result = await runTask(setChannelTask(ctx.cwd, undefined, scope));
         const format = selectFormatter(ctx, channelFormatters.reset);
-        return createOutputResult("Reset channel to default.", {
-          plain: format,
-        });
+        return createOutputResult(
+          { field: "channel", path: result.path },
+          { plain: format },
+        );
       }
 
-      if (!value) {
+      // No value at all → query the current channel. An explicit empty string
+      // is invalid input, not a query.
+      if (value === undefined) {
         const config = readConfig(ctx.cwd);
         const format = selectFormatter(ctx, channelFormatters.query);
         return createOutputResult(config.channel, {
@@ -71,10 +88,10 @@ export default function buildChannelCommand(
 
       const channel = validateChannel(value);
 
-      await runTask(setChannelTask(ctx.cwd, channel));
+      const result = await runTask(setChannelTask(ctx.cwd, channel, scope));
       const format = selectFormatter(ctx, channelFormatters.set);
       return createOutputResult(
-        { field: "channel", value: channel },
+        { field: "channel", value: channel, path: result.path },
         { plain: format },
       );
     },