@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/shared/stories/resolveLookupDetailed.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory } from "./types.js";
+
+type AnyLookupStory = LookupStory<unknown, unknown>;
+
+const baseStory: Pick<
+  AnyLookupStory,
+  "noun" | "description" | "toolDescription" | "namesDescription"
+> = {
+  noun: "thing",
+  description: "d",
+  toolDescription: "td",
+  namesDescription: "names",
+};
+
+function makeStory(overrides: Partial<AnyLookupStory>): AnyLookupStory {
+  return {
+    ...baseStory,
+    examples: [],
+    resolve: async () => ({ results: [], errors: [] }),
+    toFmtInput: (entity) => entity,
+    formatters: {
+      plain: () => "",
+      llm: () => "",
+      json: () => "",
+    },
+    ...overrides,
+  };
+}
+
+describe("resolveLookupDetailed", () => {
+  it("is never detailed when the story has no detailed param", () => {
+    const story = makeStory({});
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(false);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+
+  it("defaults detailed to true on MCP and false on CLI", () => {
+    const story = makeStory({ detailedParam: { description: "d" } });
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", { detailed: false })).toBe(
+      false,
+    );
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(false);
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(true);
+  });
+
+  it("lets a story override the surface defaults", () => {
+    const story = makeStory({
+      detailedParam: { description: "d" },
+      resolveDetailed: (surface) => surface === "cli",
+    });
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+});

package/src/domains/shared/stories/resolveLookupDetailed.ts

@@ -0,0 +1,27 @@
+import type { LookupStory } from "./types.js";
+
+/**
+ * Resolve the effective `detailed` flag for a lookup story on a surface.
+ *
+ * Defaults follow the ratified surface contract: the CLI opts in
+ * (`detailed` is false unless set) while MCP opts out (`detailed` is true
+ * unless set, since agents want full data by default). Stories without a
+ * `detailed` parameter are never detailed. A story's `resolveDetailed`
+ * override wins — block uses it to let aspect flags imply detail.
+ */
+export default function resolveLookupDetailed<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+  surface: "cli" | "mcp",
+  params: Record<string, unknown>,
+): boolean {
+  if (story.resolveDetailed) {
+    return story.resolveDetailed(surface, params);
+  }
+  if (!story.detailedParam) {
+    return false;
+  }
+  if (surface === "mcp") {
+    return ((params.detailed as boolean | undefined) ?? true) === true;
+  }
+  return params.detailed === true;
+}

package/src/domains/shared/stories/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Read-story spec types — one declaration per read story, many projections.
+ *
+ * A read story (list, show, or lookup) is declared once per domain and
+ * compiled into both surfaces: a cli-core `CommandDefinition` and a
+ * declarative MCP `ToolSpec`. The compilers in this folder own the shared
+ * execute skeletons — parameter projection, condensed rendering with token
+ * estimates, empty-result guards, and summary projection — so a domain
+ * supplies only its facts: descriptions, parameters, resolve function,
+ * formatters, and envelope mapping. This kills the per-domain duplication
+ * between `commands/*.ts` and `mcp/specs.ts` for read verbs and makes
+ * CLI/MCP parity structural instead of conventional.
+ */
+
+import type { CommandContext } from "@canonical/cli-core";
+import type { PragmaError } from "#error";
+import type { LookupResult } from "../contracts.js";
+import type { Formatters } from "../formatters.js";
+import type { PragmaRuntime } from "../types/index.js";
+
+/** Surfaces a story parameter is projected to (default: "both"). */
+export type StorySurface = "both" | "cli" | "mcp";
+
+/**
+ * Neutral parameter definition projected to a CLI flag and an MCP tool
+ * parameter. `string[]` becomes a CLI multiselect and an MCP string array.
+ */
+export interface StoryParam {
+  readonly name: string;
+  readonly type: "string" | "boolean" | "string[]";
+  /** CLI help text; also the MCP description unless `toolDescription` is set. */
+  readonly description: string;
+  /** MCP-specific description override. */
+  readonly toolDescription?: string;
+  readonly required?: boolean;
+  /** CLI default value — MCP parameters carry no defaults. */
+  readonly default?: unknown;
+  /** Allowed values; projects to CLI select choices and an MCP enum. */
+  readonly enum?: readonly string[];
+  /** If true, the CLI accepts this parameter as a positional argument. */
+  readonly positional?: boolean;
+  /** Surfaces this parameter appears on (default: "both"). */
+  readonly surfaces?: StorySurface;
+  /** CLI tab-completion for this parameter's argument. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+}
+
+/** MCP envelope fragment produced by a story's `toEnvelope`. */
+export interface StoryEnvelope {
+  readonly data: unknown;
+  readonly meta?: Record<string, unknown>;
+}
+
+/**
+ * A collection-or-singleton read story (`<noun> list`, `<noun> show`).
+ *
+ * `TData` is the domain's resolved payload; `TOutput` is the formatter and
+ * renderer input derived from it via `toOutput`.
+ */
+export interface ReadStory<TData, TOutput> {
+  readonly noun: string;
+  /** Read verb this story projects to (e.g. "list", "show"). */
+  readonly verb: string;
+  /** CLI one-line help description. */
+  readonly description: string;
+  /** MCP tool description. */
+  readonly toolDescription: string;
+  readonly params: readonly StoryParam[];
+  /** Usage examples shown in CLI help. */
+  readonly examples: readonly string[];
+  /** Fetch the story's data. Shared verbatim by both surfaces. */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    params: Record<string, unknown>,
+  ) => Promise<TData>;
+  /** Map resolved data to the formatter/renderer input. */
+  readonly toOutput: (data: TData, params: Record<string, unknown>) => TOutput;
+  readonly formatters: Formatters<TOutput>;
+  /** Map resolved data to the MCP `{ data, meta }` envelope. */
+  readonly toEnvelope: (data: TData) => StoryEnvelope;
+  /**
+   * CLI-only pre-resolve guard: return an error to reject invalid
+   * parameters (e.g. an empty required positional).
+   */
+  readonly guardParams?: (
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /**
+   * CLI-only post-resolve guard: return an error to reject an empty
+   * result set with a recovery hint.
+   */
+  readonly emptyError?: (
+    data: TData,
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (output: TOutput) => unknown;
+}
+
+/** Per-invocation view state passed to lookup story hooks. */
+export interface LookupStoryView {
+  readonly surface: "cli" | "mcp";
+  /** Effective detail level after surface defaults and flag implications. */
+  readonly detailed: boolean;
+  readonly params: Record<string, unknown>;
+}
+
+/**
+ * A batch retrieval story (`<noun> lookup <names...>`).
+ *
+ * `TDetailed` is the looked-up entity; `TFmtInput` is the per-entity
+ * formatter input derived via `toFmtInput` (some domains pair the entity
+ * with view flags such as `detailed` or aspect selections).
+ */
+export interface LookupStory<TDetailed, TFmtInput> {
+  readonly noun: string;
+  readonly description: string;
+  readonly toolDescription: string;
+  /** CLI description of the `names` positional parameter. */
+  readonly namesDescription: string;
+  /** MCP-specific `names` description override. */
+  readonly namesToolDescription?: string;
+  /** CLI tab-completion for names. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+  /**
+   * The `detailed` toggle, when the story supports one. MCP defaults
+   * `detailed` to true; the CLI defaults it to false.
+   */
+  readonly detailedParam?: {
+    readonly description: string;
+    readonly toolDescription?: string;
+  };
+  /** Additional story parameters beyond `names` and `detailed`. */
+  readonly params?: readonly StoryParam[];
+  /** Named groups for organizing CLI parameters in help output. */
+  readonly parameterGroups?: Readonly<Record<string, readonly string[]>>;
+  readonly examples: readonly string[];
+  /** Resolve all queries, collecting per-query failures. */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    names: readonly string[],
+    params: Record<string, unknown>,
+  ) => Promise<LookupResult<TDetailed>>;
+  /**
+   * Effective `detailed` for a surface. Defaults to the plain flag value
+   * (CLI: false unless set; MCP: true unless set). Domains override this
+   * when other flags imply detail (e.g. block aspect filters).
+   */
+  readonly resolveDetailed?: (
+    surface: "cli" | "mcp",
+    params: Record<string, unknown>,
+  ) => boolean;
+  /** Map an entity to the per-entity formatter input. */
+  readonly toFmtInput: (entity: TDetailed, view: LookupStoryView) => TFmtInput;
+  readonly formatters: Formatters<TFmtInput>;
+  /** MCP summary projection applied when `detailed` is false. */
+  readonly project?: (entity: TDetailed) => unknown;
+  /** CLI-only error thrown when no names are supplied. */
+  readonly emptyNamesError?: () => PragmaError;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (
+    result: LookupResult<TDetailed>,
+    view: LookupStoryView,
+  ) => unknown;
+}

package/src/domains/shared/suggestions/expandGlob.ts

@@ -41,6 +41,7 @@ function globToRegex(glob: string): RegExp {
   for (const char of glob) {
     if (char === "*") {
       pattern += ".*";
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
     } else if (".+^${}()|[]\\".includes(char)) {
       pattern += `\\${char}`;
     } else {

package/src/domains/shared/suggestions/suggestNames.ts

@@ -63,35 +63,68 @@ function damerauLevenshtein(a: string, b: string): number {
   if (lenA === 0) return lenB;
   if (lenB === 0) return lenA;
 
+  // Fully allocated (lenA + 1) × (lenB + 1) grid: every row/column index in
+  // [0, lenA] × [0, lenB] below is provably in bounds, so `row.at(j)` never
+  // yields undefined for the indices we read.
   const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
     Array.from<number>({ length: lenB + 1 }).fill(0),
   );
 
   for (let i = 0; i <= lenA; i++) {
-    matrix[i]![0] = i;
+    getRow(matrix, i)[0] = i;
   }
+  const firstRow = getRow(matrix, 0);
   for (let j = 0; j <= lenB; j++) {
-    matrix[0]![j] = j;
+    firstRow[j] = j;
   }
 
   for (let i = 1; i <= lenA; i++) {
+    const prevRow = getRow(matrix, i - 1);
+    const row = getRow(matrix, i);
     for (let j = 1; j <= lenB; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
 
-      matrix[i]![j] = Math.min(
-        matrix[i - 1]![j]! + 1, // deletion
-        matrix[i]![j - 1]! + 1, // insertion
-        matrix[i - 1]![j - 1]! + cost, // substitution
+      row[j] = Math.min(
+        getCell(prevRow, j) + 1, // deletion
+        getCell(row, j - 1) + 1, // insertion
+        getCell(prevRow, j - 1) + cost, // substitution
       );
 
       if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
-        matrix[i]![j] = Math.min(
-          matrix[i]![j]!,
-          matrix[i - 2]![j - 2]! + cost, // transposition
+        const prevPrevRow = getRow(matrix, i - 2);
+        row[j] = Math.min(
+          getCell(row, j),
+          getCell(prevPrevRow, j - 2) + cost, // transposition
         );
       }
     }
   }
 
-  return matrix[lenA]![lenB]!;
+  return getCell(getRow(matrix, lenA), lenB);
+}
+
+/**
+ * Read a matrix row that is structurally guaranteed to exist.
+ *
+ * @throws if the row is missing, signalling a broken allocation invariant.
+ */
+function getRow(matrix: number[][], index: number): number[] {
+  const row = matrix.at(index);
+  if (row === undefined) {
+    throw new Error(`matrix row ${index} is out of bounds`);
+  }
+  return row;
+}
+
+/**
+ * Read a matrix cell that is structurally guaranteed to exist.
+ *
+ * @throws if the cell is missing, signalling a broken allocation invariant.
+ */
+function getCell(row: number[], index: number): number {
+  const cell = row.at(index);
+  if (cell === undefined) {
+    throw new Error(`matrix cell ${index} is out of bounds`);
+  }
+  return cell;
 }

package/src/domains/skill/commands/index.ts

@@ -1,2 +1,4 @@
-/** @module Skill command definitions for `pragma skill`. */
+/** @module Re-exports skill command builders (`list`, `lookup`). */
+
 export { default as listCommand } from "./list.js";
+export { default as lookupCommand } from "./lookup.js";

package/src/domains/skill/commands/list.test.ts

@@ -9,9 +9,13 @@ import buildListCommand from "./list.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-skill-cmd-${Date.now()}`);
 
+/** One source per skill directory, matching the loader granularity. */
 const TEST_SOURCES = [
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-audit",
+    ),
     packageName: "@canonical/design-system",
   },
 ];
@@ -23,7 +27,7 @@ vi.mock("../helpers/resolveSkillSources.js", () => ({
 beforeAll(() => {
   mkdirSync(TMP_ROOT, { recursive: true });
 
-  const dir = join(TEST_SOURCES[0].dir, "design-audit");
+  const dir = TEST_SOURCES.at(0)?.dir ?? "";
   mkdirSync(dir, { recursive: true });
   writeFileSync(
     join(dir, "SKILL.md"),

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

@@ -1,69 +1,11 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
+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 type { SkillListInput } from "../formatters/types.js";
-import { listSkills } from "../operations/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { skillListStory } from "../stories.js";
 
-/**
- * Build the `pragma skill list` command definition.
- *
- * Discovers skills from installed packages and formats the result.
- * Throws when no skills are found, with a recovery hint.
- *
- * @param ctx - Pragma context providing cwd and formatter selection.
- * @returns The command definition for `pragma skill list`.
- * @note Impure
- */
+/** Wire the `pragma skill list` CLI command from the skill list story. */
 export default function buildListCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["skill", "list"],
-    description: "List available agent skills from design system packages",
-    parameters: [
-      {
-        name: "detailed",
-        description: "Show full metadata for each skill",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma skill list",
-        "pragma skill list --detailed",
-        "pragma skill list --llm",
-        "pragma skill list --format json",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const detailed = params.detailed === true;
-      const { skills, sources } = await listSkills(ctx.cwd);
-
-      if (skills.length === 0) {
-        const allUnavailable = sources.every((s) => !s.available);
-        throw PragmaError.emptyResults("skill", {
-          recovery: {
-            message: allUnavailable
-              ? "Install @canonical packages first"
-              : "No SKILL.md files found in source packages",
-          },
-        });
-      }
-
-      const input: SkillListInput = { skills, sources, detailed };
-
-      return createOutputResult(input, {
-        plain: selectFormatter(ctx, listFormatters),
-      });
-    },
-  };
+  return compileReadCommand(ctx, skillListStory);
 }

package/src/domains/skill/commands/lookup.test.ts

@@ -0,0 +1,118 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CommandDefinition } from "@canonical/cli-core";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../../shared/context.js";
+import buildLookupCommand from "./lookup.js";
+
+const TMP_ROOT = join(tmpdir(), `pragma-skill-lookup-cmd-${Date.now()}`);
+
+/** One source per skill directory, matching the loader granularity. */
+const TEST_SOURCES = [
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-auditor",
+    ),
+    packageName: "@canonical/design-system",
+  },
+];
+
+vi.mock("../helpers/resolveSkillSources.js", () => ({
+  default: () => TEST_SOURCES,
+}));
+
+beforeAll(() => {
+  const dir = TEST_SOURCES.at(0)?.dir ?? "";
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "SKILL.md"),
+    `---
+name: design-auditor
+description: Audit design system coverage
+---
+
+# Design Auditor
+`,
+  );
+});
+
+afterAll(() => {
+  rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: TMP_ROOT,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as PragmaContext["store"],
+    config: { tier: undefined, channel: "normal" },
+    ...overrides,
+  } as PragmaContext;
+}
+
+async function executeText(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<string> {
+  const result = await cmd.execute(params, ctx);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  return result.render.plain(result.value);
+}
+
+describe("buildLookupCommand", () => {
+  it("serves the full SKILL.md content", async () => {
+    const ctx = makeCtx();
+    const text = await executeText(
+      buildLookupCommand(ctx),
+      { names: ["design-auditor"] },
+      ctx,
+    );
+    expect(text).toContain("design-auditor");
+    expect(text).toContain("# Design Auditor");
+  });
+
+  it("renders JSON with content under --format json", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json", verbose: false },
+    });
+    const text = await executeText(
+      buildLookupCommand(ctx),
+      { names: ["design-auditor"] },
+      ctx,
+    );
+    const data = JSON.parse(text) as { name: string; content: string };
+    expect(data.name).toBe("design-auditor");
+    expect(data.content).toContain("# Design Auditor");
+  });
+
+  it("reports unknown skills in the errors section", async () => {
+    const ctx = makeCtx();
+    const text = await executeText(
+      buildLookupCommand(ctx),
+      { names: ["nope"] },
+      ctx,
+    );
+    expect(text).toContain("Errors:");
+    expect(text).toContain('skill "nope" not found.');
+  });
+
+  it("rejects an empty names list with a recovery hint", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    await expect(cmd.execute({ names: [] }, ctx)).rejects.toThrow(PragmaError);
+  });
+
+  it("completes skill names from discovery", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const names = cmd.parameters.at(0);
+    await expect(names?.complete?.("des", ctx)).resolves.toEqual([
+      "design-auditor",
+    ]);
+  });
+});

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

@@ -0,0 +1,14 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { skillLookupStory } from "../stories.js";
+
+/**
+ * Wire the `pragma skill lookup <name...>` CLI command from the skill
+ * lookup story.
+ */
+export default function buildLookupCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return compileLookupCommand(ctx, skillLookupStory);
+}

package/src/domains/skill/formatters/index.ts

@@ -1,2 +1,3 @@
 /** @module Formatter sets for skill domain output. */
 export { default as listFormatters } from "./list.js";
+export { default as lookupFormatters } from "./lookup.js";

package/src/domains/skill/formatters/lookup.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import type { SkillDetailed } from "../types.js";
+import formatters from "./lookup.js";
+
+const skill: SkillDetailed = {
+  name: "design-auditor",
+  description: "Audit design system coverage",
+  sourcePath: "/pkgs/design-system/skills/design-auditor",
+  sourcePackage: "@canonical/design-system",
+  folderName: "design-auditor",
+  frontmatter: {
+    name: "design-auditor",
+    description: "Audit design system coverage",
+  },
+  content: "---\nname: design-auditor\n---\n\n# Design Auditor\n",
+  files: ["AUDIT_SPEC.md"],
+};
+
+describe("skill lookup formatters", () => {
+  it("plain renders a header and the full content", () => {
+    const text = formatters.plain(skill);
+    expect(text).toContain("design-auditor");
+    expect(text).toContain("@canonical/design-system");
+    expect(text).toContain("Companion files: AUDIT_SPEC.md");
+    expect(text).toContain("# Design Auditor");
+  });
+
+  it("llm renders a markdown header above the content", () => {
+    const text = formatters.llm(skill);
+    expect(text).toContain("## Skill: design-auditor");
+    expect(text).toContain("**Companion files:** AUDIT_SPEC.md");
+    expect(text).toContain("# Design Auditor");
+  });
+
+  it("llm omits the companion files line when there are none", () => {
+    const text = formatters.llm({ ...skill, files: [] });
+    expect(text).not.toContain("Companion files");
+  });
+
+  it("json serializes the skill with content and files", () => {
+    const data = JSON.parse(formatters.json(skill)) as Record<string, unknown>;
+    expect(data.name).toBe("design-auditor");
+    expect(data.files).toEqual(["AUDIT_SPEC.md"]);
+    expect(data.content).toContain("# Design Auditor");
+  });
+});