@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/info/operations/collectInfo.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-const readConfigMock = vi.fn();
+const readConfigLayersMock = vi.fn();
 const detectInstallSourceMock = vi.fn();
 const bootStoreMock = vi.fn();
 const checkRegistryVersionMock = vi.fn();
@@ -8,7 +8,7 @@ const collectStoreSummaryMock = vi.fn();
 
 vi.mock("#config", async (importOriginal) => ({
   ...(await importOriginal<typeof import("#config")>()),
-  readConfig: readConfigMock,
+  readConfigLayers: readConfigLayersMock,
 }));
 
 vi.mock("#package-manager", async (importOriginal) => {
@@ -46,12 +46,23 @@ describe("collectInfo", () => {
       scope: "global",
       label: "bun (global)",
     });
-    readConfigMock.mockReturnValue({ tier: "apps/lxd", channel: "normal" });
+    readConfigLayersMock.mockReturnValue({
+      config: { tier: "apps/lxd", channel: "normal" },
+      origins: {
+        tier: "project",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: false },
+      project: { path: "/repo/pragma.config.json", exists: true },
+    });
   });
 
   it("includes update information and store summary when available", async () => {
     const dispose = vi.fn();
-    bootStoreMock.mockResolvedValue({ dispose });
+    bootStoreMock.mockResolvedValue({ store: { dispose }, packages: [] });
     checkRegistryVersionMock.mockResolvedValue({
       latest: "9.9.9",
       distTag: "latest",
@@ -91,7 +102,7 @@ describe("collectInfo", () => {
   it("omits the update section when already on the latest version", async () => {
     const { VERSION } = await import("#constants");
     const dispose = vi.fn();
-    bootStoreMock.mockResolvedValue({ dispose });
+    bootStoreMock.mockResolvedValue({ store: { dispose }, packages: [] });
     checkRegistryVersionMock.mockResolvedValue({
       latest: VERSION,
       distTag: "latest",

package/src/domains/info/operations/collectInfo.ts

@@ -1,15 +1,14 @@
-import { readConfig } from "#config";
+import { readConfigLayers } from "#config";
 import { VERSION } from "#constants";
 import { detectInstallSource, PM_COMMANDS } from "#package-manager";
-import {
-  type PackageRef,
-  parsePackageEntry,
+import type {
+  PackageRef,
+  RawPackageEntry,
 } from "../../refs/operations/parseRef.js";
-import readGlobalRefs from "../../refs/operations/readGlobalRefs.js";
 import { bootStore } from "../../shared/bootStore.js";
 import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import { mergeAndParseRefs } from "../../shared/mergeAndParseRefs.js";
 import type { InfoData, PackageRefSummary } from "../types.js";
 import checkRegistryVersion from "./checkRegistryVersion.js";
 import { collectStoreSummary } from "./collectStoreSummary.js";
@@ -28,7 +27,8 @@ import { collectStoreSummary } from "./collectStoreSummary.js";
 export default async function collectInfo(cwd: string): Promise<InfoData> {
   const install = detectInstallSource();
   const pm = install.packageManager;
-  const config = readConfig(cwd);
+  const layers = readConfigLayers(cwd);
+  const config = layers.config;
   const tierChain = resolveTierChain(config.tier);
   const channelReleases = CHANNEL_RELEASES[config.channel];
 
@@ -48,14 +48,14 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
   }
 
   let store: InfoData["store"];
-  let keStore: Awaited<ReturnType<typeof bootStore>> | undefined;
+  let bootResult: Awaited<ReturnType<typeof bootStore>> | undefined;
   try {
-    keStore = await bootStore({ cwd });
-    store = await collectStoreSummary(keStore);
+    bootResult = await bootStore({ cwd });
+    store = await collectStoreSummary(bootResult.store);
   } catch {
     // Store unavailable — show info without store section
   } finally {
-    keStore?.dispose();
+    bootResult?.store.dispose();
   }
 
   // Collect package ref summaries
@@ -65,7 +65,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
     version: VERSION,
     pm,
     installSource: install.label,
-    configPath: "pragma.config.json",
+    configPath: layers.project.exists
+      ? layers.project.path
+      : layers.global.path,
     tier: config.tier,
     tierChain,
     channel: config.channel,
@@ -78,14 +80,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
 }
 
 function collectPackageRefSummaries(
-  projectPackages?: ReadonlyArray<
-    string | { readonly name: string; readonly source?: string }
-  >,
+  configPackages?: ReadonlyArray<RawPackageEntry>,
 ): PackageRefSummary[] {
-  const entries = projectPackages ?? readGlobalRefs();
-  const raw = entries.length > 0 ? entries : DEFAULT_PACKAGES.map((pkg) => pkg);
-
-  return raw.map((entry) => refToSummary(parsePackageEntry(entry)));
+  return mergeAndParseRefs(configPackages).map(refToSummary);
 }
 
 function refToSummary(ref: PackageRef): PackageRefSummary {

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

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { VERSION } from "#constants";
+import { buildCapabilitiesCommand } from "./commands/index.js";
+import { TOOL_CATALOG } from "./data/index.js";
+import { buildCapabilitiesData } from "./mcp/index.js";
+
+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(30);
+  });
+
+  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(30);
+    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("30 tools");
+  });
+
+  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

@@ -0,0 +1,28 @@
+import {
+  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.
+ *
+ * @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 (): Promise<CommandResult> => {
+      const data = buildCapabilitiesData();
+      return createOutputResult(data, { plain: renderCapabilities });
+    },
+  };
+}

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

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

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

@@ -1,25 +1,97 @@
 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.
+ * 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.
+ * 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 list", tokens: "~200" },
-  { command: "block lookup <name-or-iri...> --detailed", tokens: "~500" },
-  { command: "standard list --category <cat>", tokens: "~100" },
-  { command: "standard lookup <name-or-iri...> --detailed", tokens: "~400" },
-  { command: "standard categories", tokens: "~50" },
-  { command: "modifier list", tokens: "~100" },
-  { command: "modifier lookup <name-or-iri...>", tokens: "~80" },
-  { command: "token list", tokens: "~400" },
-  { command: "token lookup <name-or-iri...> --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" },
+  {
+    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"),
+  },
+  {
+    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"),
+  },
+  { 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

@@ -9,21 +9,22 @@ import type { DecisionTree } from "../types.js";
 export const DECISION_TREES: readonly DecisionTree[] = [
   {
     intent: "Build a block",
-    tree: `? 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`,
+    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: `? Know standard IRI or name?
-  yes → standard lookup <name-or-iri...> --detailed [~400]
-        e.g. standard lookup react/component/props
-  no  → ? Know block IRI or name?
-      yes → block lookup <name-or-iri...> --detailed [~500]
-        → inspect related guidance manually Σ500
-        no  → standard list --category <cat> [~100]
-              → standard lookup <std-iri...> --detailed [~400] Σ500`,
+    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`,
   },
   {
     intent: "Find a token",
@@ -34,7 +35,8 @@ export const DECISION_TREES: readonly DecisionTree[] = [
   },
   {
     intent: "Explore the design system",
-    tree: `high-level → ontology list [~80] → ontology show <ns> [~300]
+    tree: `first time → block sample / 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]`,

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

@@ -2,3 +2,5 @@
 
 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

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

@@ -0,0 +1,50 @@
+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,3 +1,4 @@
 /** @module Barrel for llm formatters. */
 
+export { default as renderCapabilities } from "./capabilities.js";
 export { default as renderLlmOrientation } from "./orientation.js";