@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/llm/data/toolCatalog.ts

@@ -1,190 +0,0 @@
-/** Tool catalog with behavioral hints for agent orientation. */
-
-export interface ToolEntry {
-  readonly name: string;
-  readonly category: "read" | "write" | "orientation" | "diagnostic";
-  readonly use_when: string;
-}
-
-/** All registered MCP tools with category and behavioral guidance. */
-export const TOOL_CATALOG: readonly ToolEntry[] = [
-  // — Read ————————————————————————————————————————————————————————————————————
-  {
-    name: "block_list",
-    category: "read",
-    use_when:
-      "Browsing available components, patterns, layouts under current tier/channel",
-  },
-  {
-    name: "block_lookup",
-    category: "read",
-    use_when:
-      "Need full anatomy, modifiers, tokens, and standards for specific blocks by name or IRI",
-  },
-  {
-    name: "standard_list",
-    category: "read",
-    use_when:
-      "Browsing code standards, optionally filtered by category or search term",
-  },
-  {
-    name: "standard_lookup",
-    category: "read",
-    use_when:
-      "Need do/don't code examples for specific coding standards by name or IRI",
-  },
-  {
-    name: "standard_categories",
-    category: "read",
-    use_when: "Discovering which standard categories exist before filtering",
-  },
-  {
-    name: "modifier_list",
-    category: "read",
-    use_when: "Listing all modifier families and their allowed values",
-  },
-  {
-    name: "modifier_lookup",
-    category: "read",
-    use_when:
-      "Need values and usage details for specific modifier families by name",
-  },
-  {
-    name: "token_list",
-    category: "read",
-    use_when:
-      "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
-  },
-  {
-    name: "token_lookup",
-    category: "read",
-    use_when:
-      "Need theme values and resolution details for specific tokens by name or IRI",
-  },
-  {
-    name: "tier_list",
-    category: "read",
-    use_when: "Understanding the tier hierarchy before setting a tier filter",
-  },
-  {
-    name: "config_show",
-    category: "read",
-    use_when: "Checking active tier and channel before querying",
-  },
-  {
-    name: "ontology_list",
-    category: "read",
-    use_when:
-      "Discovering loaded namespaces, prefixes, and class/property counts",
-  },
-  {
-    name: "ontology_show",
-    category: "read",
-    use_when:
-      "Exploring the full schema of a namespace — classes, properties, and hierarchy",
-  },
-  {
-    name: "graph_query",
-    category: "read",
-    use_when:
-      "Complex SPARQL joins or aggregations that other tools cannot express",
-  },
-  {
-    name: "graph_inspect",
-    category: "read",
-    use_when:
-      "Examining all triples for a specific URI — predicates, objects, and types",
-  },
-  {
-    name: "skill_list",
-    category: "read",
-    use_when: "Discovering agent skills provided by installed packages",
-  },
-  {
-    name: "skill_lookup",
-    category: "read",
-    use_when:
-      "Loading full SKILL.md instructions for a specific agent skill by name",
-  },
-  {
-    name: "block_sample",
-    category: "read",
-    use_when:
-      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
-  },
-  {
-    name: "standard_sample",
-    category: "read",
-    use_when:
-      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
-  },
-  {
-    name: "token_sample",
-    category: "read",
-    use_when:
-      "See actual token data shapes (with theme values) before querying — returns random instances each call",
-  },
-  {
-    name: "modifier_sample",
-    category: "read",
-    use_when:
-      "See actual modifier data shapes (with value lists) before querying — returns random instances each call",
-  },
-
-  // — Write ———————————————————————————————————————————————————————————————————
-  {
-    name: "config_tier",
-    category: "write",
-    use_when: "Setting or resetting the active tier filter",
-  },
-  {
-    name: "config_channel",
-    category: "write",
-    use_when:
-      "Setting the release channel (normal, experimental, or prerelease)",
-  },
-  {
-    name: "tokens_add_config",
-    category: "write",
-    use_when: "Generating a tokens.config.mjs for the terrazzo token pipeline",
-  },
-  {
-    name: "create_component",
-    category: "write",
-    use_when:
-      "Scaffolding a new design system component (React, Svelte, or Lit)",
-  },
-  {
-    name: "create_package",
-    category: "write",
-    use_when:
-      "Scaffolding a new npm package with proper monorepo configuration",
-  },
-
-  // — Orientation —————————————————————————————————————————————————————————————
-  {
-    name: "llm",
-    category: "orientation",
-    use_when:
-      "Need live context, decision trees, and command reference for design system work",
-  },
-  {
-    name: "capabilities",
-    category: "orientation",
-    use_when:
-      "Starting a session — understand conventions, available tools, and discovery flow",
-  },
-
-  // — Diagnostic ——————————————————————————————————————————————————————————————
-  {
-    name: "doctor",
-    category: "diagnostic",
-    use_when:
-      "Diagnosing environment issues — config, store, completions, MCP health",
-  },
-  {
-    name: "info",
-    category: "diagnostic",
-    use_when: "Checking pragma version, configuration summary, and store state",
-  },
-];

package/src/domains/llm/formatters/capabilities.ts

@@ -1,50 +0,0 @@
-import type { CapabilitiesData } from "../types.js";
-
-/**
- * Render capabilities data as compact terminal text.
- *
- * @param data - The structured capabilities payload.
- * @returns Plain text for terminal output.
- */
-export default function renderCapabilities(data: CapabilitiesData): string {
-  const lines: string[] = [];
-
-  lines.push(`pragma v${data.version}`);
-  lines.push("");
-
-  // — Conventions
-  lines.push("Conventions");
-  lines.push(`  ${data.conventions.system}`);
-  lines.push(`  ${data.conventions.model}`);
-  lines.push(`  ${data.conventions.querying}`);
-  lines.push("");
-
-  // — Discovery sequence
-  lines.push("Discovery Sequence");
-  for (const stage of data.discovery_sequence) {
-    lines.push(`  ${stage.stage}. ${stage.tool} — ${stage.purpose}`);
-  }
-  lines.push("");
-
-  // — Tools by category
-  const categories = ["read", "write", "orientation", "diagnostic"] as const;
-  for (const cat of categories) {
-    const tools = data.tools.filter((t) => t.category === cat);
-    lines.push(`${cat} (${tools.length})`);
-    for (const tool of tools) {
-      lines.push(`  ${tool.name} — ${tool.use_when}`);
-    }
-    lines.push("");
-  }
-
-  // — Counts + limits
-  const { counts } = data;
-  lines.push(
-    `${counts.total} tools: ${counts.read} read, ${counts.write} write, ${counts.orientation} orientation, ${counts.diagnostic} diagnostic`,
-  );
-  lines.push(
-    `output: ${data.limits.output_modes.join(", ")} | condensed: ${data.limits.condensed_available ? "yes" : "no"}`,
-  );
-
-  return lines.join("\n");
-}

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

@@ -1,4 +0,0 @@
-/** @module Barrel for llm formatters. */
-
-export { default as renderCapabilities } from "./capabilities.js";
-export { default as renderLlmOrientation } from "./orientation.js";

package/src/domains/llm/formatters/orientation.ts

@@ -1,53 +0,0 @@
-import type { LlmData } from "../types.js";
-
-/**
- * Renders the `pragma llm` orientation document.
- *
- * Produces a single condensed Markdown output (budget: <=800 tokens) containing
- * context summary, decision trees, and a command reference table.
- *
- * @param data - The assembled LLM orientation data.
- * @returns A Markdown string for LLM context injection.
- */
-export default function renderLlmOrientation(data: LlmData): string {
-  const lines: string[] = [];
-
-  // --- Context block ---
-  const { context: ctx } = data;
-  const tierDisplay = ctx.tier
-    ? `${ctx.tier} (${ctx.tierChain.join(" → ")})`
-    : "(none)";
-
-  lines.push("# Pragma — Design System CLI");
-  lines.push("");
-  lines.push("## Context");
-  lines.push(`tier: ${tierDisplay} | channel: ${ctx.channel}`);
-  lines.push(
-    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families, ${ctx.counts.tokens} tokens`,
-  );
-  lines.push(`namespaces: ${ctx.namespaces.join(", ")}`);
-  lines.push("");
-
-  // --- Decision trees ---
-  lines.push("## Decision Trees");
-  lines.push("");
-  for (const tree of data.decisionTrees) {
-    lines.push(`### ${tree.intent}`);
-    lines.push("```");
-    lines.push(tree.tree);
-    lines.push("```");
-    lines.push("");
-  }
-
-  // --- Command reference ---
-  lines.push("## Commands");
-  lines.push("| Command | Tokens |");
-  lines.push("|---|---|");
-  for (const ref of data.commandReference) {
-    lines.push(`| \`${ref.command}\` | ${ref.tokens} |`);
-  }
-  lines.push("");
-  lines.push("Append `--llm` to all commands for token-optimized output.");
-
-  return lines.join("\n");
-}

package/src/domains/llm/index.ts

@@ -1,9 +0,0 @@
-/**
- * @module LLM domain barrel.
- *
- * Provides the `pragma capabilities` and `pragma llm` commands
- * for LLM orientation context generation.
- */
-
-export { buildCapabilitiesCommand, buildLlmCommand } from "./commands/index.js";
-export { specs as mcpSpecs } from "./mcp/index.js";

package/src/domains/llm/llmCommand.test.ts

@@ -1,93 +0,0 @@
-import type { CommandDefinition } 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 { buildLlmCommand } from "./commands/index.js";
-import type { LlmData } from "./types.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> = {}): PragmaContext {
-  return {
-    cwd: "/tmp",
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    store,
-    config: { tier: undefined, channel: "prerelease" },
-    ...overrides,
-  };
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  ctx: PragmaContext,
-): Promise<{ value: LlmData; text: string }> {
-  const result = await cmd.execute({}, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  const text = result.render.plain(result.value);
-  return { value: result.value as LlmData, text };
-}
-
-describe("buildLlmCommand", () => {
-  it("returns an output result", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLlmCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    expect(result.tag).toBe("output");
-  });
-
-  it("output contains all three sections", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLlmCommand(ctx);
-    const { text } = await executeOutput(cmd, ctx);
-    expect(text).toContain("## Context");
-    expect(text).toContain("## Decision Trees");
-    expect(text).toContain("## Commands");
-  });
-
-  it("context block reflects store state", async () => {
-    const ctx = makeCtx({
-      config: { tier: "apps/lxd", channel: "normal" },
-    });
-    const cmd = buildLlmCommand(ctx);
-    const { text, value } = await executeOutput(cmd, ctx);
-
-    expect(text).toContain("apps/lxd");
-    expect(text).toContain("normal");
-    expect(value.context.tierChain).toEqual(["global", "apps", "apps/lxd"]);
-    expect(value.context.counts.blocks).toBeGreaterThan(0);
-    expect(value.context.counts.standards).toBeGreaterThan(0);
-    expect(value.context.counts.modifierFamilies).toBeGreaterThan(0);
-    expect(value.context.counts.tokens).toBeGreaterThan(0);
-    expect(value.context.namespaces.length).toBeGreaterThan(0);
-  });
-
-  it("includes all 5 decision trees", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLlmCommand(ctx);
-    const { value, text } = await executeOutput(cmd, ctx);
-    expect(value.decisionTrees).toHaveLength(5);
-    expect(text).toContain("Build a block");
-    expect(text).toContain("Audit standards");
-    expect(text).toContain("Find a token");
-    expect(text).toContain("Explore the design system");
-    expect(text).toContain("Configure");
-  });
-
-  it("output stays within 800-token budget (≤3200 chars)", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLlmCommand(ctx);
-    const { text } = await executeOutput(cmd, ctx);
-    expect(text.length).toBeLessThanOrEqual(3200);
-  });
-});

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

@@ -1,2 +0,0 @@
-/** @module LLM domain MCP barrel — capabilities, llm. */
-export { buildCapabilitiesData, default as specs } from "./specs.js";

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

@@ -1,94 +0,0 @@
-/**
- * MCP tool specs for llm domain — capabilities, llm.
- */
-
-import { VERSION } from "#constants";
-import { buildFilterConfig } from "../../shared/filters/index.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import {
-  COMMAND_REFERENCE,
-  DECISION_TREES,
-  TOOL_CATALOG,
-} from "../data/index.js";
-import { collectContext } from "../operations/index.js";
-import type { CapabilitiesData, LlmData } from "../types.js";
-
-/** Build the static capabilities response. */
-function buildCapabilitiesData(): CapabilitiesData {
-  const counts = {
-    total: TOOL_CATALOG.length,
-    read: TOOL_CATALOG.filter((t) => t.category === "read").length,
-    write: TOOL_CATALOG.filter((t) => t.category === "write").length,
-    orientation: TOOL_CATALOG.filter((t) => t.category === "orientation")
-      .length,
-    diagnostic: TOOL_CATALOG.filter((t) => t.category === "diagnostic").length,
-  };
-
-  return {
-    version: VERSION,
-    conventions: {
-      system:
-        "Pragma is a CLI and MCP server for querying a design system knowledge graph — blocks, tokens, modifiers, standards, and ontologies.",
-      model:
-        "Data is scoped by tier (hierarchical, e.g. global > apps > apps/lxd) and channel (normal, experimental, prerelease). Set these via config_tier and config_channel.",
-      querying:
-        "All queries run against an RDF triple store. Prefixed IRIs (e.g. ds:global.component.button) identify entities. Use ontology_list to discover namespaces.",
-    },
-    discovery_sequence: [
-      {
-        stage: 1,
-        tool: "capabilities",
-        purpose: "Understand conventions, available tools, and how to navigate",
-      },
-      {
-        stage: 2,
-        tool: "*_sample",
-        purpose:
-          "Call block_sample, standard_sample, token_sample, or modifier_sample to see real data shapes before querying. Prevents guessing at property names.",
-      },
-      {
-        stage: 3,
-        tool: "domain tools",
-        purpose:
-          "Query specific entities — block_list, standard_lookup, token_list, etc. Use the use_when hints above to pick the right tool.",
-      },
-    ],
-    tools: TOOL_CATALOG,
-    counts,
-    limits: {
-      output_modes: ["text", "json", "llm"],
-      condensed_available: true,
-    },
-  };
-}
-
-const specs: readonly ToolSpec[] = [
-  {
-    name: "capabilities",
-    description:
-      "Discover pragma conventions, available tools with behavioral hints, and discovery sequence. Call this first at session start.",
-    readOnly: true,
-    async execute() {
-      return { data: buildCapabilitiesData() };
-    },
-  },
-  {
-    name: "llm",
-    description:
-      "Get live LLM orientation — context snapshot (tier, channel, entity counts), decision trees for common intents, and command reference with token costs. Call after capabilities when starting design system work.",
-    readOnly: true,
-    async execute(rt) {
-      const filters = buildFilterConfig(rt);
-      const context = await collectContext(rt.store, filters);
-      const data: LlmData = {
-        context,
-        decisionTrees: DECISION_TREES,
-        commandReference: COMMAND_REFERENCE,
-      };
-      return { data };
-    },
-  },
-];
-
-export { buildCapabilitiesData };
-export default specs;

package/src/domains/llm/operations/collectContext.ts

@@ -1,47 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { listBlocks } from "../../block/operations/index.js";
-import { listModifiers } from "../../modifier/operations/index.js";
-import { listOntologies } from "../../ontology/operations/index.js";
-import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import type { FilterConfig } from "../../shared/types/index.js";
-import { listStandards } from "../../standard/operations/index.js";
-import { listTokens } from "../../token/operations/index.js";
-import type { LlmContext } from "../types.js";
-
-/**
- * Collects dynamic context for the `pragma llm` orientation output.
- *
- * Queries the store in parallel for block, standard, modifier, token, and
- * ontology counts, and combines them with tier/channel config state.
- *
- * @note Queries ke store
- *
- * @param store - The ke store to query.
- * @param config - Filter config providing tier and channel settings.
- * @returns An {@link LlmContext} with entity counts and namespace list.
- */
-export default async function collectContext(
-  store: Store,
-  config: FilterConfig,
-): Promise<LlmContext> {
-  const [blocks, standards, modifiers, tokens, ontologies] = await Promise.all([
-    listBlocks(store, config),
-    listStandards(store),
-    listModifiers(store),
-    listTokens(store),
-    listOntologies(store),
-  ]);
-
-  return {
-    tier: config.tier,
-    tierChain: resolveTierChain(config.tier),
-    channel: config.channel,
-    counts: {
-      blocks: blocks.length,
-      standards: standards.length,
-      modifierFamilies: modifiers.length,
-      tokens: tokens.length,
-    },
-    namespaces: ontologies.map((o) => o.prefix),
-  };
-}

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

@@ -1,3 +0,0 @@
-/** @module Barrel for llm operations. */
-
-export { default as collectContext } from "./collectContext.js";

package/src/domains/llm/types.ts

@@ -1,72 +0,0 @@
-import type { ToolEntry } from "./data/toolCatalog.js";
-
-// — Capabilities ——————————————————————————————————————————————————————————————
-
-/** Structured system map returned by `pragma capabilities`. */
-export interface CapabilitiesData {
-  readonly version: string;
-  readonly conventions: {
-    readonly system: string;
-    readonly model: string;
-    readonly querying: string;
-  };
-  readonly discovery_sequence: readonly DiscoveryStage[];
-  readonly tools: readonly ToolEntry[];
-  readonly counts: ToolCounts;
-  readonly limits: {
-    readonly output_modes: readonly string[];
-    readonly condensed_available: boolean;
-  };
-}
-
-/** A single stage in the discovery flow. */
-export interface DiscoveryStage {
-  readonly stage: number;
-  readonly tool: string;
-  readonly purpose: string;
-}
-
-/** Tool counts by category. */
-export interface ToolCounts {
-  readonly total: number;
-  readonly read: number;
-  readonly write: number;
-  readonly orientation: number;
-  readonly diagnostic: number;
-}
-
-// — LLM orientation ———————————————————————————————————————————————————————————
-
-/** Dynamic context snapshot: tier, channel, entity counts, and namespaces. */
-export interface LlmContext {
-  readonly tier: string | undefined;
-  readonly tierChain: readonly string[];
-  readonly channel: string;
-  readonly counts: {
-    readonly blocks: number;
-    readonly standards: number;
-    readonly modifierFamilies: number;
-    readonly tokens: number;
-  };
-  readonly namespaces: readonly string[];
-}
-
-/** A single intent-to-flowchart mapping used in LLM orientation output. */
-export interface DecisionTree {
-  readonly intent: string;
-  readonly tree: string;
-}
-
-/** A command name paired with its approximate output token cost. */
-export interface CommandRefEntry {
-  readonly command: string;
-  readonly tokens: string;
-  readonly use_when: string;
-}
-
-/** Complete payload rendered by `pragma llm`: context, trees, and reference. */
-export interface LlmData {
-  readonly context: LlmContext;
-  readonly decisionTrees: readonly DecisionTree[];
-  readonly commandReference: readonly CommandRefEntry[];
-}

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

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

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

@@ -1,57 +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 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("modifier list command", () => {
-  it("returns output result with all families", 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("importance");
-    expect(text).toContain("density");
-  });
-
-  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("## Modifier Families");
-    expect(text).toContain("**importance**");
-  });
-});