@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,95 +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 type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.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);
-      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 }),
-            }),
-        },
-      );
-    },
-  };
-}
-
-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 [];
-}

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

@@ -1,53 +0,0 @@
-/**
- * Wires the `pragma token sample` CLI command.
- *
- * Returns 1–5 complete token instances as exemplars so agents
- * can learn the data shape before writing queries.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import type { SampleOutput, TokenDetailed } from "../../shared/types/index.js";
-import { sampleFormatters } from "../formatters/index.js";
-import { sampleTokens } from "../operations/index.js";
-
-const NEXT_STEPS = [
-  "Use token_lookup to inspect specific tokens by name.",
-  "Use token_list to see all available tokens with filtering.",
-];
-
-export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["token", "sample"],
-    description:
-      "Return randomly selected complete token instances as exemplars for shape discovery",
-    parameters: [
-      {
-        name: "count",
-        type: "string",
-        description: "Number of samples to return (1–5, default 2)",
-        required: false,
-      },
-    ],
-    meta: {
-      examples: ["pragma token sample", "pragma token sample --count 3"],
-    },
-    async execute(params) {
-      const count = Number(params.count ?? 2);
-      const result = await sampleTokens(ctx.store, count);
-
-      const output: SampleOutput<TokenDetailed> = {
-        ...result,
-        nextSteps: NEXT_STEPS,
-      };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx, sampleFormatters),
-      });
-    },
-  };
-}

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

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

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

@@ -1,37 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type { TokenSummary } from "../../shared/types/index.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

@@ -1,24 +0,0 @@
-import type { Formatters } from "../../shared/formatters.js";
-import { renderListLlm } from "../../shared/renderers.js";
-import type { TokenSummary } from "../../shared/types/index.js";
-import { tokenConfig } from "../tokenConfig.js";
-
-/** Three-mode formatter for `pragma token list` output. */
-const formatters: Formatters<TokenSummary[]> = {
-  plain: (tokens) =>
-    tokens
-      .map((token) =>
-        token.category ? `${token.name} [${token.category}]` : token.name,
-      )
-      .join("\n"),
-
-  llm: (tokens) =>
-    renderListLlm(tokens, {
-      heading: "Design Tokens",
-      columns: tokenConfig.listColumns,
-    }),
-
-  json: (tokens) => JSON.stringify(tokens, null, 2),
-};
-
-export default formatters;

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

@@ -1,61 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type { TokenDetailed } from "../../shared/types/index.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: —");
-  });
-});

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

@@ -1,107 +0,0 @@
-import type { RenderLookupOptions } from "../../shared/contracts.js";
-import type { Formatters } from "../../shared/formatters.js";
-import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
-import type { TokenDetailed } from "../../shared/types/index.js";
-import { tokenConfig } from "../tokenConfig.js";
-
-/** Options controlling detail level for the token-lookup formatter. */
-interface TokenLookupFormatterOptions {
-  readonly detailed: boolean;
-}
-
-/**
- * Create a three-mode formatter set for a single token.
- *
- * Captures 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 default function createLookupFormatters(
-  options: TokenLookupFormatterOptions,
-): Formatters<TokenDetailed> {
-  const { detailed } = options;
-  const sections = detailed ? tokenConfig.lookupSections : [];
-
-  return {
-    plain: (token) =>
-      renderLookupPlain(token, {
-        title: (entry) => entry.name,
-        fields: [
-          { label: "URI", value: (entry) => entry.uri },
-          { label: "Category", value: (entry) => entry.category || "—" },
-        ],
-        sections,
-        sectionOverrides: {
-          values: {
-            plain: (entry) =>
-              entry.values.length > 0
-                ? entry.values
-                    .map((value) => `  ${value.theme}: ${value.value}`)
-                    .join("\n")
-                : null,
-            llm: (entry) =>
-              entry.values.length > 0
-                ? entry.values
-                    .map((value) => `- ${value.theme}: \`${value.value}\``)
-                    .join("\n")
-                : null,
-          },
-        },
-      }),
-
-    llm: (token) =>
-      renderLookupLlm(token, {
-        title: (entry) => entry.name,
-        fields: [
-          { label: "URI", value: (entry) => entry.uri },
-          { label: "Category", value: (entry) => entry.category || "—" },
-        ],
-        sections,
-        sectionOverrides: {
-          values: {
-            plain: (entry) =>
-              entry.values.length > 0
-                ? entry.values
-                    .map((value) => `  ${value.theme}: ${value.value}`)
-                    .join("\n")
-                : null,
-            llm: (entry) =>
-              entry.values.length > 0
-                ? entry.values
-                    .map((value) => `- ${value.theme}: \`${value.value}\``)
-                    .join("\n")
-                : null,
-          },
-        },
-      }),
-
-    json: (token) => {
-      if (detailed) {
-        return JSON.stringify(token, null, 2);
-      }
-      const { values: _values, ...summary } = token;
-      return JSON.stringify(summary, null, 2);
-    },
-  };
-}
-
-/**
- * Build lookup rendering options for the Ink TUI view.
- *
- * @param options - detail-level options
- * @returns Options compatible with the LookupView component.
- */
-export function createInkLookupOptions(
-  options: TokenLookupFormatterOptions,
-): RenderLookupOptions<TokenDetailed> {
-  const sections = options.detailed ? tokenConfig.lookupSections : [];
-  return {
-    title: (entry) => entry.name,
-    fields: [
-      { label: "URI", value: (entry) => entry.uri },
-      { label: "Category", value: (entry) => entry.category || "—" },
-    ],
-    sections,
-  };
-}

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

@@ -1,16 +0,0 @@
-/**
- * Sample formatter for the token domain.
- *
- * Delegates to the shared factory, rendering each item via the
- * existing token lookup formatter with full detail.
- */
-
-import createSampleFormatters from "../../shared/sampleFormatters.js";
-import type { TokenDetailed } from "../../shared/types/index.js";
-import createLookupFormatters from "./lookup.js";
-
-const lookupFmt = createLookupFormatters({ detailed: true });
-
-export default createSampleFormatters<TokenDetailed>("tokens", (token, mode) =>
-  lookupFmt[mode](token),
-);

package/src/domains/token/index.ts

@@ -1,40 +0,0 @@
-/**
- * @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,
-  sampleCommand,
-} from "./commands/index.js";
-
-export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [
-    listCommand(ctx),
-    lookupCommand(ctx),
-    addConfigCommand(),
-    sampleCommand(ctx),
-  ];
-}
-
-export { specs as mcpSpecs } from "./mcp/index.js";
-export type { AddConfigResult, TokenListFilters } from "./operations/index.js";
-export {
-  listTokens,
-  lookupToken,
-  resolveAddConfig,
-  sampleTokens,
-} from "./operations/index.js";
-export {
-  resolveTokenList,
-  resolveTokenLookup,
-  tokenEmptyError,
-} from "./orchestration/index.js";
-export { tokenConfig } from "./tokenConfig.js";

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

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

@@ -1,195 +0,0 @@
-/**
- * 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 { lookupToolMeta } from "../../shared/lookupMany.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import {
-  createLookupFormatters as createTokenLookupFmt,
-  listFormatters as tokenListFmt,
-  sampleFormatters as tokenSampleFmt,
-} from "../formatters/index.js";
-import { resolveAddConfig, sampleTokens } 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: { results: result.results, errors: result.errors },
-        meta: lookupToolMeta(result),
-      };
-    },
-  },
-
-  {
-    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,
-        },
-      };
-    },
-  },
-  {
-    name: "token_sample",
-    description:
-      "Return 1–5 randomly selected complete token instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
-    params: {
-      count: {
-        type: "string",
-        description: "Number of samples (1–5, default 2)",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { count, condensed }) {
-      const n = Number(count ?? 2);
-      const result = await sampleTokens(rt.store, n);
-      const nextSteps = [
-        `These are ${result.samples.length} of ${result.totalCount} total tokens.`,
-        "Use token_lookup to inspect specific tokens by name.",
-        "Use token_list with category param to filter by type.",
-      ];
-
-      if (condensed) {
-        const text = tokenSampleFmt.llm({ ...result, nextSteps });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return {
-        data: {
-          samples: result.samples,
-          totalCount: result.totalCount,
-          nextSteps,
-        },
-        meta: { count: result.samples.length },
-      };
-    },
-  },
-] as const;
-
-export default specs;