@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,72 @@
+/**
+ * Three-mode formatter factory for `pragma token lookup` output.
+ *
+ * - **plain** — terminal text showing token name, category, and optional
+ *   per-theme values when detailed.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON; omits values unless detailed.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { TokenDetailed } from "../../shared/types.js";
+
+/** Options controlling detail level for the token-lookup formatter. */
+export interface TokenLookupFormatterOptions {
+  readonly detailed: boolean;
+}
+
+/**
+ * Creates a three-mode formatter set for a single token, capturing the
+ * detail level in the closure so callers only pass the token data.
+ *
+ * @param options - detail-level options
+ * @returns plain/llm/json formatters for {@link TokenDetailed}
+ */
+export function createLookupFormatters(
+  options: TokenLookupFormatterOptions,
+): Formatters<TokenDetailed> {
+  const { detailed } = options;
+
+  return {
+    plain: (token) => {
+      const lines: string[] = [];
+      lines.push(token.name);
+      lines.push(`Category: ${token.category || "—"}`);
+
+      if (detailed && token.values.length > 0) {
+        lines.push("");
+        lines.push("Values:");
+        for (const v of token.values) {
+          lines.push(`  ${v.theme}: ${v.value}`);
+        }
+      }
+
+      return lines.join("\n");
+    },
+
+    llm: (token) => {
+      const lines: string[] = [];
+      lines.push(`## ${token.name}`);
+      lines.push(`Category: ${token.category || "—"}`);
+
+      if (detailed && token.values.length > 0) {
+        lines.push("");
+        lines.push("### Values");
+        for (const v of token.values) {
+          lines.push(`- ${v.theme}: \`${v.value}\``);
+        }
+      }
+
+      return lines.join("\n");
+    },
+
+    json: (token) => {
+      if (detailed) {
+        return JSON.stringify(token, null, 2);
+      }
+      const { values: _values, ...summary } = token;
+      return JSON.stringify(summary, null, 2);
+    },
+  };
+}

package/src/domains/token/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @module Token domain — CLI commands and operations.
+ *
+ * Commands: `pragma token list`, `pragma token lookup <name>`,
+ *           `pragma tokens add-config`.
+ * Operations: {@link lookupToken}, {@link listTokens}, {@link resolveAddConfig}.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import {
+  addConfigCommand,
+  listCommand,
+  lookupCommand,
+} from "./commands/index.js";
+
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx), lookupCommand(ctx), addConfigCommand()];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export type { AddConfigResult, TokenListFilters } from "./operations/index.js";
+export {
+  listTokens,
+  lookupToken,
+  resolveAddConfig,
+} from "./operations/index.js";
+export {
+  resolveTokenList,
+  resolveTokenLookup,
+  tokenEmptyError,
+} from "./orchestration/index.js";

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

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

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

@@ -0,0 +1,145 @@
+/**
+ * MCP tool specs for the token domain.
+ *
+ * Declarative definitions — no MCP imports. The adapter layer
+ * converts these into registered MCP tools via `registerFromSpec()`.
+ */
+
+import { writeFileSync } from "node:fs";
+import { PragmaError } from "#error";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import {
+  createLookupFormatters as createTokenLookupFmt,
+  listFormatters as tokenListFmt,
+} from "../formatters/index.js";
+import { resolveAddConfig } from "../operations/index.js";
+import {
+  resolveTokenList,
+  resolveTokenLookup,
+} from "../orchestration/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "token_list",
+    description:
+      "List all design tokens. Optionally filter by category (token type).",
+    params: {
+      category: {
+        type: "string",
+        description: "Filter by token type (e.g., Color, Dimension)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { category, condensed }) {
+      const resolution = await resolveTokenList(rt, {
+        category: category as string | undefined,
+      });
+
+      if (condensed) {
+        const text = tokenListFmt.llm([...resolution.items]);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return {
+        data: resolution.items,
+        meta: { count: resolution.items.length },
+      };
+    },
+  },
+
+  {
+    name: "token_lookup",
+    description:
+      "Get detailed information about one or more design tokens including theme values.",
+    params: {
+      names: {
+        type: "string[]",
+        description: "Token names or IRIs to look up (e.g. ['color.primary'])",
+        optional: false,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { names, condensed }) {
+      const contract = await resolveTokenLookup(rt.store, names as string[]);
+      const result = contract.result;
+
+      if (condensed) {
+        const fmt = createTokenLookupFmt({ detailed: true });
+        const textParts = result.results.map((token) => fmt.llm(token));
+
+        if (result.errors.length > 0) {
+          textParts.push(
+            [
+              "### Errors",
+              ...result.errors.map(
+                (error) => `- ${error.query}: ${error.message}`,
+              ),
+            ].join("\n"),
+          );
+        }
+
+        return {
+          condensed: true,
+          text: textParts.join("\n\n"),
+          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
+        };
+      }
+
+      return { data: result, meta: { count: result.results.length } };
+    },
+  },
+
+  {
+    name: "tokens_add_config",
+    description:
+      "Generate a tokens.config.mjs file for terrazzo token pipeline.",
+    params: {
+      force: {
+        type: "boolean",
+        description: "Overwrite existing config file",
+        optional: true,
+      },
+    },
+    readOnly: false,
+    async execute(rt, { force }) {
+      const result = resolveAddConfig(rt.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");
+
+      return {
+        data: {
+          configPath: result.configPath,
+          tokenSources: result.tokenSources,
+          installHint: result.installHint,
+        },
+      };
+    },
+  },
+] as const;
+
+export default specs;

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

@@ -0,0 +1,68 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import resolveAddConfig from "./add-config.js";
+
+describe("resolveAddConfig", () => {
+  it("returns correct config path", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      const result = resolveAddConfig(cwd);
+      expect(result.configPath).toBe(join(cwd, "tokens.config.mjs"));
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+
+  it("returns alreadyExists: false when file does not exist", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      const result = resolveAddConfig(cwd);
+      expect(result.alreadyExists).toBe(false);
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+
+  it("returns alreadyExists: true when file exists", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      writeFileSync(join(cwd, "tokens.config.mjs"), "// existing", "utf-8");
+      const result = resolveAddConfig(cwd);
+      expect(result.alreadyExists).toBe(true);
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+
+  it("config content contains defineConfig", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      const result = resolveAddConfig(cwd);
+      expect(result.configContent).toContain("defineConfig");
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+
+  it("token sources include ds-global path", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      const result = resolveAddConfig(cwd);
+      expect(result.tokenSources[0]).toContain("@canonical/ds-global");
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+
+  it("provides install hint for terrazzo-lsp", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-test-"));
+    try {
+      const result = resolveAddConfig(cwd);
+      expect(result.installHint).toContain("terrazzo-lsp");
+    } finally {
+      rmSync(cwd, { recursive: true });
+    }
+  });
+});

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

@@ -0,0 +1,61 @@
+/**
+ * Resolves the terrazzo tokens config content and target path.
+ *
+ * Performs filesystem checks and package-manager detection but does not
+ * write files itself -- the caller is responsible for writing.
+ *
+ * @note Impure
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { detectPackageManager, PM_COMMANDS } from "#package-manager";
+
+/** Result of resolving a tokens config, including content and write metadata. */
+export interface AddConfigResult {
+  readonly configPath: string;
+  readonly configContent: string;
+  readonly tokenSources: readonly string[];
+  readonly alreadyExists: boolean;
+  readonly installHint: string;
+}
+
+/**
+ * Resolve the tokens config to generate.
+ *
+ * Returns data only — the caller writes the file.
+ */
+export default function resolveAddConfig(cwd: string): AddConfigResult {
+  const configPath = resolve(cwd, "tokens.config.mjs");
+  const alreadyExists = existsSync(configPath);
+
+  const tokenSources = ["node_modules/@canonical/ds-global/tokens/**/*.json"];
+
+  const configContent = generateConfigContent(tokenSources);
+
+  const pm = detectPackageManager();
+  const installHint = `Recommended: ${PM_COMMANDS[pm].install("@canonical/terrazzo-lsp")}`;
+
+  return {
+    configPath,
+    configContent,
+    tokenSources,
+    alreadyExists,
+    installHint,
+  };
+}
+
+function generateConfigContent(sources: readonly string[]): string {
+  const sourcesStr = sources.map((s) => `    "${s}"`).join(",\n");
+  return `// tokens.config.mjs — generated by pragma tokens add-config
+import { defineConfig } from "@canonical/terrazzo";
+
+export default defineConfig({
+  tokens: [
+${sourcesStr},
+  ],
+  outDir: "./tokens/",
+  plugins: [],
+});
+`;
+}

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

@@ -0,0 +1,7 @@
+/** @module Re-exports token operations and types (`resolveAddConfig`, `getToken`, `listTokens`). */
+
+export type { AddConfigResult } from "./add-config.js";
+export { default as resolveAddConfig } from "./add-config.js";
+export type { TokenListFilters } from "./list.js";
+export { default as listTokens } from "./list.js";
+export { default as lookupToken } from "./lookup.js";

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

@@ -0,0 +1,50 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listTokens 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());
+
+describe("listTokens", () => {
+  it("returns all tokens", async () => {
+    const result = await listTokens(store);
+    const names = result.map((t) => t.name);
+    expect(names).toContain("color.primary");
+    expect(names).toContain("spacing.sm");
+  });
+
+  it("returns sorted by tokenId", async () => {
+    const result = await listTokens(store);
+    const names = result.map((t) => t.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+
+  it("filters by category", async () => {
+    const result = await listTokens(store, { category: "Color" });
+    const names = result.map((t) => t.name);
+    expect(names).toContain("color.primary");
+    expect(names).not.toContain("spacing.sm");
+  });
+
+  it("category filter is case-insensitive", async () => {
+    const result = await listTokens(store, { category: "color" });
+    const names = result.map((t) => t.name);
+    expect(names).toContain("color.primary");
+    expect(names).not.toContain("spacing.sm");
+  });
+
+  it("returns empty for non-matching category", async () => {
+    const result = await listTokens(store, { category: "nonexistent" });
+    expect(result).toEqual([]);
+  });
+});

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

@@ -0,0 +1,52 @@
+/**
+ * Lists all design tokens, optionally filtered by category (token type name).
+ *
+ * @param store - ke store to query
+ * @param filters - optional category filter
+ * @returns array of token summaries ordered by token ID, empty when none match
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { TokenSummary } from "../../shared/types.js";
+
+/** Optional filters for the token list operation. */
+export interface TokenListFilters {
+  readonly category?: string;
+}
+
+export default async function listTokens(
+  store: Store,
+  filters?: TokenListFilters,
+): Promise<TokenSummary[]> {
+  const categoryFilter = filters?.category
+    ? `FILTER(LCASE(?typeName) = LCASE(${escapeSparqlValue(filters.category)}))`
+    : "";
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?token ?tokenId ?typeName
+      WHERE {
+        ?token a ${P.ds}Token ;
+               ${P.ds}tokenId ?tokenId .
+        OPTIONAL {
+          ?token ${P.ds}tokenType ?type .
+          ?type ${P.rdfs}label ?typeName .
+        }
+        ${categoryFilter}
+      }
+      ORDER BY ?tokenId
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings.map((b) => ({
+    uri: (b.token ?? "") as URI,
+    name: b.tokenId ?? "",
+    category: b.typeName ?? "",
+  }));
+}

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

@@ -0,0 +1,42 @@
+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 lookupToken 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());
+
+describe("lookupToken", () => {
+  it("returns detailed data with theme values", async () => {
+    const result = await lookupToken(store, "color.primary");
+    expect(result.name).toBe("color.primary");
+    expect(result.values.length).toBe(2);
+
+    const light = result.values.find((v) => v.theme === "light");
+    expect(light?.value).toBe("#0066cc");
+
+    const dark = result.values.find((v) => v.theme === "dark");
+    expect(dark?.value).toBe("#4d9aff");
+  });
+
+  it("throws PragmaError.notFound for unknown token", async () => {
+    await expect(lookupToken(store, "nonexistent")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await lookupToken(store, "nonexistent");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+});

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

@@ -0,0 +1,66 @@
+/**
+ * Look up detailed information for a single design token by name.
+ *
+ * Queries the token URI, type, and per-theme values (light/dark).
+ *
+ * @param store - ke store to query
+ * @param name - token name (e.g. "color.primary")
+ * @returns full token detail including theme values
+ * @throws PragmaError.notFound if the token does not exist
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { TokenDetailed } from "../../shared/types.js";
+
+export default async function lookupToken(
+  store: Store,
+  name: string,
+): Promise<TokenDetailed> {
+  const escaped = escapeSparqlValue(name);
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?token ?typeName ?valueLight ?valueDark
+      WHERE {
+        ?token a ${P.ds}Token ;
+               ${P.ds}tokenId ${escaped} .
+        OPTIONAL {
+          ?token ${P.ds}tokenType ?type .
+          ?type ${P.rdfs}label ?typeName .
+        }
+        OPTIONAL { ?token ${P.ds}valueLight ?valueLight }
+        OPTIONAL { ?token ${P.ds}valueDark ?valueDark }
+      }
+      LIMIT 1
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("token", name, {
+      recovery: {
+        message: "List available tokens.",
+        cli: "pragma token list",
+        mcp: { tool: "token_list" },
+      },
+    });
+  }
+
+  // Safe: length check above guarantees bindings[0] exists
+  const b = result.bindings[0] as (typeof result.bindings)[number];
+
+  const values: { theme: string; value: string }[] = [];
+  if (b.valueLight) values.push({ theme: "light", value: b.valueLight });
+  if (b.valueDark) values.push({ theme: "dark", value: b.valueDark });
+
+  return {
+    uri: (b.token ?? "") as URI,
+    name,
+    category: b.typeName ?? "",
+    values,
+  };
+}

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

@@ -0,0 +1,3 @@
+export { default as resolveTokenList } from "./resolveTokenList.js";
+export { default as resolveTokenLookup } from "./resolveTokenLookup.js";
+export { default as tokenEmptyError } from "./tokenEmptyError.js";

package/src/domains/token/orchestration/resolveTokenList.ts

@@ -0,0 +1,17 @@
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import { listTokens } from "../operations/index.js";
+import type { TokenListResolution } from "../types.js";
+import tokenEmptyError from "./tokenEmptyError.js";
+
+export default async function resolveTokenList(
+  rt: Pick<PragmaRuntime, "store">,
+  params: { category?: string },
+): Promise<TokenListResolution> {
+  const items = await listTokens(rt.store, { category: params.category });
+
+  if (items.length === 0) {
+    throw tokenEmptyError(params.category);
+  }
+
+  return { params, items };
+}

package/src/domains/token/orchestration/resolveTokenLookup.ts

@@ -0,0 +1,20 @@
+import type { LookupContract, LookupResult } from "../../shared/contracts.js";
+import lookupMany from "../../shared/lookupMany.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { TokenDetailed } from "../../shared/types.js";
+import { lookupToken } from "../operations/index.js";
+
+export default async function resolveTokenLookup(
+  store: Pick<PragmaRuntime, "store">["store"],
+  queries: readonly string[],
+): Promise<LookupContract<TokenDetailed>> {
+  const result: LookupResult<TokenDetailed> = await lookupMany(
+    queries,
+    (query) => lookupToken(store, query),
+  );
+
+  return {
+    params: { names: queries },
+    result,
+  };
+}

package/src/domains/token/orchestration/tokenEmptyError.ts

@@ -0,0 +1,17 @@
+import { PragmaError } from "#error";
+
+export default function tokenEmptyError(category?: string): PragmaError {
+  return PragmaError.emptyResults("token", {
+    filters: category ? { category } : undefined,
+    recovery: category
+      ? {
+          message: "List all tokens without category filter.",
+          cli: "pragma token list",
+          mcp: { tool: "token_list" },
+        }
+      : {
+          message:
+            "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+        },
+  });
+}

package/src/domains/token/types.ts

@@ -0,0 +1,6 @@
+import type { TokenSummary } from "../shared/types.js";
+
+export interface TokenListResolution {
+  readonly params: { category?: string };
+  readonly items: readonly TokenSummary[];
+}