@canonical/pragma-cli 0.31.0 → 0.32.0

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

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

@@ -1,8 +0,0 @@
-/** @module Re-exports token operations and types (`resolveAddConfig`, `listTokens`, `lookupToken`, `sampleTokens`). */
-
-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";
-export { default as sampleTokens } from "./sample.js";

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

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

@@ -1,52 +0,0 @@
-/**
- * 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/index.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

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

@@ -1,75 +0,0 @@
-/**
- * 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 {
-  detectCrossDomain,
-  listDomainNames,
-  suggestNames,
-} from "../../shared/suggestions/index.js";
-import type { TokenDetailed } from "../../shared/types/index.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) {
-    const candidates = await listDomainNames(store, "token");
-    const crossDomain = await detectCrossDomain(name, "token", store);
-    throw PragmaError.notFound("token", name, {
-      suggestions: suggestNames(name, candidates),
-      recovery: {
-        message: "List available tokens.",
-        cli: "pragma token list",
-        mcp: { tool: "token_list" },
-      },
-      crossDomain: crossDomain ?? undefined,
-    });
-  }
-
-  // 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/operations/sample.ts

@@ -1,32 +0,0 @@
-/**
- * Returns a small number of complete token instances as exemplars.
- *
- * Composes the existing list and lookup operations to avoid duplicating
- * any SPARQL logic. Agents use this to learn the data shape before querying.
- *
- * @param store - ke store to query
- * @param count - number of samples (clamped 1–5, default 2)
- * @returns sample result with detailed tokens and total count
- * @note Queries ke store
- */
-
-import type { Store } from "@canonical/ke";
-import pickRandom from "../../shared/pickRandom.js";
-import type { SampleResult, TokenDetailed } from "../../shared/types/index.js";
-import listTokens from "./list.js";
-import lookupToken from "./lookup.js";
-
-export default async function sampleTokens(
-  store: Store,
-  count = 2,
-): Promise<SampleResult<TokenDetailed>> {
-  const clamped = Math.max(1, Math.min(5, count));
-  const all = await listTokens(store);
-  const selected = pickRandom(all, clamped);
-
-  const samples = await Promise.all(
-    selected.map((t) => lookupToken(store, t.name)),
-  );
-
-  return { samples, totalCount: all.length };
-}

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

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

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

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

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

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import tokenEmptyError from "./tokenEmptyError.js";
-
-describe("tokenEmptyError", () => {
-  it("filter-narrowing: a category was active → clear it and re-list", () => {
-    const err = tokenEmptyError("color");
-
-    expect(err.filters).toEqual({ category: "color" });
-    expect(err.recovery).toEqual({
-      message: "List all tokens without category filter.",
-      cli: "pragma token list",
-      mcp: { tool: "token_list" },
-    });
-  });
-
-  it("store-empty: no category active → runnable install, no mcp retry", () => {
-    const err = tokenEmptyError();
-
-    expect(err.filters).toBeUndefined();
-    expect(err.recovery).toEqual({
-      message: "Install the design system packages that provide tokens.",
-      cli: "bun add -D @canonical/design-system",
-    });
-    // No mcp: re-calling token_list on an absent store returns empty again.
-    expect(err.recovery?.mcp).toBeUndefined();
-  });
-
-  it("install branch cites a real default package, not @canonical/ds-global", () => {
-    const err = tokenEmptyError();
-    expect(err.recovery?.cli).toContain("@canonical/design-system");
-    expect(err.recovery?.cli).not.toContain("ds-global");
-  });
-});

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

@@ -1,20 +0,0 @@
-import { PragmaError } from "#error";
-
-export default function tokenEmptyError(category?: string): PragmaError {
-  return PragmaError.emptyResults("token", {
-    filters: category ? { category } : undefined,
-    recovery: category
-      ? {
-          // Filter-narrowing: a category was active — clear it and re-list.
-          message: "List all tokens without category filter.",
-          cli: "pragma token list",
-          mcp: { tool: "token_list" },
-        }
-      : {
-          // Store-empty: no category was active, so the token-supplying
-          // packages are absent. No mcp retry — re-listing returns empty.
-          message: "Install the design system packages that provide tokens.",
-          cli: "bun add -D @canonical/design-system",
-        },
-  });
-}

package/src/domains/token/tokenConfig.ts

@@ -1,38 +0,0 @@
-import type { EntityDisplayConfig } from "../shared/contracts.js";
-import { P } from "../shared/prefixes.js";
-import type {
-  FilterConfig,
-  TokenDetailed,
-  TokenDigest,
-  TokenSummary,
-} from "../shared/types/index.js";
-
-/** Display-contract configuration for design-token entities. */
-export const tokenConfig: EntityDisplayConfig<
-  TokenSummary,
-  TokenDigest,
-  TokenDetailed
-> = {
-  domain: "token",
-  entityName: "token",
-  rdfTypes: [`${P.ds}Token`],
-  listColumns: [
-    { key: "uri", label: "IRI" },
-    { key: "name", label: "Name" },
-    { key: "category", label: "Category" },
-  ],
-  digestColumns: [],
-  lookupSections: [
-    { key: "values", heading: "Values", kind: "table", showWhenEmpty: false },
-  ],
-  emptyRecovery: (_filters: FilterConfig) => ({
-    message: "List available tokens.",
-    cli: "pragma token list",
-    mcp: { tool: "token_list" },
-  }),
-  notFoundRecovery: (_query: string) => ({
-    message: "List available tokens.",
-    cli: "pragma token list",
-    mcp: { tool: "token_list" },
-  }),
-};

package/src/domains/token/types.ts

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

package/src/domains/trace/commands/clear.ts

@@ -1,71 +0,0 @@
-/**
- * Wires the `pragma trace clear` CLI command.
- *
- * Deletes all trace log files.
- */
-
-import { readdirSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { traceDir } from "../../refs/operations/paths.js";
-
-const clearCommand: CommandDefinition = {
-  path: ["trace", "clear"],
-  description: "Delete all trace log files",
-  parameters: [
-    {
-      name: "yes",
-      description: "Skip confirmation",
-      type: "boolean",
-      default: false,
-    },
-  ],
-  meta: {
-    examples: ["pragma trace clear", "pragma trace clear --yes"],
-  },
-  async execute(params) {
-    const dir = traceDir();
-
-    let entries: string[];
-    try {
-      entries = readdirSync(dir).filter((e) => e.endsWith(".ndjson"));
-    } catch {
-      return createOutputResult("No trace directory found.\n", {
-        plain: (s) => s,
-      });
-    }
-
-    if (entries.length === 0) {
-      return createOutputResult("No trace files to delete.\n", {
-        plain: (s) => s,
-      });
-    }
-
-    if (params.yes !== true) {
-      return createOutputResult(
-        `Would delete ${entries.length} trace file${entries.length !== 1 ? "s" : ""}. Pass --yes to confirm.\n`,
-        { plain: (s) => s },
-      );
-    }
-
-    let deleted = 0;
-    for (const entry of entries) {
-      try {
-        unlinkSync(join(dir, entry));
-        deleted++;
-      } catch {
-        // Skip files we can't delete
-      }
-    }
-
-    return createOutputResult(
-      `Deleted ${deleted} trace file${deleted !== 1 ? "s" : ""}.\n`,
-      { plain: (s) => s },
-    );
-  },
-};
-
-export default clearCommand;

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

@@ -1,5 +0,0 @@
-/** @module Re-exports trace command builders. */
-
-export { default as clearCommand } from "./clear.js";
-export { default as sessionsCommand } from "./sessions.js";
-export { default as showCommand } from "./show.js";

package/src/domains/trace/commands/resolveTraceLimit.test.ts

@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import { resolveTraceLimit } from "./show.js";
-
-describe("resolveTraceLimit", () => {
-  it("defaults to 50 when absent", () => {
-    expect(resolveTraceLimit(undefined)).toBe(50);
-    expect(resolveTraceLimit("")).toBe(50);
-  });
-
-  it("accepts a positive integer", () => {
-    expect(resolveTraceLimit("20")).toBe(20);
-    expect(resolveTraceLimit(" 5 ")).toBe(5);
-  });
-
-  it.each([
-    "notanumber",
-    "-5",
-    "0",
-    "3.5",
-    "1e1",
-    "0x5",
-  ])("rejects the non-positive-integer value %j", (value) => {
-    expect(() => resolveTraceLimit(value)).toThrowError(PragmaError);
-    try {
-      resolveTraceLimit(value);
-    } catch (error) {
-      expect((error as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-});

package/src/domains/trace/commands/sessions.ts

@@ -1,32 +0,0 @@
-/**
- * Wires the `pragma trace sessions` CLI command.
- *
- * Lists all available trace sessions with metadata.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { traceDir } from "../../refs/operations/paths.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { sessionsFormatters } from "../formatters/index.js";
-import { listSessions } from "../operations/index.js";
-
-const sessionsCommand: CommandDefinition = {
-  path: ["trace", "sessions"],
-  description: "List available trace sessions",
-  parameters: [],
-  meta: {
-    examples: ["pragma trace sessions"],
-  },
-  async execute(_params, ctx) {
-    const sessions = listSessions(traceDir());
-
-    return createOutputResult(sessions, {
-      plain: selectFormatter(ctx, sessionsFormatters),
-    });
-  },
-};
-
-export default sessionsCommand;