@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/domains/skill/stories.ts

@@ -1,103 +0,0 @@
-/**
- * Skill read stories — the single declaration of `skill list` and
- * `skill lookup` for both surfaces.
- *
- * `skill lookup` serves the full SKILL.md content, making skills directly
- * consumable by agents over MCP (previously only metadata was listed).
- */
-
-import { PragmaError } from "#error";
-import lookupMany from "../shared/lookupMany.js";
-import {
-  type LookupStory,
-  type ReadStory,
-  requirePragmaContext,
-} from "../shared/stories/index.js";
-import { listFormatters, lookupFormatters } from "./formatters/index.js";
-import type { SkillListInput } from "./formatters/types.js";
-import {
-  discoverSkills,
-  listSkills,
-  lookupSkill,
-  type SkillListResult,
-} from "./operations/index.js";
-import type { SkillDetailed } from "./types.js";
-
-/** The `skill list` / `skill_list` read story. */
-export const skillListStory: ReadStory<SkillListResult, SkillListInput> = {
-  noun: "skill",
-  verb: "list",
-  description: "List available agent skills from design system packages",
-  toolDescription: "List available agent skills from design system packages.",
-  params: [
-    {
-      name: "detailed",
-      type: "boolean",
-      description: "Show full metadata for each skill",
-      default: false,
-      surfaces: "cli",
-    },
-  ],
-  examples: [
-    "pragma skill list",
-    "pragma skill list --detailed",
-    "pragma skill list --llm",
-    "pragma skill list --format json",
-  ],
-  resolve: (rt) => listSkills(rt.cwd),
-  toOutput: ({ skills, sources }, params) => ({
-    skills,
-    sources,
-    detailed: params.detailed === true,
-  }),
-  formatters: listFormatters,
-  toEnvelope: ({ skills, sources }) => ({
-    data: { skills, sources },
-    meta: { count: skills.length },
-  }),
-  emptyError: ({ skills, sources }) => {
-    if (skills.length > 0) return undefined;
-    const allUnavailable = sources.every((source) => !source.available);
-    return PragmaError.emptyResults("skill", {
-      recovery: {
-        message: allUnavailable
-          ? "Install @canonical packages first"
-          : "No SKILL.md files found in source packages",
-      },
-    });
-  },
-};
-
-/** The `skill lookup` / `skill_lookup` read story. */
-export const skillLookupStory: LookupStory<SkillDetailed, SkillDetailed> = {
-  noun: "skill",
-  description: "Show full instructions for a skill by name",
-  toolDescription:
-    "Get full skill instructions (SKILL.md content) for one or more agent skills by name.",
-  namesDescription: "Skill names",
-  namesToolDescription: "Skill names to look up (e.g. ['design-auditor'])",
-  complete: async (partial, cmdCtx) => {
-    const ctx = requirePragmaContext(cmdCtx);
-    const skills = await discoverSkills(ctx.cwd);
-    return skills
-      .map((skill) => skill.name)
-      .filter((name) => name.toLowerCase().startsWith(partial.toLowerCase()));
-  },
-  examples: [
-    "pragma skill lookup design-auditor",
-    "pragma skill lookup design-auditor add-standard",
-    "pragma skill lookup design-auditor --llm",
-  ],
-  resolve: (rt, names) =>
-    lookupMany(names, (query) => lookupSkill(rt.cwd, query)),
-  toFmtInput: (skill) => skill,
-  formatters: lookupFormatters,
-  emptyNamesError: () =>
-    PragmaError.invalidInput("names", "(empty)", {
-      recovery: {
-        message: "List available skills.",
-        cli: "pragma skill list",
-        mcp: { tool: "skill_list" },
-      },
-    }),
-};

package/src/domains/skill/types.ts

@@ -1,33 +0,0 @@
-/** 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;
-}
-
-/** A discovered skill enriched with its full SKILL.md content and companion files. */
-export interface SkillDetailed extends DiscoveredSkill {
-  /** Full SKILL.md text, frontmatter included. */
-  readonly content: string;
-  /** Companion file names shipped next to SKILL.md (e.g. spec documents). */
-  readonly files: readonly string[];
-}

package/src/domains/token/commands/add-config.test.ts

@@ -1,68 +0,0 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { CommandContext } from "@canonical/cli-core";
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import addConfigCommand from "./add-config.js";
-
-function makeCtx(cwd: string): CommandContext {
-  return {
-    cwd,
-    globalFlags: {
-      llm: false,
-      format: "text",
-      verbose: false,
-    },
-  };
-}
-
-describe("tokens add-config command", () => {
-  it("writes config file to cwd", async () => {
-    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
-    try {
-      const cmd = addConfigCommand();
-      const result = await cmd.execute({}, makeCtx(cwd));
-      expect(result.tag).toBe("output");
-
-      const content = readFileSync(join(cwd, "tokens.config.mjs"), "utf-8");
-      expect(content).toContain("defineConfig");
-    } finally {
-      rmSync(cwd, { recursive: true });
-    }
-  });
-
-  it("throws INVALID_INPUT when file already exists", async () => {
-    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
-    try {
-      writeFileSync(join(cwd, "tokens.config.mjs"), "// existing", "utf-8");
-
-      const cmd = addConfigCommand();
-      try {
-        await cmd.execute({}, makeCtx(cwd));
-        expect.fail("Should have thrown");
-      } catch (e) {
-        expect(e).toBeInstanceOf(PragmaError);
-        expect((e as PragmaError).code).toBe("INVALID_INPUT");
-      }
-    } finally {
-      rmSync(cwd, { recursive: true });
-    }
-  });
-
-  it("overwrites with --force", async () => {
-    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
-    try {
-      writeFileSync(join(cwd, "tokens.config.mjs"), "// old", "utf-8");
-
-      const cmd = addConfigCommand();
-      await cmd.execute({ force: true }, makeCtx(cwd));
-
-      const content = readFileSync(join(cwd, "tokens.config.mjs"), "utf-8");
-      expect(content).toContain("defineConfig");
-      expect(content).not.toContain("// old");
-    } finally {
-      rmSync(cwd, { recursive: true });
-    }
-  });
-});

package/src/domains/token/commands/add-config.ts

@@ -1,62 +0,0 @@
-/**
- * Wires the `pragma tokens add-config` CLI command.
- *
- * Generates a `tokens.config.mjs` file for the terrazzo token pipeline.
- * Refuses to overwrite an existing config unless `--force` is passed.
- *
- * @note Impure
- */
-
-import { writeFileSync } from "node:fs";
-import {
-  type CommandContext,
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { resolveAddConfig } from "../operations/index.js";
-
-export default function addConfigCommand(): CommandDefinition {
-  return {
-    path: ["tokens", "add-config"],
-    description: "Generate a tokens.config.mjs for terrazzo",
-    parameters: [
-      {
-        name: "force",
-        description: "Overwrite existing config file",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: ["pragma tokens add-config"],
-    },
-    async execute(params: Record<string, unknown>, ctx: CommandContext) {
-      const force = (params.force as boolean) ?? false;
-      const result = resolveAddConfig(ctx.cwd);
-
-      if (result.alreadyExists && !force) {
-        throw PragmaError.invalidInput("tokens.config.mjs", "already exists", {
-          recovery: {
-            message: "Overwrite existing config file.",
-            cli: "pragma tokens add-config --force",
-            mcp: { tool: "tokens_add_config", params: { force: true } },
-          },
-        });
-      }
-
-      writeFileSync(result.configPath, result.configContent, "utf-8");
-
-      const lines: string[] = [];
-      lines.push(`Created ${result.configPath}`);
-      if (result.installHint) {
-        lines.push(result.installHint);
-      }
-      const message = lines.join("\n");
-
-      return createOutputResult(message, {
-        plain: () => message,
-      });
-    },
-  };
-}

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

@@ -1,6 +0,0 @@
-/** @module Re-exports token command builders (`addConfig`, `list`, `lookup`, `sample`). */
-
-export { default as addConfigCommand } from "./add-config.js";
-export { default as listCommand } from "./list.js";
-export { default as lookupCommand } from "./lookup.js";
-export { default as sampleCommand } from "./sample.js";

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

@@ -1,82 +0,0 @@
-import type { CommandOutputResult } 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 listCommand 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["globalFlags"]>,
-): PragmaContext {
-  return {
-    cwd: "/tmp",
-    store,
-    config: { tier: undefined, channel: "normal" },
-    globalFlags: {
-      llm: false,
-      format: "text",
-      verbose: false,
-      ...overrides,
-    },
-  };
-}
-
-describe("token list command", () => {
-  it("returns output result with all tokens", async () => {
-    const ctx = makeCtx();
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    expect(result.tag).toBe("output");
-
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("color.primary");
-    expect(text).toContain("spacing.sm");
-  });
-
-  it("filters by --category", async () => {
-    const ctx = makeCtx();
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({ category: "Color" }, ctx);
-    expect(result.tag).toBe("output");
-
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("color.primary");
-    expect(text).not.toContain("spacing.sm");
-  });
-
-  it("throws EMPTY_RESULTS for non-matching category", async () => {
-    const ctx = makeCtx();
-    const cmd = listCommand(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({ llm: true });
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("## Design Tokens");
-    expect(text).toContain("**color.primary**");
-  });
-});

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

@@ -1,54 +0,0 @@
-/**
- * Wires the `pragma token list` CLI command.
- *
- * Lists all design tokens with an optional `--category` filter.
- * Throws a structured recovery error when no tokens match.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { listFormatters } from "../formatters/index.js";
-import { resolveTokenList } from "../orchestration/index.js";
-import { tokenConfig } from "../tokenConfig.js";
-
-export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["token", "list"],
-    description: "List all design tokens",
-    parameters: [
-      {
-        name: "category",
-        description: "Filter by token type (e.g., Color, Dimension)",
-        type: "string",
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma token list",
-        "pragma token list --category color",
-        "pragma token list --llm",
-      ],
-    },
-    async execute(params: Record<string, unknown>) {
-      const resolution = await resolveTokenList(ctx, {
-        category: params.category as string | undefined,
-      });
-
-      return createOutputResult([...resolution.items], {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Tokens",
-            domain: "token",
-            items: data,
-            columns: tokenConfig.listColumns,
-          }),
-      });
-    },
-  };
-}

package/src/domains/token/commands/lookup.test.ts

@@ -1,133 +0,0 @@
-import type { CommandOutputResult } 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 lookupCommand from "./lookup.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["globalFlags"]>,
-): PragmaContext {
-  return {
-    cwd: "/tmp",
-    store,
-    config: { tier: undefined, channel: "normal" },
-    globalFlags: {
-      llm: false,
-      format: "text",
-      verbose: false,
-      ...overrides,
-    },
-  };
-}
-
-describe("token lookup command", () => {
-  it("returns summary by default", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["color.primary"] }, ctx);
-    expect(result.tag).toBe("output");
-
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("color.primary");
-    expect(text).toContain("Category: Color");
-    expect(text).not.toContain("Values:");
-  });
-
-  it("returns values with --detailed", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute(
-      { names: ["color.primary"], detailed: true },
-      ctx,
-    );
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("Values:");
-    expect(text).toContain("light: #0066cc");
-    expect(text).toContain("dark: #4d9aff");
-  });
-
-  it("throws ENTITY_NOT_FOUND for unknown token", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["nonexistent"] }, ctx);
-    expect(result.tag).toBe("output");
-    if (result.tag !== "output") {
-      expect.fail("Expected output result");
-    }
-    expect(result.render.plain(result.value)).toContain("Errors:");
-  });
-
-  it("renders LLM format with --llm --detailed", async () => {
-    const ctx = makeCtx({ llm: true });
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute(
-      { names: ["color.primary"], detailed: true },
-      ctx,
-    );
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("## color.primary");
-    expect(text).toContain("### Values");
-  });
-
-  it("renders JSON with --detailed", async () => {
-    const ctx = makeCtx({ format: "json" });
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute(
-      { names: ["color.primary"], detailed: true },
-      ctx,
-    );
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("color.primary");
-    expect(parsed.values).toHaveLength(2);
-  });
-
-  it("renders JSON without --detailed (omits values)", async () => {
-    const ctx = makeCtx({ format: "json" });
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["color.primary"] }, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("color.primary");
-    expect(parsed.values).toBeUndefined();
-  });
-
-  it("renders multiple tokens together", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute(
-      { names: ["color.primary", "spacing.sm"] },
-      ctx,
-    );
-    expect(result.tag).toBe("output");
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("color.primary");
-    expect(text).toContain("spacing.sm");
-  });
-
-  it("rejects an empty names list with INVALID_INPUT", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    await expect(cmd.execute({ names: [] }, ctx)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-    });
-  });
-});

package/src/domains/token/commands/lookup.ts

@@ -1,107 +0,0 @@
-/**
- * Wires the `pragma token lookup <name...>` CLI command.
- *
- * Retrieves detailed information for a single design token, including
- * per-theme values when `--detailed` is passed.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
-import { PragmaError } from "../../../error/index.js";
-import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import resolveLookupExitCode from "../../shared/resolveLookupExitCode.js";
-import {
-  createLookupFormatters,
-  createTokenInkLookupOptions,
-} from "../formatters/index.js";
-import type { lookupToken } from "../operations/index.js";
-import { resolveTokenLookup } from "../orchestration/index.js";
-
-interface TokenLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupToken>>>;
-  readonly detailed: boolean;
-}
-
-export default function buildLookupCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return {
-    path: ["token", "lookup"],
-    description: "Look up detailed information for a design token",
-    parameters: [
-      {
-        name: "names",
-        description: "Token names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-      {
-        name: "detailed",
-        description: "Include values per theme",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma token lookup color.primary",
-        "pragma token lookup color.primary spacing.sm",
-        "pragma token lookup color.primary --detailed",
-        "pragma token lookup color.primary --llm",
-      ],
-    },
-    async execute(params: Record<string, unknown>) {
-      const names = normalizeNames(params.names, params.name);
-      if (names.length === 0) {
-        throw PragmaError.invalidInput("names", "(empty)", {
-          recovery: {
-            message: "List available tokens.",
-            cli: "pragma token list",
-            mcp: { tool: "token_list" },
-          },
-        });
-      }
-      const detailed = (params.detailed as boolean) ?? false;
-      const contract = await resolveTokenLookup(ctx.store, names);
-
-      return createOutputResult<TokenLookupOutput>(
-        { result: contract.result, detailed },
-        {
-          plain: ({ result, detailed: isDetailed }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: createLookupFormatters({ detailed: isDetailed }),
-              mapResult: (token) => token,
-            }),
-          ink: ({ result, detailed: isDetailed }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "token",
-              options: createTokenInkLookupOptions({ detailed: isDetailed }),
-            }),
-        },
-        resolveLookupExitCode(contract.result),
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
-}