@canonical/pragma-cli 0.31.0 → 0.33.0

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

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

@@ -1,119 +0,0 @@
-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/lookup.test.ts

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

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

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

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

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

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

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

@@ -1,70 +0,0 @@
-import { parsePackageEntry } from "../../refs/operations/parseRef.js";
-import {
-  createGitLoader,
-  createLocalLoader,
-} from "../../shared/loaders/index.js";
-import { DEFAULT_PACKAGES } from "../../shared/packages.js";
-import type { SemanticPackage } from "../../shared/semanticPackage.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 semantic packages.
- *
- * When `packages` is provided (from PragmaRuntime), extracts skill entries
- * directly. Otherwise, resolves packages using local and git loaders
- * (bundled loader is excluded since it has no filesystem skills).
- *
- * @param packages - Pre-resolved semantic packages (from boot).
- * @returns Array of resolved skill sources with absolute paths.
- * @note Impure when packages is omitted (reads filesystem).
- */
-export default function resolveSkillSources(
-  packages?: readonly SemanticPackage[],
-): SkillSource[] {
-  if (packages) {
-    return extractSkillSources(packages);
-  }
-
-  // Fallback: resolve packages ourselves (skills need filesystem paths,
-  // so we skip the bundled loader here)
-  return resolveSkillSourcesFromRefs();
-}
-
-function extractSkillSources(
-  packages: readonly SemanticPackage[],
-): SkillSource[] {
-  const sources: SkillSource[] = [];
-  for (const pkg of packages) {
-    for (const skill of pkg.skills) {
-      sources.push({ dir: skill.dir, packageName: pkg.name });
-    }
-  }
-  return sources;
-}
-
-function resolveSkillSourcesFromRefs(): SkillSource[] {
-  const refs = DEFAULT_PACKAGES.map(parsePackageEntry);
-  const loaders = [createLocalLoader(), createGitLoader()];
-
-  // resolveSemanticPackages is async but skills resolution is sync.
-  // Use local+git loaders which are both sync.
-  const packages: SemanticPackage[] = [];
-  for (const ref of refs) {
-    for (const loader of loaders) {
-      const resolved = loader.resolve(ref);
-      if (resolved && !(resolved instanceof Promise)) {
-        packages.push(resolved);
-        break;
-      }
-    }
-  }
-
-  return extractSkillSources(packages);
-}