@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,69 @@
+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 { listFormatters } from "../formatters/index.js";
+import type { SkillListInput } from "../formatters/types.js";
+import { listSkills } from "../operations/index.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
+ */
+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),
+      });
+    },
+  };
+}

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

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

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

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import type { DiscoveredSkill, SkillSource } from "../types.js";
+import formatters from "./list.js";
+
+const MOCK_SKILLS: readonly DiscoveredSkill[] = [
+  {
+    name: "design-audit",
+    description: "Audit a component against DS specs",
+    sourcePath: "node_modules/@canonical/ds-global/skills/design-audit",
+    sourcePackage: "@canonical/ds-global",
+    folderName: "design-audit",
+    frontmatter: {
+      name: "design-audit",
+      description: "Audit a component against DS specs",
+      metadata: { author: "canonical" },
+    },
+  },
+  {
+    name: "scaffold-story",
+    description: "Generate a Storybook story from anatomy",
+    sourcePath: "/tmp/node_modules/@canonical/pragma-cli/skills/scaffold-story",
+    sourcePackage: "@canonical/pragma-cli",
+    folderName: "scaffold-story",
+    frontmatter: {
+      name: "scaffold-story",
+      description: "Generate a Storybook story from anatomy",
+    },
+  },
+];
+
+const MOCK_SOURCES: readonly SkillSource[] = [
+  {
+    path: "node_modules/@canonical/ds-global/skills",
+    packageName: "@canonical/ds-global",
+    available: true,
+  },
+  {
+    path: "node_modules/@canonical/anatomy-dsl/skills",
+    packageName: "@canonical/anatomy-dsl",
+    available: false,
+  },
+  {
+    path: "/tmp/node_modules/@canonical/pragma-cli/skills",
+    packageName: "@canonical/pragma-cli",
+    available: true,
+  },
+];
+
+describe("skill list formatters", () => {
+  describe("plain", () => {
+    it("groups skills by source package", () => {
+      const output = formatters.plain({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("@canonical/ds-global");
+      expect(output).toContain("@canonical/pragma-cli");
+      expect(output).toContain("design-audit");
+      expect(output).toContain("scaffold-story");
+    });
+
+    it("shows unavailable sources", () => {
+      const output = formatters.plain({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("@canonical/anatomy-dsl not installed");
+    });
+
+    it("shows total count", () => {
+      const output = formatters.plain({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("2 skills from 2 packages");
+    });
+
+    it("shows metadata when detailed", () => {
+      const output = formatters.plain({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: true,
+      });
+      expect(output).toContain("Author");
+      expect(output).toContain("canonical");
+      expect(output).toContain("Source:");
+    });
+  });
+
+  describe("llm", () => {
+    it("renders markdown with heading", () => {
+      const output = formatters.llm({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("## Skills");
+      expect(output).toContain("### @canonical/ds-global");
+      expect(output).toContain("**design-audit**");
+    });
+
+    it("notes unavailable sources", () => {
+      const output = formatters.llm({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("*Not installed: @canonical/anatomy-dsl*");
+    });
+  });
+
+  describe("json", () => {
+    it("produces valid JSON array", () => {
+      const output = formatters.json({
+        skills: MOCK_SKILLS,
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      const parsed = JSON.parse(output);
+      expect(Array.isArray(parsed)).toBe(true);
+      expect(parsed).toHaveLength(2);
+      expect(parsed[0].name).toBe("design-audit");
+      expect(parsed[0].source).toBe("@canonical/ds-global");
+    });
+  });
+
+  describe("empty skills", () => {
+    it("handles no skills gracefully", () => {
+      const output = formatters.plain({
+        skills: [],
+        sources: MOCK_SOURCES,
+        detailed: false,
+      });
+      expect(output).toContain("0 skills from 0 packages");
+    });
+  });
+});

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

@@ -0,0 +1,119 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { DiscoveredSkill } from "../types.js";
+import type { SkillListInput } from "./types.js";
+
+/**
+ * Group discovered skills by their source package name.
+ *
+ * @param skills - Skills to group.
+ * @returns A Map keyed by package name.
+ */
+function groupBySource(
+  skills: readonly DiscoveredSkill[],
+): Map<string, DiscoveredSkill[]> {
+  const groups = new Map<string, DiscoveredSkill[]>();
+  for (const skill of skills) {
+    const group = groups.get(skill.sourcePackage) ?? [];
+    group.push(skill);
+    groups.set(skill.sourcePackage, group);
+  }
+  return groups;
+}
+
+/**
+ * Formatters for `pragma skill list` output.
+ *
+ * - **plain** renders skills grouped by source package with chalk styling.
+ * - **llm** renders a markdown document with package headings.
+ * - **json** serializes a flat skill array with metadata.
+ */
+const formatters: Formatters<SkillListInput> = {
+  plain({ skills, sources, detailed }) {
+    const lines: string[] = [];
+    const grouped = groupBySource(skills);
+
+    for (const [pkg, pkgSkills] of grouped) {
+      lines.push(`  ${chalk.dim(pkg)}`);
+      for (const skill of pkgSkills) {
+        const desc = chalk.dim(skill.description);
+        lines.push(`    ${chalk.bold(skill.name.padEnd(22))}${desc}`);
+
+        if (detailed) {
+          const fm = skill.frontmatter;
+          if (fm.license) {
+            lines.push(`      License:         ${fm.license}`);
+          }
+          if (fm.compatibility?.length) {
+            lines.push(`      Compatibility:  ${fm.compatibility.join(", ")}`);
+          }
+          if (fm.metadata) {
+            for (const [key, value] of Object.entries(fm.metadata)) {
+              const label = key.charAt(0).toUpperCase() + key.slice(1);
+              lines.push(`      ${label.padEnd(16)}${String(value)}`);
+            }
+          }
+          lines.push(`      Source:         ${skill.sourcePath}`);
+        }
+      }
+      lines.push("");
+    }
+
+    const unavailable = sources.filter((s) => !s.available);
+    for (const source of unavailable) {
+      lines.push(
+        chalk.dim(
+          `  ${source.packageName} not installed (no skills from this source)`,
+        ),
+      );
+    }
+
+    const total = `${skills.length} skill${skills.length === 1 ? "" : "s"}`;
+    const pkgCount = grouped.size;
+    const pkgs = `${pkgCount} package${pkgCount === 1 ? "" : "s"}`;
+    lines.push(`${total} from ${pkgs}`);
+
+    return lines.join("\n");
+  },
+
+  llm({ skills, sources }) {
+    const lines: string[] = [];
+    const grouped = groupBySource(skills);
+
+    lines.push("## Skills");
+    lines.push("");
+
+    for (const [pkg, pkgSkills] of grouped) {
+      lines.push(`### ${pkg}`);
+      for (const skill of pkgSkills) {
+        lines.push(`- **${skill.name}** — ${skill.description}`);
+      }
+      lines.push("");
+    }
+
+    const unavailable = sources.filter((s) => !s.available);
+    if (unavailable.length > 0) {
+      lines.push(
+        `*Not installed: ${unavailable.map((s) => s.packageName).join(", ")}*`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  json({ skills }) {
+    return JSON.stringify(
+      skills.map((s) => ({
+        name: s.name,
+        description: s.description,
+        source: s.sourcePackage,
+        path: s.sourcePath,
+        metadata: s.frontmatter.metadata ?? {},
+      })),
+      null,
+      2,
+    );
+  },
+};
+
+export default formatters;

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

@@ -0,0 +1,8 @@
+import type { DiscoveredSkill, SkillSource } from "../types.js";
+
+/** Formatter input for `pragma skill list`, pairing skills with source metadata and detail flag. */
+export interface SkillListInput {
+  readonly skills: readonly DiscoveredSkill[];
+  readonly sources: readonly SkillSource[];
+  readonly detailed: boolean;
+}

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

@@ -0,0 +1,6 @@
+/** @module Shared helpers for skill discovery: frontmatter parsing and source resolution. */
+export { default as parseFrontmatter } from "./parseFrontmatter.js";
+export {
+  default as resolveSkillSources,
+  type SkillSource,
+} from "./resolveSkillSources.js";

package/src/domains/skill/helpers/parseFrontmatter.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import parseFrontmatter from "./parseFrontmatter.js";
+
+describe("parseFrontmatter", () => {
+  it("parses valid frontmatter with required fields", () => {
+    const content = `---
+name: design-audit
+description: Audit a component implementation against DS specs
+---
+
+# Design Audit
+
+Instructions here.
+`;
+    const result = parseFrontmatter(content);
+    expect(result).toEqual({
+      name: "design-audit",
+      description: "Audit a component implementation against DS specs",
+    });
+  });
+
+  it("parses frontmatter with all optional fields", () => {
+    const content = `---
+name: design-audit
+description: Audit a component implementation against DS specs
+license: MIT
+compatibility: [claude, cursor, windsurf]
+metadata:
+  author: canonical
+  version: 1.0
+---
+
+Body content.
+`;
+    const result = parseFrontmatter(content);
+    expect(result).toEqual({
+      name: "design-audit",
+      description: "Audit a component implementation against DS specs",
+      license: "MIT",
+      compatibility: ["claude", "cursor", "windsurf"],
+      metadata: { author: "canonical", version: 1.0 },
+    });
+  });
+
+  it("returns null for missing frontmatter delimiters", () => {
+    expect(parseFrontmatter("# No frontmatter here")).toBeNull();
+  });
+
+  it("returns null for empty content", () => {
+    expect(parseFrontmatter("")).toBeNull();
+  });
+
+  it("returns null when name is missing", () => {
+    const content = `---
+description: Some description
+---`;
+    expect(parseFrontmatter(content)).toBeNull();
+  });
+
+  it("returns null when description is missing", () => {
+    const content = `---
+name: some-skill
+---`;
+    expect(parseFrontmatter(content)).toBeNull();
+  });
+
+  it("returns null when name is empty string", () => {
+    const content = `---
+name:
+description: Some description
+---`;
+    expect(parseFrontmatter(content)).toBeNull();
+  });
+
+  it("handles quoted values", () => {
+    const content = `---
+name: "my-skill"
+description: 'A skill with quotes'
+---`;
+    const result = parseFrontmatter(content);
+    expect(result?.name).toBe("my-skill");
+    expect(result?.description).toBe("A skill with quotes");
+  });
+
+  it("handles metadata with nested keys", () => {
+    const content = `---
+name: test-skill
+description: A test skill
+metadata:
+  author: canonical
+  priority: high
+---`;
+    const result = parseFrontmatter(content);
+    expect(result?.metadata).toEqual({
+      author: "canonical",
+      priority: "high",
+    });
+  });
+
+  it("ignores content after closing delimiter", () => {
+    const content = `---
+name: test-skill
+description: A test skill
+---
+
+This is the body and should not affect parsing.
+name: wrong-name
+`;
+    const result = parseFrontmatter(content);
+    expect(result?.name).toBe("test-skill");
+  });
+
+  it("handles single-item compatibility array", () => {
+    const content = `---
+name: test-skill
+description: A test skill
+compatibility: [claude]
+---`;
+    const result = parseFrontmatter(content);
+    expect(result?.compatibility).toEqual(["claude"]);
+  });
+});

package/src/domains/skill/helpers/parseFrontmatter.ts

@@ -0,0 +1,112 @@
+import type { SkillFrontmatter } from "../types.js";
+
+/** Regex matching the `---`-delimited YAML frontmatter block. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Parse a single YAML scalar value (string, boolean, number, or inline array).
+ *
+ * @param raw - Raw string value from a YAML line.
+ * @returns The parsed JavaScript value.
+ */
+function parseYamlValue(raw: string): unknown {
+  const trimmed = raw.trim();
+
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed
+      .slice(1, -1)
+      .split(",")
+      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== "") return num;
+
+  return trimmed.replace(/^["']|["']$/g, "");
+}
+
+/**
+ * Parse a simple subset of YAML supporting top-level keys and one level of nesting.
+ *
+ * @param block - The YAML block content (without `---` delimiters).
+ * @returns A record of parsed key-value pairs.
+ */
+function parseSimpleYaml(block: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  let currentKey: string | null = null;
+  let nestedObject: Record<string, unknown> | null = null;
+
+  for (const line of block.split("\n")) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+
+    const indented = line.match(/^(\s+)(\w[\w-]*)\s*:\s*(.*)/);
+    const topLevel = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+
+    if (indented && currentKey && (indented[1]?.length ?? 0) >= 2) {
+      if (!nestedObject) nestedObject = {};
+      const key = indented[2] as string;
+      const value = (indented[3] ?? "").trim();
+      nestedObject[key] = value === "" ? true : parseYamlValue(value);
+    } else if (topLevel) {
+      if (currentKey && nestedObject) {
+        result[currentKey] = nestedObject;
+        nestedObject = null;
+      }
+
+      const key = topLevel[1] as string;
+      const value = topLevel[2] ?? "";
+      currentKey = key;
+      if (value === "") {
+        nestedObject = {};
+      } else {
+        result[key] = parseYamlValue(value);
+        nestedObject = null;
+      }
+    }
+  }
+
+  if (currentKey && nestedObject) {
+    result[currentKey] = nestedObject;
+  }
+
+  return result;
+}
+
+/**
+ * Extract and validate YAML frontmatter from a SKILL.md file.
+ *
+ * Requires `name` and `description` fields. Returns null for missing
+ * or malformed frontmatter.
+ *
+ * @param content - Full SKILL.md file content.
+ * @returns Parsed frontmatter, or null if invalid.
+ */
+export default function parseFrontmatter(
+  content: string,
+): SkillFrontmatter | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match?.[1]) return null;
+
+  const parsed = parseSimpleYaml(match[1]);
+
+  if (typeof parsed.name !== "string" || parsed.name === "") return null;
+  if (typeof parsed.description !== "string" || parsed.description === "")
+    return null;
+
+  return {
+    name: parsed.name,
+    description: parsed.description,
+    ...(typeof parsed.license === "string" && { license: parsed.license }),
+    ...(Array.isArray(parsed.compatibility) && {
+      compatibility: parsed.compatibility,
+    }),
+    ...(typeof parsed.metadata === "object" &&
+      parsed.metadata !== null && {
+        metadata: parsed.metadata as Readonly<Record<string, unknown>>,
+      }),
+  };
+}

package/src/domains/skill/helpers/resolveSkillSources.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { PACKAGES, resolvePackages } from "../../shared/packages.js";
+
+/** A resolved skill source directory from an installed package. */
+export interface SkillSource {
+  /** Absolute path to the skills directory. */
+  readonly dir: string;
+  /** Package name this source belongs to. */
+  readonly packageName: string;
+}
+
+/**
+ * Resolve skill source directories from the shared package registry.
+ * Package-manager agnostic -- works with bun, npm, pnpm, yarn.
+ *
+ * @returns Array of resolved skill sources with absolute paths.
+ * @note Impure
+ */
+export default function resolveSkillSources(): SkillSource[] {
+  const sources: SkillSource[] = [];
+  const resolved = resolvePackages();
+
+  for (const { pkg, dir } of resolved) {
+    const def = PACKAGES.find((p) => p.pkg === pkg);
+    if (!def?.skills) continue;
+
+    sources.push({
+      dir: join(dir, def.skills),
+      packageName: pkg,
+    });
+  }
+
+  return sources;
+}

package/src/domains/skill/index.ts

@@ -0,0 +1,19 @@
+/** @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 } 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)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export type { SkillListResult } from "./operations/index.js";
+export { discoverSkills, listSkills } from "./operations/index.js";

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * MCP tool specs for the skill domain.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { listFormatters as skillListFmt } from "../formatters/index.js";
+import { listSkills } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "skill_list",
+    description: "List available agent skills from design system packages.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const { skills, sources } = await listSkills(rt.cwd);
+
+      if (condensed) {
+        const text = skillListFmt.llm({ skills, sources, detailed: false });
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: { skills, sources }, meta: { count: skills.length } };
+    },
+  },
+];
+
+export default specs;