@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/info/types.ts

@@ -1,67 +0,0 @@
-/** Summary of how a single package is resolved. */
-export interface PackageRefSummary {
-  readonly pkg: string;
-  readonly source: "npm" | "file" | "git";
-  readonly detail: string;
-}
-
-/** 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;
-  readonly packageRefs?: readonly PackageRefSummary[];
-}
-
-/** 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[];
-}
-
-/**
- * Entity counts for the `pragma llm` orientation summary.
- *
- * Mirrors the row cardinality of the four leaf list operations
- * (`listBlocks`, `listStandards`, `listModifiers`, `listTokens`).
- */
-export interface EntityCounts {
-  readonly blocks: number;
-  readonly standards: number;
-  readonly modifierFamilies: number;
-  readonly tokens: number;
-}

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

@@ -1,111 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { VERSION } from "#constants";
-import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
-import { buildCapabilitiesCommand } from "./commands/index.js";
-import { TOOL_CATALOG } from "./data/index.js";
-import { buildCapabilitiesData } from "./mcp/index.js";
-
-// token_list, token_lookup, and token_sample are gated behind the token
-// read-surface feature flag.
-const EXPECTED_TOOL_COUNT = TOKEN_READ_SURFACE_ENABLED ? 34 : 31;
-
-describe("buildCapabilitiesData", () => {
-  it("returns correct version", () => {
-    const data = buildCapabilitiesData();
-    expect(data.version).toBe(VERSION);
-  });
-
-  it("includes conventions with three fields", () => {
-    const data = buildCapabilitiesData();
-    expect(data.conventions.system).toBeTruthy();
-    expect(data.conventions.model).toBeTruthy();
-    expect(data.conventions.querying).toBeTruthy();
-  });
-
-  it("includes a 3-stage discovery sequence", () => {
-    const data = buildCapabilitiesData();
-    expect(data.discovery_sequence).toHaveLength(3);
-    expect(data.discovery_sequence[0]?.stage).toBe(1);
-    expect(data.discovery_sequence[0]?.tool).toBe("capabilities");
-    expect(data.discovery_sequence[1]?.tool).toBe("*_sample");
-    expect(data.discovery_sequence[2]?.tool).toBe("domain tools");
-  });
-
-  it("includes every tool from TOOL_CATALOG", () => {
-    const data = buildCapabilitiesData();
-    expect(data.tools).toHaveLength(TOOL_CATALOG.length);
-    expect(data.tools).toHaveLength(EXPECTED_TOOL_COUNT);
-  });
-
-  it("every tool has a non-empty use_when", () => {
-    const data = buildCapabilitiesData();
-    for (const tool of data.tools) {
-      expect(tool.use_when.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("counts match tool catalog category lengths", () => {
-    const data = buildCapabilitiesData();
-    expect(data.counts.total).toBe(EXPECTED_TOOL_COUNT);
-    expect(data.counts.read).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "read").length,
-    );
-    expect(data.counts.write).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "write").length,
-    );
-    expect(data.counts.orientation).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "orientation").length,
-    );
-    expect(data.counts.diagnostic).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "diagnostic").length,
-    );
-  });
-
-  it("includes limits section", () => {
-    const data = buildCapabilitiesData();
-    expect(data.limits.output_modes).toContain("text");
-    expect(data.limits.output_modes).toContain("json");
-    expect(data.limits.output_modes).toContain("llm");
-    expect(data.limits.condensed_available).toBe(true);
-  });
-});
-
-describe("buildCapabilitiesCommand", () => {
-  it("returns an output result with plain renderer", async () => {
-    const cmd = buildCapabilitiesCommand();
-    expect(cmd.path).toEqual(["capabilities"]);
-
-    const result = await cmd.execute({}, {} as never);
-    expect(result.tag).toBe("output");
-    if (result.tag !== "output") throw new Error("Expected output result");
-
-    const text = result.render.plain(result.value) as string;
-    expect(text).toContain("Conventions");
-    expect(text).toContain("Discovery Sequence");
-    expect(text).toContain("block_list");
-    expect(text).toContain("read");
-    expect(text).toContain(`${EXPECTED_TOOL_COUNT} tools`);
-  });
-
-  it("emits valid JSON when --format json is requested", async () => {
-    const cmd = buildCapabilitiesCommand();
-    const ctx = {
-      cwd: "/test",
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    };
-
-    const result = await cmd.execute({}, ctx);
-    if (result.tag !== "output") throw new Error("Expected output result");
-
-    const text = result.render.plain(result.value) as string;
-    expect(() => JSON.parse(text)).not.toThrow();
-    expect(JSON.parse(text)).toMatchObject({ version: expect.any(String) });
-  });
-
-  it("does not require a store or runtime", async () => {
-    const cmd = buildCapabilitiesCommand();
-    // Execute with no context — should succeed because it's static
-    const result = await cmd.execute({}, {} as never);
-    expect(result.tag).toBe("output");
-  });
-});

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

@@ -1,37 +0,0 @@
-import {
-  type CommandContext,
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import renderCapabilities from "../formatters/capabilities.js";
-import { buildCapabilitiesData } from "../mcp/specs.js";
-
-/**
- * Builds the `pragma capabilities` command definition.
- *
- * Returns a static system map: conventions, tool catalog with behavioral
- * hints, discovery sequence, and output modes. No store needed. Honours
- * `--format json` by emitting the structured payload so agents can parse it.
- *
- * @returns A command definition for `capabilities`.
- */
-export default function buildCapabilitiesCommand(): CommandDefinition {
-  return {
-    path: ["capabilities"],
-    description:
-      "Discover conventions, available tools, and discovery sequence",
-    parameters: [],
-    execute: async (
-      _params: Record<string, unknown>,
-      ctx: CommandContext,
-    ): Promise<CommandResult> => {
-      const data = buildCapabilitiesData();
-      const asJson = ctx?.globalFlags?.format === "json";
-      return createOutputResult(data, {
-        plain: (value) =>
-          asJson ? JSON.stringify(value, null, 2) : renderCapabilities(value),
-      });
-    },
-  };
-}

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

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

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

@@ -1,41 +0,0 @@
-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,
-      };
-      const asJson = ctx?.globalFlags?.format === "json";
-      return createOutputResult(data, {
-        plain: (value) =>
-          asJson ? JSON.stringify(value, null, 2) : renderLlmOrientation(value),
-      });
-    },
-  };
-}

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

@@ -1,106 +0,0 @@
-import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
-import type { CommandRefEntry } from "../types.js";
-import { TOOL_CATALOG } from "./toolCatalog.js";
-
-/** Look up a use_when string from the tool catalog by MCP tool name. */
-function hintFor(mcpName: string): string {
-  return TOOL_CATALOG.find((t) => t.name === mcpName)?.use_when ?? "";
-}
-
-/**
- * Static command reference table with approximate token-cost estimates
- * and behavioral hints for LLM tool selection.
- *
- * Used by the `pragma llm` orientation output to help LLMs budget context
- * and choose the right tool.
- */
-export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
-  {
-    command: "block sample",
-    tokens: "~600",
-    use_when: hintFor("block_sample"),
-  },
-  { command: "block list", tokens: "~200", use_when: hintFor("block_list") },
-  {
-    command: "block lookup <name-or-iri...> --detailed",
-    tokens: "~500",
-    use_when: hintFor("block_lookup"),
-  },
-  {
-    command: "standard sample",
-    tokens: "~500",
-    use_when: hintFor("standard_sample"),
-  },
-  {
-    command: "standard list --category <cat>",
-    tokens: "~100",
-    use_when: hintFor("standard_list"),
-  },
-  {
-    command: "standard lookup <name-or-iri...> --detailed",
-    tokens: "~400",
-    use_when: hintFor("standard_lookup"),
-  },
-  {
-    command: "standard categories",
-    tokens: "~50",
-    use_when: hintFor("standard_categories"),
-  },
-  {
-    command: "modifier sample",
-    tokens: "~200",
-    use_when: hintFor("modifier_sample"),
-  },
-  {
-    command: "modifier list",
-    tokens: "~100",
-    use_when: hintFor("modifier_list"),
-  },
-  {
-    command: "modifier lookup <name-or-iri...>",
-    tokens: "~80",
-    use_when: hintFor("modifier_lookup"),
-  },
-  ...(TOKEN_READ_SURFACE_ENABLED
-    ? ([
-        {
-          command: "token sample",
-          tokens: "~300",
-          use_when: hintFor("token_sample"),
-        },
-        {
-          command: "token list",
-          tokens: "~400",
-          use_when: hintFor("token_list"),
-        },
-        {
-          command: "token lookup <name-or-iri...> --detailed",
-          tokens: "~150",
-          use_when: hintFor("token_lookup"),
-        },
-      ] as const)
-    : []),
-  { command: "tier list", tokens: "~50", use_when: hintFor("tier_list") },
-  {
-    command: "ontology list",
-    tokens: "~80",
-    use_when: hintFor("ontology_list"),
-  },
-  {
-    command: "ontology show <prefix>",
-    tokens: "~300",
-    use_when: hintFor("ontology_show"),
-  },
-  {
-    command: 'graph query "<sparql>"',
-    tokens: "varies",
-    use_when: hintFor("graph_query"),
-  },
-  {
-    command: "graph inspect <uri>",
-    tokens: "~200",
-    use_when: hintFor("graph_inspect"),
-  },
-  { command: "config show", tokens: "~50", use_when: hintFor("config_show") },
-  { command: "info", tokens: "~100", use_when: hintFor("info") },
-];

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

@@ -1,55 +0,0 @@
-import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
-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: `? First time seeing block data?
-  yes → block sample [~600] → see actual shapes, then query
-  no  → ? Know IRI or name?
-    yes → block lookup <name-or-iri...> --detailed  [~500]
-          e.g. block lookup ds:global.component.button
-    no  → block list [~200] → pick compact IRI → lookup`,
-  },
-  {
-    intent: "Audit standards",
-    tree: `? First time seeing standard data?
-  yes → standard sample [~500] → see actual shapes, then query
-  no  → ? Know standard IRI or name?
-    yes → standard lookup <name-or-iri...> --detailed [~400]
-          e.g. standard lookup react/component/props
-    no  → standard list --category <cat> [~100]
-          → standard lookup <std-iri...> --detailed [~400] Σ500`,
-  },
-  ...(TOKEN_READ_SURFACE_ENABLED
-    ? ([
-        {
-          intent: "Find a token",
-          tree: `? Know token IRI or name?
-  yes → token lookup <name-or-iri...> --detailed [~150]
-  no  → token list --category <cat> [~100]
-        → token lookup <name-or-iri...> --detailed [~150] Σ250`,
-        },
-      ] as const)
-    : []),
-  {
-    intent: "Explore the design system",
-    tree: `first time → block sample / ${TOKEN_READ_SURFACE_ENABLED ? "token sample / " : ""}modifier sample [~300] → see real shapes
-high-level → ontology list [~80] → ontology show <ns> [~300]
-modifiers  → modifier list [~100] → modifier lookup <name-or-iri...> [~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

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

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

@@ -1,221 +0,0 @@
-/** Tool catalog with behavioral hints for agent orientation. */
-
-import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
-
-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",
-  },
-  ...(TOKEN_READ_SURFACE_ENABLED
-    ? ([
-        {
-          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",
-        },
-      ] as const)
-    : []),
-  {
-    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",
-  },
-  ...(TOKEN_READ_SURFACE_ENABLED
-    ? ([
-        {
-          name: "token_sample",
-          category: "read",
-          use_when:
-            "See actual token data shapes (with theme values) before querying — returns random instances each call",
-        },
-      ] as const)
-    : []),
-  {
-    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",
-  },
-  {
-    name: "create_application",
-    category: "write",
-    use_when:
-      "Scaffolding a new React application with SSR, routing, and optional Relay",
-  },
-  {
-    name: "create_domain",
-    category: "write",
-    use_when: "Scaffolding a new domain module inside an existing application",
-  },
-  {
-    name: "create_route",
-    category: "write",
-    use_when: "Scaffolding a new route inside an existing application",
-  },
-  {
-    name: "create_wrapper",
-    category: "write",
-    use_when: "Scaffolding a new wrapper component inside an application",
-  },
-
-  // — 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",
-  },
-];