@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/skill/index.ts

@@ -1,23 +0,0 @@
-/** @module Skill domain -- CLI commands and operations for `pragma skill`. */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../shared/context.js";
-import { listCommand, lookupCommand } from "./commands/index.js";
-
-/**
- * Return all skill command definitions.
- *
- * @param ctx - Pragma context providing cwd and formatter selection.
- * @returns An array of CommandDefinitions for the skill subcommands.
- */
-export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx)];
-}
-
-export { specs as mcpSpecs } from "./mcp/index.js";
-export type { SkillListResult } from "./operations/index.js";
-export {
-  discoverSkills,
-  listSkills,
-  lookupSkill,
-} from "./operations/index.js";

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

@@ -1,2 +0,0 @@
-/** @module Skill domain MCP barrel — skill_list. */
-export { default as specs } from "./specs.js";

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

@@ -1,19 +0,0 @@
-/**
- * MCP tool specs for the skill domain — skill_list and skill_lookup,
- * compiled from the skill read stories in `../stories.ts`. skill_lookup
- * serves full SKILL.md content so agents can load skills over MCP.
- */
-
-import {
-  compileLookupTool,
-  compileReadTool,
-} from "../../shared/stories/index.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { skillListStory, skillLookupStory } from "../stories.js";
-
-const specs: readonly ToolSpec[] = [
-  compileReadTool(skillListStory),
-  compileLookupTool(skillLookupStory),
-];
-
-export default specs;

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

@@ -1,176 +0,0 @@
-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 type { SkillSource } from "../helpers/index.js";
-import discoverSkills from "./discover.js";
-
-const TMP_ROOT = join(tmpdir(), `pragma-skill-discover-${Date.now()}`);
-
-/**
- * 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/design-audit",
-    ),
-    packageName: "@canonical/design-system",
-  },
-  {
-    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/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, 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(
-    sourceAt(0),
-    `---
-name: design-audit
-description: Audit a component against DS specs
-metadata:
-  author: canonical
----
-
-# Design Audit
-`,
-  );
-
-  writeSkillMd(
-    sourceAt(1),
-    `---
-name: ds-review
-description: Review a PR for DS compliance
----
-`,
-  );
-
-  writeSkillMd(
-    sourceAt(3),
-    `---
-name: scaffold-story
-description: Generate a Storybook story from anatomy
----
-`,
-  );
-
-  // Invalid frontmatter (missing description) — should be skipped with warning
-  writeSkillMd(
-    sourceAt(4),
-    `---
-name: broken-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(() => {
-  rmSync(TMP_ROOT, { recursive: true, force: true });
-});
-
-describe("discoverSkills", () => {
-  it("discovers skills from available sources", async () => {
-    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const names = skills.map((s) => s.name);
-    expect(names).toContain("design-audit");
-    expect(names).toContain("ds-review");
-    expect(names).toContain("scaffold-story");
-  });
-
-  it("skips missing source directories", async () => {
-    // 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 source directories without SKILL.md", async () => {
-    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const names = skills.map((s) => s.folderName);
-    expect(names).not.toContain("no-skill-md");
-  });
-
-  it("skips skills with invalid frontmatter", async () => {
-    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const names = skills.map((s) => s.name);
-    expect(names).not.toContain("broken-skill");
-  });
-
-  it("populates source metadata correctly", async () => {
-    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    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(sourceAt(0).dir);
-  });
-
-  it("preserves frontmatter metadata", async () => {
-    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const audit = skills.find((s) => s.name === "design-audit");
-    expect(audit?.frontmatter.metadata).toEqual({ author: "canonical" });
-  });
-
-  it("returns empty array when no sources available", async () => {
-    const emptySources: SkillSource[] = [
-      {
-        dir: "/nonexistent/path/skills/some-skill",
-        packageName: "@canonical/nope",
-      },
-    ];
-    const skills = await discoverSkills("/nonexistent", emptySources);
-    expect(skills).toEqual([]);
-  });
-});

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

@@ -1,59 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { basename, resolve } from "node:path";
-import {
-  parseFrontmatter,
-  resolveSkillSources,
-  type SkillSource,
-} from "../helpers/index.js";
-import type { DiscoveredSkill } from "../types.js";
-
-/**
- * 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 — reads SKILL.md files from the filesystem.
- */
-export default async function discoverSkills(
-  _cwd: string,
-  overrideSources?: SkillSource[],
-): Promise<DiscoveredSkill[]> {
-  const skills: DiscoveredSkill[] = [];
-  const sources = overrideSources ?? resolveSkillSources();
-
-  for (const source of sources) {
-    const skillMdPath = resolve(source.dir, "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: source.dir,
-      sourcePackage: source.packageName,
-      folderName: basename(source.dir),
-      frontmatter,
-    });
-  }
-
-  return skills;
-}

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

@@ -1,5 +0,0 @@
-/** @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

@@ -1,76 +0,0 @@
-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 type { SkillSource } from "../helpers/index.js";
-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/design-audit",
-    ),
-    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/scaffold-story",
-    ),
-    packageName: "@canonical/pragma-cli",
-  },
-];
-
-beforeAll(() => {
-  const skillDir = TEST_SOURCES.at(0)?.dir ?? "";
-  mkdirSync(skillDir, { recursive: true });
-  writeFileSync(
-    join(skillDir, "SKILL.md"),
-    `---
-name: design-audit
-description: Audit a component against DS specs
----
-`,
-  );
-});
-
-afterAll(() => {
-  rmSync(TMP_ROOT, { recursive: true, force: true });
-});
-
-describe("listSkills", () => {
-  it("returns discovered skills", async () => {
-    const { skills } = await listSkills(TMP_ROOT, TEST_SOURCES);
-    expect(skills).toHaveLength(1);
-    expect(skills.at(0)?.name).toBe("design-audit");
-  });
-
-  it("reports source availability", async () => {
-    const { sources } = await listSkills(TMP_ROOT, TEST_SOURCES);
-    const ds = sources.find(
-      (s) => s.packageName === "@canonical/design-system",
-    );
-    expect(ds?.available).toBe(true);
-
-    const anatomyDsl = sources.find(
-      (s) => s.packageName === "@canonical/anatomy-dsl",
-    );
-    expect(anatomyDsl?.available).toBe(false);
-  });
-
-  it("includes all three sources in result", async () => {
-    const { sources } = await listSkills(TMP_ROOT, TEST_SOURCES);
-    expect(sources).toHaveLength(3);
-  });
-});

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

@@ -1,47 +0,0 @@
-import { stat } from "node:fs/promises";
-import {
-  resolveSkillSources,
-  type SkillSource as SkillSourceDef,
-} from "../helpers/index.js";
-import type { DiscoveredSkill, SkillSource } from "../types.js";
-import discoverSkills from "./discover.js";
-
-/** Result of listing skills, including source availability metadata. */
-export interface SkillListResult {
-  readonly skills: readonly DiscoveredSkill[];
-  readonly sources: readonly SkillSource[];
-}
-
-/**
- * List all discovered skills along with source availability metadata.
- *
- * Wraps {@link discoverSkills} and enriches the result with per-source
- * availability flags by checking the filesystem.
- *
- * @param cwd - Working directory.
- * @param overrideSources - Optional override for skill source definitions.
- * @returns Skills and source availability information.
- * @note Impure
- */
-export default async function listSkills(
-  cwd: string,
-  overrideSources?: SkillSourceDef[],
-): Promise<SkillListResult> {
-  const resolved = overrideSources ?? resolveSkillSources();
-  const skills = await discoverSkills(cwd, resolved);
-
-  const sources: SkillSource[] = await Promise.all(
-    resolved.map(async (source) => {
-      const available = await stat(source.dir)
-        .then((s) => s.isDirectory())
-        .catch(() => false);
-      return {
-        path: source.dir,
-        packageName: source.packageName,
-        available,
-      };
-    }),
-  );
-
-  return { skills, sources };
-}

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

@@ -1,91 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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",
-    );
-  });
-});