@canonical/pragma-cli 0.18.0

package/src/domains/info/types.test-d.ts

@@ -0,0 +1,35 @@
+/**
+ * Compile-time type tests for info + upgrade domain types.
+ *
+ * Checked by `tsc --noEmit`, not executed at runtime.
+ */
+
+import { expectTypeOf } from "expect-type";
+import type {
+  InfoData,
+  RegistryCheckResult,
+  StoreSummary,
+  UpgradeData,
+} from "./types.js";
+
+// InfoData
+expectTypeOf<InfoData["version"]>().toBeString();
+expectTypeOf<InfoData["pm"]>().toBeString();
+expectTypeOf<InfoData["tier"]>().toEqualTypeOf<string | undefined>();
+expectTypeOf<InfoData["tierChain"]>().toEqualTypeOf<readonly string[]>();
+expectTypeOf<InfoData["updateSkipped"]>().toBeBoolean();
+
+// UpgradeData
+expectTypeOf<UpgradeData["current"]>().toBeString();
+expectTypeOf<UpgradeData["latest"]>().toEqualTypeOf<string | undefined>();
+expectTypeOf<UpgradeData["dryRun"]>().toBeBoolean();
+expectTypeOf<UpgradeData["offline"]>().toBeBoolean();
+expectTypeOf<UpgradeData["executed"]>().toBeBoolean();
+
+// RegistryCheckResult
+expectTypeOf<RegistryCheckResult["latest"]>().toBeString();
+expectTypeOf<RegistryCheckResult["distTag"]>().toBeString();
+
+// StoreSummary
+expectTypeOf<StoreSummary["tripleCount"]>().toBeNumber();
+expectTypeOf<StoreSummary["graphNames"]>().toEqualTypeOf<readonly string[]>();

package/src/domains/info/types.ts

@@ -0,0 +1,46 @@
+/** Data collected by `pragma info` for rendering. */
+export interface InfoData {
+  readonly version: string;
+  readonly pm: string;
+  readonly installSource: string;
+  readonly configPath: string;
+  readonly tier: string | undefined;
+  readonly tierChain: readonly string[];
+  readonly channel: string;
+  readonly channelReleases: readonly string[];
+  readonly update:
+    | {
+        readonly current: string;
+        readonly latest: string;
+        readonly command: string;
+      }
+    | undefined;
+  readonly updateSkipped: boolean;
+  readonly store:
+    | { readonly tripleCount: number; readonly graphNames: readonly string[] }
+    | undefined;
+}
+
+/** Data collected by `pragma upgrade` for rendering. */
+export interface UpgradeData {
+  readonly pm: string;
+  readonly current: string;
+  readonly latest: string | undefined;
+  readonly command: string;
+  readonly dryRun: boolean;
+  readonly alreadyLatest: boolean;
+  readonly offline: boolean;
+  readonly executed: boolean;
+}
+
+/** Result of checking the npm registry for the latest package version. */
+export interface RegistryCheckResult {
+  readonly latest: string;
+  readonly distTag: string;
+}
+
+/** Summary statistics from the ke store (triple count and named graphs). */
+export interface StoreSummary {
+  readonly tripleCount: number;
+  readonly graphNames: readonly string[];
+}

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

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

package/src/domains/llm/commands/llm.ts

@@ -0,0 +1,37 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { COMMAND_REFERENCE, DECISION_TREES } from "../data/index.js";
+import renderLlmOrientation from "../formatters/orientation.js";
+import collectContext from "../operations/collectContext.js";
+import type { LlmData } from "../types.js";
+
+/**
+ * Builds the `pragma llm` command definition.
+ *
+ * Produces an LLM orientation document containing live context (entity counts,
+ * tier/channel), static decision trees, and a command reference table.
+ *
+ * @param ctx - Pragma runtime context providing the ke store and config.
+ * @returns A command definition for `llm`.
+ */
+export default function buildLlmCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["llm"],
+    description:
+      "LLM orientation — context, decision trees, and command reference",
+    parameters: [],
+    execute: async (): Promise<CommandResult> => {
+      const context = await collectContext(ctx.store, ctx.config);
+      const data: LlmData = {
+        context,
+        decisionTrees: DECISION_TREES,
+        commandReference: COMMAND_REFERENCE,
+      };
+      return createOutputResult(data, { plain: renderLlmOrientation });
+    },
+  };
+}

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

@@ -0,0 +1,25 @@
+import type { CommandRefEntry } from "../types.js";
+
+/**
+ * Static command reference table with approximate token-cost estimates.
+ *
+ * Used by the `pragma llm` orientation output to help LLMs budget context.
+ */
+export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
+  { command: "block list", tokens: "~200" },
+  { command: "block lookup <name> --detailed", tokens: "~500" },
+  { command: "standard list --category <cat>", tokens: "~100" },
+  { command: "standard lookup <name> --detailed", tokens: "~400" },
+  { command: "standard categories", tokens: "~50" },
+  { command: "modifier list", tokens: "~100" },
+  { command: "modifier lookup <name>", tokens: "~80" },
+  { command: "token list", tokens: "~400" },
+  { command: "token lookup <name> --detailed", tokens: "~150" },
+  { command: "tier list", tokens: "~50" },
+  { command: "ontology list", tokens: "~80" },
+  { command: "ontology show <prefix>", tokens: "~300" },
+  { command: 'graph query "<sparql>"', tokens: "varies" },
+  { command: "graph inspect <uri>", tokens: "~200" },
+  { command: "config show", tokens: "~50" },
+  { command: "info", tokens: "~100" },
+];

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

@@ -0,0 +1,46 @@
+import type { DecisionTree } from "../types.js";
+
+/**
+ * Static decision trees guiding LLMs through common pragma workflows.
+ *
+ * Each tree maps an intent (e.g. "Build a block") to a compact ASCII
+ * flowchart with token-cost annotations.
+ */
+export const DECISION_TREES: readonly DecisionTree[] = [
+  {
+    intent: "Build a block",
+    tree: `? Know name?
+  yes → block lookup <name> --detailed  [~500]
+  no  → block list [~200] → pick → lookup`,
+  },
+  {
+    intent: "Audit standards",
+    tree: `? Know standard?
+  yes → standard lookup <name> --detailed [~400]
+  no  → ? Know block?
+      yes → block lookup <name> --detailed [~500]
+        → inspect related guidance manually Σ500
+        no  → standard list --category <cat> [~100]
+              → standard lookup <std> --detailed [~400] Σ500`,
+  },
+  {
+    intent: "Find a token",
+    tree: `? Know name?
+  yes → token lookup <name> --detailed [~150]
+  no  → token list --category <cat> [~100]
+        → token lookup <name> --detailed [~150] Σ250`,
+  },
+  {
+    intent: "Explore the design system",
+    tree: `high-level → ontology list [~80] → ontology show <ns> [~300]
+modifiers  → modifier list [~100] → modifier lookup <name> [~80]
+tiers      → tier list [~50]
+raw        → graph query "SELECT ..." → graph inspect <uri> [~200]`,
+  },
+  {
+    intent: "Configure",
+    tree: `tier    → config tier <path> → config show [~50]
+channel → config channel <value> (normal|experimental|prerelease)
+status  → info [~100]`,
+  },
+];

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

@@ -0,0 +1,4 @@
+/** @module Barrel for llm static data. */
+
+export { COMMAND_REFERENCE } from "./commandReference.js";
+export { DECISION_TREES } from "./decisionTrees.js";

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,87 @@
+/**
+ * MCP tool specs for llm domain — capabilities, llm.
+ */
+
+import { buildFilterConfig } from "../../shared/filters/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { COMMAND_REFERENCE, DECISION_TREES } from "../data/index.js";
+import { collectContext } from "../operations/index.js";
+import type { LlmData } from "../types.js";
+
+/** All registered tool names, categorized for the capabilities response. */
+const toolNames = {
+  read: [
+    "block_list",
+    "block_lookup",
+    "standard_list",
+    "standard_lookup",
+    "standard_categories",
+    "modifier_list",
+    "modifier_lookup",
+    "token_list",
+    "token_lookup",
+    "tier_list",
+    "config_show",
+    "ontology_list",
+    "ontology_show",
+    "graph_query",
+    "graph_inspect",
+    "skill_list",
+  ],
+  write: [
+    "config_tier",
+    "config_channel",
+    "tokens_add_config",
+    "create_component",
+    "create_package",
+  ],
+  orientation: ["llm", "capabilities"],
+  diagnostic: ["doctor", "info"],
+};
+const allToolNames = [
+  ...toolNames.read,
+  ...toolNames.write,
+  ...toolNames.orientation,
+  ...toolNames.diagnostic,
+];
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "capabilities",
+    description:
+      "List all available pragma MCP tools with counts by category. Call this first to discover what pragma can do. (~100 tokens)",
+    readOnly: true,
+    async execute() {
+      return {
+        data: {
+          tools: allToolNames,
+          counts: {
+            total: allToolNames.length,
+            read: toolNames.read.length,
+            write: toolNames.write.length,
+            orientation: toolNames.orientation.length,
+            diagnostic: toolNames.diagnostic.length,
+          },
+        },
+      };
+    },
+  },
+  {
+    name: "llm",
+    description:
+      "Get LLM orientation for the pragma design system CLI. Returns context, decision trees for common intents, and command reference with token costs. Call this first when starting a design system task.",
+    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 default specs;

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

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

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

package/src/domains/llm/types.ts

@@ -0,0 +1,32 @@
+/** 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;
+}
+
+/** 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

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * Wires the `pragma modifier list` CLI command.
+ *
+ * Lists all modifier families with their allowed values. Throws a
+ * structured recovery error when no families are found.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { listFormatters } from "../formatters/index.js";
+import { resolveModifierList } from "../orchestration/index.js";
+
+export default function listCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["modifier", "list"],
+    description: "List all modifier families",
+    parameters: [],
+    meta: {
+      examples: ["pragma modifier list", "pragma modifier list --llm"],
+    },
+    async execute() {
+      const resolution = await resolveModifierList(ctx);
+
+      return createOutputResult([...resolution.items], {
+        plain: selectFormatter(ctx, listFormatters),
+      });
+    },
+  };
+}