@canonical/pragma-cli 0.30.0 → 0.32.0

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);
-}

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);
-  });
-});