@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/skill/operations/discover.test.ts

@@ -7,38 +7,72 @@ import discoverSkills from "./discover.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-skill-discover-${Date.now()}`);
 
-/** Test skill sources that mirror the real package layout. */
+/**
+ * Test skill sources that mirror the real loader granularity: each source
+ * is one skill directory (`<package>/skills/<name>`) containing SKILL.md,
+ * as produced by `readPackageDir`.
+ */
 const TEST_SOURCES: SkillSource[] = [
   {
-    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",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/ds-review",
+    ),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/anatomy-dsl/skills/anatomy-author",
+    ),
     packageName: "@canonical/anatomy-dsl",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/scaffold-story",
+    ),
+    packageName: "@canonical/pragma-cli",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/broken-skill",
+    ),
     packageName: "@canonical/pragma-cli",
   },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/no-skill-md",
+    ),
+    packageName: "@canonical/design-system",
+  },
 ];
 
-function writeSkillMd(
-  source: SkillSource,
-  skillName: string,
-  content: string,
-): void {
-  const dir = join(source.dir, skillName);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "SKILL.md"), content);
+function writeSkillMd(source: SkillSource, content: string): void {
+  mkdirSync(source.dir, { recursive: true });
+  writeFileSync(join(source.dir, "SKILL.md"), content);
+}
+
+function sourceAt(index: number): SkillSource {
+  const source = TEST_SOURCES.at(index);
+  if (!source) throw new Error(`no test source at index ${index}`);
+  return source;
 }
 
 beforeAll(() => {
   mkdirSync(TMP_ROOT, { recursive: true });
 
   writeSkillMd(
-    TEST_SOURCES[0],
-    "design-audit",
+    sourceAt(0),
     `---
 name: design-audit
 description: Audit a component against DS specs
@@ -51,8 +85,7 @@ metadata:
   );
 
   writeSkillMd(
-    TEST_SOURCES[0],
-    "ds-review",
+    sourceAt(1),
     `---
 name: ds-review
 description: Review a PR for DS compliance
@@ -61,8 +94,7 @@ description: Review a PR for DS compliance
   );
 
   writeSkillMd(
-    TEST_SOURCES[2],
-    "scaffold-story",
+    sourceAt(3),
     `---
 name: scaffold-story
 description: Generate a Storybook story from anatomy
@@ -70,20 +102,19 @@ description: Generate a Storybook story from anatomy
 `,
   );
 
-  // Invalid frontmatter — should be skipped with warning
+  // Invalid frontmatter (missing description) — should be skipped with warning
   writeSkillMd(
-    TEST_SOURCES[2],
-    "broken-skill",
+    sourceAt(4),
     `---
 name: broken-skill
 ---
 `,
   );
 
-  // File without SKILL.md — should be skipped
-  const noSkillDir = join(TEST_SOURCES[0].dir, "no-skill-md");
-  mkdirSync(noSkillDir, { recursive: true });
-  writeFileSync(join(noSkillDir, "README.md"), "Not a skill");
+  // Source directory without a SKILL.md — should be skipped
+  const noSkillMd = sourceAt(5);
+  mkdirSync(noSkillMd.dir, { recursive: true });
+  writeFileSync(join(noSkillMd.dir, "README.md"), "Not a skill");
 });
 
 afterAll(() => {
@@ -100,15 +131,15 @@ describe("discoverSkills", () => {
   });
 
   it("skips missing source directories", async () => {
-    // TEST_SOURCES[1] (anatomy-dsl) was not created
+    // TEST_SOURCES[2] (anatomy-dsl) was never created on disk
     const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
     const packages = [...new Set(skills.map((s) => s.sourcePackage))];
     expect(packages).not.toContain("@canonical/anatomy-dsl");
   });
 
-  it("skips folders without SKILL.md", async () => {
+  it("skips source directories without SKILL.md", async () => {
     const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const names = skills.map((s) => s.name);
+    const names = skills.map((s) => s.folderName);
     expect(names).not.toContain("no-skill-md");
   });
 
@@ -123,7 +154,7 @@ describe("discoverSkills", () => {
     const audit = skills.find((s) => s.name === "design-audit");
     expect(audit?.sourcePackage).toBe("@canonical/design-system");
     expect(audit?.folderName).toBe("design-audit");
-    expect(audit?.sourcePath).toBe(join(TEST_SOURCES[0].dir, "design-audit"));
+    expect(audit?.sourcePath).toBe(sourceAt(0).dir);
   });
 
   it("preserves frontmatter metadata", async () => {
@@ -135,7 +166,7 @@ describe("discoverSkills", () => {
   it("returns empty array when no sources available", async () => {
     const emptySources: SkillSource[] = [
       {
-        dir: "/nonexistent/path/skills",
+        dir: "/nonexistent/path/skills/some-skill",
         packageName: "@canonical/nope",
       },
     ];

package/src/domains/skill/operations/discover.ts

@@ -1,5 +1,5 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
 import {
   parseFrontmatter,
   resolveSkillSources,
@@ -8,14 +8,18 @@ import {
 import type { DiscoveredSkill } from "../types.js";
 
 /**
- * Discover skills by scanning source package directories for subdirectories
- * containing a valid `SKILL.md` file. Missing source paths and invalid
- * frontmatter are skipped gracefully.
+ * Discover skills from resolved skill source directories.
+ *
+ * Each source directory is one skill folder (`<package>/skills/<name>`)
+ * containing a `SKILL.md` with YAML frontmatter — the granularity
+ * produced by the package loaders' `readPackageDir`. Missing files and
+ * invalid frontmatter are skipped gracefully (invalid frontmatter is
+ * reported on stderr).
  *
  * @param _cwd - Working directory (unused, sources are resolved globally).
  * @param overrideSources - Optional override for skill source definitions.
  * @returns Array of discovered skills with parsed frontmatter.
- * @note Impure
+ * @note Impure — reads SKILL.md files from the filesystem.
  */
 export default async function discoverSkills(
   _cwd: string,
@@ -25,43 +29,30 @@ export default async function discoverSkills(
   const sources = overrideSources ?? resolveSkillSources();
 
   for (const source of sources) {
-    let entries: string[];
+    const skillMdPath = resolve(source.dir, "SKILL.md");
+    let content: string;
     try {
-      entries = await readdir(source.dir);
+      content = await readFile(skillMdPath, "utf-8");
     } catch {
       continue;
     }
 
-    for (const entry of entries) {
-      const entryPath = resolve(source.dir, entry);
-      const entryStat = await stat(entryPath).catch(() => null);
-      if (!entryStat?.isDirectory()) continue;
-
-      const skillMdPath = resolve(entryPath, "SKILL.md");
-      let content: string;
-      try {
-        content = await readFile(skillMdPath, "utf-8");
-      } catch {
-        continue;
-      }
-
-      const frontmatter = parseFrontmatter(content);
-      if (!frontmatter) {
-        process.stderr.write(
-          `Warning: invalid SKILL.md frontmatter in ${skillMdPath}\n`,
-        );
-        continue;
-      }
-
-      skills.push({
-        name: frontmatter.name,
-        description: frontmatter.description,
-        sourcePath: entryPath,
-        sourcePackage: source.packageName,
-        folderName: entry,
-        frontmatter,
-      });
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) {
+      process.stderr.write(
+        `Warning: invalid SKILL.md frontmatter in ${skillMdPath}\n`,
+      );
+      continue;
     }
+
+    skills.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      sourcePath: source.dir,
+      sourcePackage: source.packageName,
+      folderName: basename(source.dir),
+      frontmatter,
+    });
   }
 
   return skills;

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

@@ -1,4 +1,5 @@
-/** @module Skill operations: discovery and listing with source metadata. */
+/** @module Skill operations: discovery, listing, and content lookup. */
 export { default as discoverSkills } from "./discover.js";
 export type { SkillListResult } from "./list.js";
 export { default as listSkills } from "./list.js";
+export { default as lookupSkill } from "./lookup.js";

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

@@ -7,25 +7,33 @@ import listSkills from "./list.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-skill-list-${Date.now()}`);
 
+/** Each source is one skill directory, matching the loader granularity. */
 const TEST_SOURCES: SkillSource[] = [
   {
-    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",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/anatomy-dsl/skills/anatomy-author",
+    ),
     packageName: "@canonical/anatomy-dsl",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/scaffold-story",
+    ),
     packageName: "@canonical/pragma-cli",
   },
 ];
 
 beforeAll(() => {
-  mkdirSync(TMP_ROOT, { recursive: true });
-
-  const skillDir = join(TEST_SOURCES[0].dir, "design-audit");
+  const skillDir = TEST_SOURCES.at(0)?.dir ?? "";
   mkdirSync(skillDir, { recursive: true });
   writeFileSync(
     join(skillDir, "SKILL.md"),
@@ -45,7 +53,7 @@ describe("listSkills", () => {
   it("returns discovered skills", async () => {
     const { skills } = await listSkills(TMP_ROOT, TEST_SOURCES);
     expect(skills).toHaveLength(1);
-    expect(skills[0].name).toBe("design-audit");
+    expect(skills.at(0)?.name).toBe("design-audit");
   });
 
   it("reports source availability", async () => {

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

@@ -0,0 +1,91 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { SkillSource } from "../helpers/index.js";
+import lookupSkill from "./lookup.js";
+
+const TMP_ROOT = join(tmpdir(), `pragma-skill-lookup-${Date.now()}`);
+
+/** Each source is one skill directory, matching the loader granularity. */
+const TEST_SOURCES: SkillSource[] = [
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-auditor",
+    ),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/code-standards/skills/add-standard",
+    ),
+    packageName: "@canonical/code-standards",
+  },
+];
+
+const AUDITOR_CONTENT = `---
+name: design-auditor
+description: Audit design system coverage
+---
+
+# Design Auditor
+
+Full instructions here.
+`;
+
+beforeAll(() => {
+  const auditor = TEST_SOURCES.at(0)?.dir ?? "";
+  mkdirSync(auditor, { recursive: true });
+  writeFileSync(join(auditor, "SKILL.md"), AUDITOR_CONTENT);
+  writeFileSync(join(auditor, "AUDIT_SPEC.md"), "# Spec");
+
+  const addStandard = TEST_SOURCES.at(1)?.dir ?? "";
+  mkdirSync(addStandard, { recursive: true });
+  writeFileSync(
+    join(addStandard, "SKILL.md"),
+    `---
+name: add-standard
+description: Create a new code standard
+---
+`,
+  );
+});
+
+afterAll(() => {
+  rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+describe("lookupSkill", () => {
+  it("returns the skill with full content and companion files", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "design-auditor", TEST_SOURCES);
+    expect(skill.name).toBe("design-auditor");
+    expect(skill.content).toBe(AUDITOR_CONTENT);
+    expect(skill.files).toEqual(["AUDIT_SPEC.md"]);
+    expect(skill.sourcePackage).toBe("@canonical/design-system");
+  });
+
+  it("matches case-insensitively", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "Design-Auditor", TEST_SOURCES);
+    expect(skill.name).toBe("design-auditor");
+  });
+
+  it("reports no companion files when SKILL.md is alone", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "add-standard", TEST_SOURCES);
+    expect(skill.files).toEqual([]);
+  });
+
+  it("throws not-found with suggestions for unknown names", async () => {
+    await expect(
+      lookupSkill(TMP_ROOT, "design-audit", TEST_SOURCES),
+    ).rejects.toMatchObject({
+      code: "ENTITY_NOT_FOUND",
+      suggestions: ["design-auditor"],
+    });
+    await expect(
+      lookupSkill(TMP_ROOT, "nope", TEST_SOURCES),
+    ).rejects.toBeInstanceOf(PragmaError);
+  });
+});

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

@@ -0,0 +1,70 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { PragmaError } from "#error";
+import { suggestNames } from "../../shared/suggestions/index.js";
+import type { SkillSource } from "../helpers/index.js";
+import type { SkillDetailed } from "../types.js";
+import discoverSkills from "./discover.js";
+
+/**
+ * Look up one skill by name or folder name and serve its content.
+ *
+ * Matches case-insensitively against the frontmatter name and the skill's
+ * folder name, then reads the full SKILL.md text plus the names of any
+ * companion files shipped alongside it (e.g. spec documents).
+ *
+ * @param cwd - Working directory.
+ * @param query - Skill name or folder name to look up.
+ * @param overrideSources - Optional override for skill source definitions.
+ * @returns The matched skill with content and companion file names.
+ * @throws PragmaError with code ENTITY_NOT_FOUND and ranked suggestions
+ *   when no skill matches.
+ * @note Impure — reads SKILL.md and the skill directory listing.
+ */
+export default async function lookupSkill(
+  cwd: string,
+  query: string,
+  overrideSources?: SkillSource[],
+): Promise<SkillDetailed> {
+  const skills = await discoverSkills(cwd, overrideSources);
+  const queryLower = query.toLowerCase();
+  const match = skills.find(
+    (skill) =>
+      skill.name.toLowerCase() === queryLower ||
+      skill.folderName.toLowerCase() === queryLower,
+  );
+
+  if (!match) {
+    throw PragmaError.notFound("skill", query, {
+      suggestions: suggestNames(
+        query,
+        skills.map((skill) => skill.name),
+      ),
+      recovery: {
+        message: "List available skills.",
+        cli: "pragma skill list",
+        mcp: { tool: "skill_list" },
+      },
+    });
+  }
+
+  const content = await readFile(
+    resolve(match.sourcePath, "SKILL.md"),
+    "utf-8",
+  );
+  const files = await listCompanionFiles(match.sourcePath);
+
+  return { ...match, content, files };
+}
+
+async function listCompanionFiles(dir: string): Promise<readonly string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name !== "SKILL.md")
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { skillListStory } from "./stories.js";
+import type { SkillSource } from "./types.js";
+
+const availableSource: SkillSource = {
+  path: "/pkgs/design-system/skills/design-auditor",
+  packageName: "@canonical/design-system",
+  available: true,
+};
+
+const unavailableSource: SkillSource = {
+  path: "/pkgs/missing/skills/gone",
+  packageName: "@canonical/missing",
+  available: false,
+};
+
+describe("skillListStory", () => {
+  it("passes the CLI detailed flag into the formatter input", () => {
+    const data = { skills: [], sources: [] };
+    expect(skillListStory.toOutput(data, { detailed: true }).detailed).toBe(
+      true,
+    );
+    expect(skillListStory.toOutput(data, {}).detailed).toBe(false);
+  });
+
+  it("suggests installing packages when no source is available", () => {
+    const error = skillListStory.emptyError?.(
+      { skills: [], sources: [unavailableSource] },
+      {},
+    );
+    expect(error?.recovery?.message).toBe("Install @canonical packages first");
+  });
+
+  it("reports missing SKILL.md files when sources are available", () => {
+    const error = skillListStory.emptyError?.(
+      { skills: [], sources: [availableSource] },
+      {},
+    );
+    expect(error?.recovery?.message).toBe(
+      "No SKILL.md files found in source packages",
+    );
+  });
+});

package/src/domains/skill/stories.ts

@@ -0,0 +1,103 @@
+/**
+ * Skill read stories — the single declaration of `skill list` and
+ * `skill lookup` for both surfaces.
+ *
+ * `skill lookup` serves the full SKILL.md content, making skills directly
+ * consumable by agents over MCP (previously only metadata was listed).
+ */
+
+import { PragmaError } from "#error";
+import lookupMany from "../shared/lookupMany.js";
+import {
+  type LookupStory,
+  type ReadStory,
+  requirePragmaContext,
+} from "../shared/stories/index.js";
+import { listFormatters, lookupFormatters } from "./formatters/index.js";
+import type { SkillListInput } from "./formatters/types.js";
+import {
+  discoverSkills,
+  listSkills,
+  lookupSkill,
+  type SkillListResult,
+} from "./operations/index.js";
+import type { SkillDetailed } from "./types.js";
+
+/** The `skill list` / `skill_list` read story. */
+export const skillListStory: ReadStory<SkillListResult, SkillListInput> = {
+  noun: "skill",
+  verb: "list",
+  description: "List available agent skills from design system packages",
+  toolDescription: "List available agent skills from design system packages.",
+  params: [
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full metadata for each skill",
+      default: false,
+      surfaces: "cli",
+    },
+  ],
+  examples: [
+    "pragma skill list",
+    "pragma skill list --detailed",
+    "pragma skill list --llm",
+    "pragma skill list --format json",
+  ],
+  resolve: (rt) => listSkills(rt.cwd),
+  toOutput: ({ skills, sources }, params) => ({
+    skills,
+    sources,
+    detailed: params.detailed === true,
+  }),
+  formatters: listFormatters,
+  toEnvelope: ({ skills, sources }) => ({
+    data: { skills, sources },
+    meta: { count: skills.length },
+  }),
+  emptyError: ({ skills, sources }) => {
+    if (skills.length > 0) return undefined;
+    const allUnavailable = sources.every((source) => !source.available);
+    return PragmaError.emptyResults("skill", {
+      recovery: {
+        message: allUnavailable
+          ? "Install @canonical packages first"
+          : "No SKILL.md files found in source packages",
+      },
+    });
+  },
+};
+
+/** The `skill lookup` / `skill_lookup` read story. */
+export const skillLookupStory: LookupStory<SkillDetailed, SkillDetailed> = {
+  noun: "skill",
+  description: "Show full instructions for a skill by name",
+  toolDescription:
+    "Get full skill instructions (SKILL.md content) for one or more agent skills by name.",
+  namesDescription: "Skill names",
+  namesToolDescription: "Skill names to look up (e.g. ['design-auditor'])",
+  complete: async (partial, cmdCtx) => {
+    const ctx = requirePragmaContext(cmdCtx);
+    const skills = await discoverSkills(ctx.cwd);
+    return skills
+      .map((skill) => skill.name)
+      .filter((name) => name.toLowerCase().startsWith(partial.toLowerCase()));
+  },
+  examples: [
+    "pragma skill lookup design-auditor",
+    "pragma skill lookup design-auditor add-standard",
+    "pragma skill lookup design-auditor --llm",
+  ],
+  resolve: (rt, names) =>
+    lookupMany(names, (query) => lookupSkill(rt.cwd, query)),
+  toFmtInput: (skill) => skill,
+  formatters: lookupFormatters,
+  emptyNamesError: () =>
+    PragmaError.invalidInput("names", "(empty)", {
+      recovery: {
+        message: "List available skills.",
+        cli: "pragma skill list",
+        mcp: { tool: "skill_list" },
+      },
+    }),
+};

package/src/domains/skill/types.ts

@@ -23,3 +23,11 @@ export interface SkillSource {
   readonly packageName: string;
   readonly available: boolean;
 }
+
+/** A discovered skill enriched with its full SKILL.md content and companion files. */
+export interface SkillDetailed extends DiscoveredSkill {
+  /** Full SKILL.md text, frontmatter included. */
+  readonly content: string;
+  /** Companion file names shipped next to SKILL.md (e.g. spec documents). */
+  readonly files: readonly string[];
+}

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

@@ -122,4 +122,12 @@ describe("token lookup command", () => {
     expect(text).toContain("color.primary");
     expect(text).toContain("spacing.sm");
   });
+
+  it("rejects an empty names list with INVALID_INPUT", async () => {
+    const ctx = makeCtx();
+    const cmd = lookupCommand(ctx);
+    await expect(cmd.execute({ names: [] }, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+    });
+  });
 });