@canonical/pragma-cli 0.18.0

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

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

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

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

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

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

@@ -0,0 +1,45 @@
+/**
+ * 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 type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { listFormatters } from "../formatters/index.js";
+import { resolveTokenList } from "../orchestration/index.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),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,125 @@
+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");
+  });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * 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 type { PragmaContext } from "../../shared/context.js";
+import type { LookupResult } from "../../shared/contracts.js";
+import { createLookupFormatters } 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);
+      const detailed = (params.detailed as boolean) ?? false;
+      const contract = await resolveTokenLookup(ctx.store, names);
+
+      return createOutputResult<TokenLookupOutput>(
+        { result: contract.result, detailed },
+        { plain: renderTokenLookupOutput(ctx) },
+      );
+    },
+  };
+}
+
+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 [];
+}
+
+function renderTokenLookupOutput(
+  ctx: PragmaContext,
+): (data: TokenLookupOutput) => string {
+  return ({ result, detailed }) => {
+    const formatters = createLookupFormatters({ detailed });
+    const formatOne =
+      ctx.globalFlags.format === "json"
+        ? formatters.json
+        : ctx.globalFlags.llm
+          ? formatters.llm
+          : formatters.plain;
+
+    if (ctx.globalFlags.format === "json") {
+      if (result.results.length === 1 && result.errors.length === 0) {
+        const only = result.results[0];
+        return only
+          ? formatters.json(only)
+          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
+      }
+
+      return JSON.stringify(
+        {
+          results: result.results.map((token) =>
+            JSON.parse(formatters.json(token)),
+          ),
+          errors: result.errors,
+        },
+        null,
+        2,
+      );
+    }
+
+    const parts = result.results.map((token) => formatOne(token));
+    if (result.errors.length > 0) {
+      parts.push(
+        [
+          "Errors:",
+          ...result.errors.map((error) => `- ${error.query}: ${error.message}`),
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  };
+}

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

@@ -0,0 +1,4 @@
+/** @module Re-exports token formatters (`createLookupFormatters`, `listFormatters`). */
+
+export { default as listFormatters } from "./list.js";
+export { createLookupFormatters } from "./lookup.js";

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

@@ -0,0 +1,37 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { TokenSummary } from "../../shared/types.js";
+import formatters from "./list.js";
+
+const TOKENS: TokenSummary[] = [
+  {
+    uri: "http://example.com/t1" as URI,
+    name: "color.primary",
+    category: "Color",
+  },
+  {
+    uri: "http://example.com/t2" as URI,
+    name: "spacing.sm",
+    category: "Dimension",
+  },
+];
+
+describe("token list formatters", () => {
+  it("plain renders name with category in brackets", () => {
+    const text = formatters.plain(TOKENS);
+    expect(text).toContain("color.primary [Color]");
+    expect(text).toContain("spacing.sm [Dimension]");
+  });
+
+  it("plain omits brackets when category is empty", () => {
+    const text = formatters.plain([{ ...TOKENS[0], category: "" }]);
+    expect(text).not.toContain("[");
+  });
+
+  it("llm renders markdown heading and bold names", () => {
+    const text = formatters.llm(TOKENS);
+    expect(text).toContain("## Design Tokens");
+    expect(text).toContain("**color.primary**");
+    expect(text).toContain("**spacing.sm**");
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Three-mode formatter for `pragma token list` output.
+ *
+ * - **plain** — one line per token showing name and optional category.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON array for programmatic consumption.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { TokenSummary } from "../../shared/types.js";
+
+const formatters: Formatters<TokenSummary[]> = {
+  plain: (tokens) => {
+    const lines: string[] = [];
+    for (const t of tokens) {
+      const cat = t.category ? ` [${t.category}]` : "";
+      lines.push(`${t.name}${cat}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm: (tokens) => {
+    const lines: string[] = [];
+    lines.push("## Design Tokens");
+    lines.push("");
+    for (const t of tokens) {
+      const cat = t.category ? ` [${t.category}]` : "";
+      lines.push(`- **${t.name}**${cat}`);
+    }
+    return lines.join("\n");
+  },
+
+  json: (tokens) => JSON.stringify(tokens, null, 2),
+};
+
+export default formatters;

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

@@ -0,0 +1,61 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { TokenDetailed } from "../../shared/types.js";
+import { createLookupFormatters } from "./lookup.js";
+
+const DETAILED: TokenDetailed = {
+  uri: "http://example.com/t1" as URI,
+  name: "color.primary",
+  category: "Color",
+  values: [
+    { theme: "light", value: "#0066cc" },
+    { theme: "dark", value: "#4d9aff" },
+  ],
+};
+
+describe("token lookup formatters", () => {
+  describe("detailed: false", () => {
+    const fmt = createLookupFormatters({ detailed: false });
+
+    it("plain renders summary without values", () => {
+      const text = fmt.plain(DETAILED);
+      expect(text).toContain("color.primary");
+      expect(text).toContain("Category: Color");
+      expect(text).not.toContain("Values:");
+    });
+
+    it("json omits values", () => {
+      const parsed = JSON.parse(fmt.json(DETAILED));
+      expect(parsed.name).toBe("color.primary");
+      expect(parsed.values).toBeUndefined();
+    });
+  });
+
+  describe("detailed: true", () => {
+    const fmt = createLookupFormatters({ detailed: true });
+
+    it("plain renders values", () => {
+      const text = fmt.plain(DETAILED);
+      expect(text).toContain("Values:");
+      expect(text).toContain("  light: #0066cc");
+      expect(text).toContain("  dark: #4d9aff");
+    });
+
+    it("llm renders values section", () => {
+      const text = fmt.llm(DETAILED);
+      expect(text).toContain("### Values");
+      expect(text).toContain("- light: `#0066cc`");
+    });
+
+    it("json includes values", () => {
+      const parsed = JSON.parse(fmt.json(DETAILED));
+      expect(parsed.values).toHaveLength(2);
+    });
+  });
+
+  it("plain renders dash for empty category", () => {
+    const fmt = createLookupFormatters({ detailed: false });
+    const text = fmt.plain({ ...DETAILED, category: "" });
+    expect(text).toContain("Category: —");
+  });
+});