@canonical/pragma-cli 0.31.0 → 0.32.0

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,57 +0,0 @@
-import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
-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}`);
-  const tokenCount = TOKEN_READ_SURFACE_ENABLED
-    ? `, ${ctx.counts.tokens} tokens`
-    : "";
-  lines.push(
-    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families${tokenCount}`,
-  );
-  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,101 +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 { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.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 decision trees", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLlmCommand(ctx);
-    const { value, text } = await executeOutput(cmd, ctx);
-    // "Find a token" is gated behind the token read-surface feature flag.
-    expect(value.decisionTrees).toHaveLength(
-      TOKEN_READ_SURFACE_ENABLED ? 5 : 4,
-    );
-    expect(text).toContain("Build a block");
-    expect(text).toContain("Audit standards");
-    if (TOKEN_READ_SURFACE_ENABLED) {
-      expect(text).toContain("Find a token");
-    } else {
-      expect(text).not.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,93 +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 { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.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_READ_SURFACE_ENABLED ? " 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_READ_SURFACE_ENABLED ? "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.test.ts

@@ -1,64 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import type { FilterConfig } from "../../shared/types/index.js";
-import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
-import { renderLlmOrientation } from "../formatters/index.js";
-import type { LlmData } from "../types.js";
-import collectContext from "./collectContext.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());
-
-const config: FilterConfig = { tier: undefined, channel: "prerelease" };
-
-/** Extract the `## Context` data lines from a rendered orientation doc. */
-function contextBlock(rendered: string): string {
-  const lines = rendered.split("\n");
-  const start = lines.indexOf("## Context");
-  const block: string[] = [];
-  for (let i = start + 1; i < lines.length && lines[i] !== ""; i++) {
-    block.push(lines[i] ?? "");
-  }
-  return block.join("\n");
-}
-
-describe("collectContext", () => {
-  it("assembles counts and namespaces from the store", async () => {
-    const ctx = await collectContext(store, config);
-
-    expect(ctx.tier).toBeUndefined();
-    expect(ctx.channel).toBe("prerelease");
-    expect(ctx.counts.blocks).toBeGreaterThan(0);
-    expect(ctx.counts.standards).toBeGreaterThan(0);
-    expect(ctx.counts.modifierFamilies).toBeGreaterThan(0);
-    expect(ctx.counts.tokens).toBeGreaterThan(0);
-    expect(ctx.namespaces.length).toBeGreaterThan(0);
-  });
-
-  it("renders a stable `## Context` block", async () => {
-    const data: LlmData = {
-      context: await collectContext(store, config),
-      decisionTrees: [],
-      commandReference: [],
-    };
-
-    // The token count only renders while the token read surface is enabled.
-    const tokenSegment = TOKEN_READ_SURFACE_ENABLED ? ", 2 tokens" : "";
-    expect(contextBlock(renderLlmOrientation(data))).toBe(
-      [
-        "tier: (none) | channel: prerelease",
-        `data: 5 blocks, 3 standards, 2 modifier families${tokenSegment}`,
-        "namespaces: cs, ds",
-      ].join("\n"),
-    );
-  });
-});

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

@@ -1,37 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { collectEntityCounts } from "../../info/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 type { LlmContext } from "../types.js";
-
-/**
- * Collects dynamic context for the `pragma llm` orientation output.
- *
- * Queries the store in parallel for entity counts (via
- * {@link collectEntityCounts}) and ontology namespaces, 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 [counts, ontologies] = await Promise.all([
-    collectEntityCounts(store, config),
-    listOntologies(store),
-  ]);
-
-  return {
-    tier: config.tier,
-    tierChain: resolveTierChain(config.tier),
-    channel: config.channel,
-    counts,
-    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**");
-  });
-});

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

@@ -1,9 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileReadCommand } from "../../shared/stories/index.js";
-import { modifierListStory } from "../stories.js";
-
-/** Wire the `pragma modifier list` CLI command from the modifier list story. */
-export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return compileReadCommand(ctx, modifierListStory);
-}

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

@@ -1,91 +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 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("modifier lookup command", () => {
-  it("returns a family with values", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["density"] }, ctx);
-    expect(result.tag).toBe("output");
-
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("density");
-    expect(text).toContain("default");
-    expect(text).toContain("compact");
-  });
-
-  it("throws ENTITY_NOT_FOUND for unknown modifier", 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", async () => {
-    const ctx = makeCtx({ llm: true });
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["importance"] }, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("## importance");
-    expect(text).toContain("- default");
-  });
-
-  it("renders JSON with --format json", async () => {
-    const ctx = makeCtx({ format: "json" });
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["importance"] }, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("importance");
-    expect(parsed.values).toContain("primary");
-  });
-
-  it("renders multiple families together", async () => {
-    const ctx = makeCtx();
-    const cmd = lookupCommand(ctx);
-    const result = await cmd.execute({ names: ["importance", "density"] }, 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");
-  });
-});