@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import suggestNames from "./suggestNames.js";
+
+describe("suggestNames", () => {
+  it("T1-1: suggests edit-distance match for single-char typo", () => {
+    expect(suggestNames("Buton", ["Button", "Card", "Input"])).toEqual([
+      "Button",
+    ]);
+  });
+
+  it("T1-2: suggests dot-separated names with typo in last segment", () => {
+    const candidates = [
+      "react.component.props",
+      "react.component.props.wrapper",
+      "react.component.props.html_rendering",
+      "react.component.naming",
+      "css.selectors.namespace",
+    ];
+    const result = suggestNames("react.component.prosp", candidates);
+    expect(result.at(0)).toBe("react.component.props");
+    expect(result.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("T1-3: matches case-insensitively, preserves original casing", () => {
+    expect(
+      suggestNames("buton-background", ["Button-Background", "color-primary"]),
+    ).toEqual(["Button-Background"]);
+  });
+
+  it("T1-4: returns prefix matches ranked first", () => {
+    const result = suggestNames("Accordion", [
+      "AccordionItem",
+      "AccordionGroup",
+      "Button",
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result).toContain("AccordionItem");
+    expect(result).toContain("AccordionGroup");
+  });
+
+  it("T1-5: returns empty for completely unrelated input", () => {
+    expect(suggestNames("zzzzz", ["Button", "Card", "Input"])).toEqual([]);
+  });
+
+  it("T1-6: returns empty for empty query", () => {
+    expect(suggestNames("", ["Button"])).toEqual([]);
+  });
+
+  it("T1-7: excludes exact matches", () => {
+    expect(suggestNames("Button", ["Button", "Card"])).toEqual([]);
+  });
+
+  it("T1-8: ranks multiple candidates by distance", () => {
+    const result = suggestNames("Buttn", ["Button", "Butter", "Bitten"]);
+    expect(result).toContain("Button");
+    expect(result).toContain("Butter");
+    expect(result.indexOf("Button")).toBeLessThan(result.indexOf("Butter"));
+  });
+
+  it("respects maxResults option", () => {
+    const candidates = Array.from({ length: 20 }, (_, i) => `Item${i}`);
+    const result = suggestNames("Item", candidates, { maxResults: 3 });
+    expect(result.length).toBeLessThanOrEqual(3);
+  });
+
+  it("respects threshold option", () => {
+    const result = suggestNames("Buton", ["Button"], { threshold: 0.05 });
+    expect(result).toEqual([]);
+  });
+});

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

@@ -0,0 +1,130 @@
+/**
+ * Rank candidates by similarity to a failed lookup query.
+ *
+ * Returns up to {@link maxResults} names sorted by relevance:
+ * 1. Prefix matches (query is a case-insensitive prefix of candidate)
+ * 2. Edit-distance matches (Damerau-Levenshtein, normalized ≤ threshold)
+ *
+ * Exact matches are excluded — if the query exactly matches a candidate,
+ * the caller should have found it and never reached this function.
+ *
+ * @param query - The user-supplied name that failed lookup.
+ * @param candidates - All known names in the domain.
+ * @param opts.maxResults - Max suggestions to return (default: 5).
+ * @param opts.threshold - Max normalized edit distance (default: 0.4).
+ * @returns Ranked suggestions with original casing preserved.
+ */
+export default function suggestNames(
+  query: string,
+  candidates: readonly string[],
+  opts?: { maxResults?: number; threshold?: number },
+): string[] {
+  if (query === "") return [];
+
+  const maxResults = opts?.maxResults ?? 5;
+  const threshold = opts?.threshold ?? 0.4;
+  const queryLower = query.toLowerCase();
+
+  type Scored = { name: string; score: number };
+  const scored: Scored[] = [];
+
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+
+    if (candidateLower === queryLower) continue;
+
+    if (candidateLower.startsWith(queryLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+
+    const distance = damerauLevenshtein(queryLower, candidateLower);
+    const maxLen = Math.max(queryLower.length, candidateLower.length);
+    const normalized = maxLen === 0 ? 0 : distance / maxLen;
+
+    if (normalized <= threshold) {
+      scored.push({ name: candidate, score: normalized });
+    }
+  }
+
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, maxResults).map((s) => s.name);
+}
+
+/**
+ * Damerau-Levenshtein distance between two strings.
+ *
+ * Counts insertions, deletions, substitutions, and adjacent transpositions.
+ */
+function damerauLevenshtein(a: string, b: string): number {
+  const lenA = a.length;
+  const lenB = b.length;
+
+  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++) {
+    getRow(matrix, i)[0] = i;
+  }
+  const firstRow = getRow(matrix, 0);
+  for (let j = 0; j <= lenB; 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;
+
+      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]) {
+        const prevPrevRow = getRow(matrix, i - 2);
+        row[j] = Math.min(
+          getCell(row, j),
+          getCell(prevPrevRow, j - 2) + cost, // transposition
+        );
+      }
+    }
+  }
+
+  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/shared/types/index.ts

@@ -31,6 +31,7 @@ export type {
   OntologySummary,
 } from "./ontology.js";
 export type { PragmaRuntime } from "./runtime.js";
+export type { SampleOutput, SampleResult } from "./sample.js";
 export type {
   CategorySummary,
   CodeBlock,

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

@@ -2,14 +2,16 @@
 
 import type { Store } from "@canonical/ke";
 import type { PragmaConfig } from "#config";
+import type { SemanticPackage } from "../semanticPackage.js";
 
 /**
  * Boot-time state shared by CLI, MCP, and completions server.
  *
- * Four members:
+ * Five members:
  * - `store` — the ke triple store, loaded and ready for SPARQL queries.
  * - `config` — resolved pragma config (tier, channel).
  * - `cwd` — working directory used for config and source resolution.
+ * - `packages` — resolved semantic packages (for diagnostics and skills).
  * - `dispose()` — tears down the store and frees WASM memory. Must be
  *   called exactly once; calling operations after dispose is undefined.
  */
@@ -17,5 +19,6 @@ export interface PragmaRuntime {
   readonly store: Store;
   readonly config: PragmaConfig;
   readonly cwd: string;
+  readonly packages: readonly SemanticPackage[];
   dispose(): void;
 }

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

@@ -0,0 +1,17 @@
+/**
+ * Shared types for sample operations across domains.
+ *
+ * Sample returns 1–5 complete instances as exemplars so agents
+ * can learn actual data shapes before writing queries.
+ */
+
+/** Raw result from a sample operation — instances plus total count. */
+export interface SampleResult<T> {
+  readonly samples: readonly T[];
+  readonly totalCount: number;
+}
+
+/** Full sample output including agent guidance. */
+export interface SampleOutput<T> extends SampleResult<T> {
+  readonly nextSteps: readonly string[];
+}

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");
+  });
+});

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

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { SkillDetailed } from "../types.js";
+
+/**
+ * Formatters for `pragma skill lookup` output.
+ *
+ * - **plain** renders a chalk-styled header (name, source, files) above
+ *   the full SKILL.md content.
+ * - **llm** renders a markdown header above the content — the skill body
+ *   is already markdown, so it is served verbatim.
+ * - **json** serializes the skill with its content and companion files.
+ */
+const formatters: Formatters<SkillDetailed> = {
+  plain(skill) {
+    const lines: string[] = [
+      chalk.bold(skill.name),
+      chalk.dim(skill.description),
+      chalk.dim(`Source: ${skill.sourcePackage} (${skill.sourcePath})`),
+    ];
+    if (skill.files.length > 0) {
+      lines.push(chalk.dim(`Companion files: ${skill.files.join(", ")}`));
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  llm(skill) {
+    const lines: string[] = [
+      `## Skill: ${skill.name}`,
+      "",
+      `**Source:** ${skill.sourcePackage} (${skill.folderName})`,
+    ];
+    if (skill.files.length > 0) {
+      lines.push(`**Companion files:** ${skill.files.join(", ")}`);
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  json(skill) {
+    return JSON.stringify(
+      {
+        name: skill.name,
+        description: skill.description,
+        source: skill.sourcePackage,
+        path: skill.sourcePath,
+        files: skill.files,
+        content: skill.content,
+      },
+      null,
+      2,
+    );
+  },
+};
+
+export default formatters;