@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,145 @@
+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 package layout. */
+const TEST_SOURCES: SkillSource[] = [
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    packageName: "@canonical/anatomy-dsl",
+  },
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    packageName: "@canonical/pragma-cli",
+  },
+];
+
+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);
+}
+
+beforeAll(() => {
+  mkdirSync(TMP_ROOT, { recursive: true });
+
+  writeSkillMd(
+    TEST_SOURCES[0],
+    "design-audit",
+    `---
+name: design-audit
+description: Audit a component against DS specs
+metadata:
+  author: canonical
+---
+
+# Design Audit
+`,
+  );
+
+  writeSkillMd(
+    TEST_SOURCES[0],
+    "ds-review",
+    `---
+name: ds-review
+description: Review a PR for DS compliance
+---
+`,
+  );
+
+  writeSkillMd(
+    TEST_SOURCES[2],
+    "scaffold-story",
+    `---
+name: scaffold-story
+description: Generate a Storybook story from anatomy
+---
+`,
+  );
+
+  // Invalid frontmatter — should be skipped with warning
+  writeSkillMd(
+    TEST_SOURCES[2],
+    "broken-skill",
+    `---
+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");
+});
+
+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[1] (anatomy-dsl) was not created
+    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 () => {
+    const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
+    const names = skills.map((s) => s.name);
+    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(join(TEST_SOURCES[0].dir, "design-audit"));
+  });
+
+  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",
+        packageName: "@canonical/nope",
+      },
+    ];
+    const skills = await discoverSkills("/nonexistent", emptySources);
+    expect(skills).toEqual([]);
+  });
+});

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

@@ -0,0 +1,68 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  parseFrontmatter,
+  resolveSkillSources,
+  type SkillSource,
+} from "../helpers/index.js";
+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.
+ *
+ * @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
+ */
+export default async function discoverSkills(
+  _cwd: string,
+  overrideSources?: SkillSource[],
+): Promise<DiscoveredSkill[]> {
+  const skills: DiscoveredSkill[] = [];
+  const sources = overrideSources ?? resolveSkillSources();
+
+  for (const source of sources) {
+    let entries: string[];
+    try {
+      entries = await readdir(source.dir);
+    } 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,
+      });
+    }
+  }
+
+  return skills;
+}

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

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

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

@@ -0,0 +1,68 @@
+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()}`);
+
+const TEST_SOURCES: SkillSource[] = [
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    packageName: "@canonical/anatomy-dsl",
+  },
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    packageName: "@canonical/pragma-cli",
+  },
+];
+
+beforeAll(() => {
+  mkdirSync(TMP_ROOT, { recursive: true });
+
+  const skillDir = join(TEST_SOURCES[0].dir, "design-audit");
+  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[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

@@ -0,0 +1,47 @@
+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/types.ts

@@ -0,0 +1,25 @@
+/** YAML frontmatter extracted from a SKILL.md file per the agentskills.io spec. */
+export interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string;
+  readonly license?: string;
+  readonly compatibility?: readonly string[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/** A skill discovered from a hardcoded source path. */
+export interface DiscoveredSkill {
+  readonly name: string;
+  readonly description: string;
+  readonly sourcePath: string;
+  readonly sourcePackage: string;
+  readonly folderName: string;
+  readonly frontmatter: SkillFrontmatter;
+}
+
+/** Availability metadata about a skill source entry. */
+export interface SkillSource {
+  readonly path: string;
+  readonly packageName: string;
+  readonly available: boolean;
+}

package/src/domains/standard/commands/categories.test.ts

@@ -0,0 +1,70 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { PragmaContext } from "../../shared/context.js";
+import buildCategoriesCommand from "./categories.js";
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store,
+    config: { tier: undefined, channel: "prerelease" },
+    ...overrides,
+  };
+}
+
+async function executeOutput(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<{ value: unknown; text: string }> {
+  const result = await cmd.execute(params, ctx);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  const text = result.render.plain(result.value);
+  return { value: result.value, text };
+}
+
+describe("buildCategoriesCommand", () => {
+  it("returns categories with counts", async () => {
+    const ctx = makeCtx();
+    const cmd = buildCategoriesCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("react (2 standards)");
+    expect(text).toContain("code (1 standard)");
+  });
+
+  it("renders LLM format with --llm", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildCategoriesCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("## Standard Categories");
+    expect(text).toContain("**react**");
+  });
+
+  it("renders JSON output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildCategoriesCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    const parsed = JSON.parse(text);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.some((c: { name: string }) => c.name === "react")).toBe(true);
+  });
+});

package/src/domains/standard/commands/categories.ts

@@ -0,0 +1,48 @@
+/**
+ * Wires the `pragma standard categories` CLI command.
+ *
+ * Lists all standard categories with their standard counts. Throws a
+ * structured recovery error when no categories are found.
+ */
+
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { categoriesFormatters } from "../formatters/index.js";
+import { listCategories } from "../operations/index.js";
+
+export default function buildCategoriesCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["standard", "categories"],
+    description: "List all standard categories with counts",
+    parameters: [],
+    meta: {
+      examples: ["pragma standard categories"],
+    },
+    execute: async (
+      _params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const categories = await listCategories(ctx.store);
+
+      if (categories.length === 0) {
+        throw PragmaError.emptyResults("categories", {
+          recovery: {
+            message:
+              "Ensure code standards packages are installed: bun add -D @canonical/code-standards",
+          },
+        });
+      }
+
+      return createOutputResult(categories, {
+        plain: selectFormatter(ctx, categoriesFormatters),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,5 @@
+/** @module Re-exports standard command builders (`categories`, `get`, `list`). */
+
+export { default as categoriesCommand } from "./categories.js";
+export { default as listCommand } from "./list.js";
+export { default as lookupCommand } from "./lookup.js";

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

@@ -0,0 +1,105 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { PragmaContext } from "../../shared/context.js";
+import buildListCommand from "./list.js";
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store,
+    config: { tier: undefined, channel: "prerelease" },
+    ...overrides,
+  };
+}
+
+async function executeOutput(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<{ value: unknown; text: string }> {
+  const result = await cmd.execute(params, ctx);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  const text = result.render.plain(result.value);
+  return { value: result.value, text };
+}
+
+describe("buildListCommand", () => {
+  it("returns output result with all standards", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("react/component/folder-structure");
+    expect(text).toContain("react/component/props");
+    expect(text).toContain("code/function/purity");
+  });
+
+  it("filters by --category", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, { category: "react" }, ctx);
+    expect(text).toContain("react/component/folder-structure");
+    expect(text).toContain("react/component/props");
+    expect(text).not.toContain("code/function/purity");
+  });
+
+  it("filters by --search", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, { search: "folder" }, ctx);
+    expect(text).toContain("react/component/folder-structure");
+    expect(text).not.toContain("code/function/purity");
+  });
+
+  it("throws EMPTY_RESULTS for non-matching filter", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    try {
+      await cmd.execute({ category: "nonexistent" }, ctx);
+      expect.fail("Should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(PragmaError);
+      expect((e as PragmaError).code).toBe("EMPTY_RESULTS");
+    }
+  });
+
+  it("renders LLM format with --llm", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("## Standards");
+    expect(text).toContain("**react/component/folder-structure**");
+  });
+
+  it("renders JSON output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    const parsed = JSON.parse(text);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(
+      parsed.some(
+        (s: { name: string }) => s.name === "react/component/folder-structure",
+      ),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * Wires the `pragma standard list` CLI command.
+ *
+ * Lists all code standards with optional category and search filters.
+ * Supports progressive disclosure via `--digest` (summary + first example)
+ * and `--detailed` (full dos/donts) flags.
+ */
+
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} 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 { StandardListOutput } from "../formatters/types.js";
+import { resolveStandardList } from "../orchestration/index.js";
+
+export default function buildListCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["standard", "list"],
+    description: "List all code standards",
+    parameters: [
+      {
+        name: "category",
+        description: "Filter by category",
+        type: "string",
+      },
+      {
+        name: "search",
+        description: "Search in name and description",
+        type: "string",
+      },
+      {
+        name: "digest",
+        description: "Show description and first example for each standard",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "detailed",
+        description: "Show full dos/donts for each standard",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma standard list",
+        "pragma standard list --category react",
+        'pragma standard list --search "folder"',
+        "pragma standard list --digest",
+        "pragma standard list --detailed",
+        "pragma standard list --llm",
+      ],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const contract = await resolveStandardList(ctx, {
+        category: params.category as string | undefined,
+        search: params.search as string | undefined,
+        digest: params.digest === true,
+        detailed: params.detailed === true,
+      });
+
+      const output: StandardListOutput = {
+        items: contract.items,
+        details: contract.details,
+        disclosure: contract.disclosure,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, listFormatters),
+      });
+    },
+  };
+}