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

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";

package/src/domains/llm/index.ts

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

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

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

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

@@ -2,74 +2,80 @@
  * 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 } from "../data/index.js";
+import {
+  COMMAND_REFERENCE,
+  DECISION_TREES,
+  TOOL_CATALOG,
+} from "../data/index.js";
 import { collectContext } from "../operations/index.js";
-import type { LlmData } from "../types.js";
+import type { CapabilitiesData, 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,
-];
+/** 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:
-      "List all available pragma MCP tools with counts by category. Call this first to discover what pragma can do. (~100 tokens)",
+      "Discover pragma conventions, available tools with behavioral hints, and discovery sequence. Call this first at session start.",
     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,
-          },
-        },
-      };
+      return { data: buildCapabilitiesData() };
     },
   },
   {
     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.",
+      "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);
@@ -84,4 +90,5 @@ const specs: readonly ToolSpec[] = [
   },
 ];
 
+export { buildCapabilitiesData };
 export default specs;

package/src/domains/llm/types.ts

@@ -1,3 +1,42 @@
+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;
@@ -22,6 +61,7 @@ export interface DecisionTree {
 export interface CommandRefEntry {
   readonly command: string;
   readonly tokens: string;
+  readonly use_when: string;
 }
 
 /** Complete payload rendered by `pragma llm`: context, trees, and reference. */

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

@@ -1,4 +1,5 @@
-/** @module Re-exports modifier command builders (`lookup`, `list`). */
+/** @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/sample.ts

@@ -0,0 +1,53 @@
+/**
+ * Wires the `pragma modifier sample` CLI command.
+ *
+ * Returns 1–5 complete modifier family instances as exemplars so agents
+ * can learn the data shape before writing queries.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import type { ModifierFamily, SampleOutput } from "../../shared/types/index.js";
+import { sampleFormatters } from "../formatters/index.js";
+import { sampleModifiers } from "../operations/index.js";
+
+const NEXT_STEPS = [
+  "Use modifier_lookup to inspect specific modifier families by name.",
+  "Use modifier_list to see all available modifier families.",
+];
+
+export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["modifier", "sample"],
+    description:
+      "Return randomly selected complete modifier family instances as exemplars for shape discovery",
+    parameters: [
+      {
+        name: "count",
+        type: "string",
+        description: "Number of samples to return (1–5, default 2)",
+        required: false,
+      },
+    ],
+    meta: {
+      examples: ["pragma modifier sample", "pragma modifier sample --count 3"],
+    },
+    async execute(params) {
+      const count = Number(params.count ?? 2);
+      const result = await sampleModifiers(ctx.store, count);
+
+      const output: SampleOutput<ModifierFamily> = {
+        ...result,
+        nextSteps: NEXT_STEPS,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, sampleFormatters),
+      });
+    },
+  };
+}

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

@@ -1,7 +1,8 @@
-/** @module Re-exports modifier formatters (`lookupFormatters`, `listFormatters`). */
+/** @module Re-exports modifier formatters (`listFormatters`, `lookupFormatters`, `sampleFormatters`). */
 
 export { default as listFormatters } from "./list.js";
 export {
   createInkLookupOptions,
   default as lookupFormatters,
 } from "./lookup.js";
+export { default as sampleFormatters } from "./sample.js";

package/src/domains/modifier/formatters/sample.ts

@@ -0,0 +1,15 @@
+/**
+ * Sample formatter for the modifier domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing modifier lookup formatter.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { ModifierFamily } from "../../shared/types/index.js";
+import lookupFormatters from "./lookup.js";
+
+export default createSampleFormatters<ModifierFamily>(
+  "modifiers",
+  (family, mode) => lookupFormatters[mode](family),
+);

package/src/domains/modifier/index.ts

@@ -7,15 +7,19 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { listCommand, lookupCommand } from "./commands/index.js";
+import { listCommand, lookupCommand, sampleCommand } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx)];
+  return [listCommand(ctx), lookupCommand(ctx), sampleCommand(ctx)];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
 export { modifierConfig } from "./modifierConfig.js";
-export { listModifiers, lookupModifier } from "./operations/index.js";
+export {
+  listModifiers,
+  lookupModifier,
+  sampleModifiers,
+} from "./operations/index.js";
 export {
   modifierEmptyError,
   resolveModifierList,

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

@@ -9,7 +9,9 @@ import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
   listFormatters as modifierListFmt,
   lookupFormatters as modifierLookupFmt,
+  sampleFormatters as modifierSampleFmt,
 } from "../formatters/index.js";
+import { sampleModifiers } from "../operations/index.js";
 import {
   resolveModifierList,
   resolveModifierLookup,
@@ -92,6 +94,51 @@ const specs: readonly ToolSpec[] = [
       return { data: result, meta: { count: result.results.length } };
     },
   },
+  {
+    name: "modifier_sample",
+    description:
+      "Return 1–5 randomly selected complete modifier family instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+    params: {
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { count, condensed }) {
+      const n = Number(count ?? 2);
+      const result = await sampleModifiers(rt.store, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total modifier families.`,
+        "Use modifier_lookup to inspect specific modifier families by name.",
+        "Use modifier_list to see all available modifier families.",
+      ];
+
+      if (condensed) {
+        const text = modifierSampleFmt.llm({ ...result, nextSteps });
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return {
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
+        },
+        meta: { count: result.samples.length },
+      };
+    },
+  },
 ] as const;
 
 export default specs;

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

@@ -1,4 +1,5 @@
-/** @module Re-exports modifier operations (`lookupModifier`, `listModifiers`). */
+/** @module Re-exports modifier operations (`listModifiers`, `lookupModifier`, `sampleModifiers`). */
 
 export { default as listModifiers } from "./list.js";
 export { default as lookupModifier } from "./lookup.js";
+export { default as sampleModifiers } from "./sample.js";

package/src/domains/modifier/operations/lookup.ts

@@ -13,6 +13,11 @@ import { escapeSparqlValue } from "@canonical/ke";
 import { PragmaError } from "#error";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
+import {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type { ModifierFamily } from "../../shared/types/index.js";
 
 export default async function lookupModifier(
@@ -39,12 +44,16 @@ export default async function lookupModifier(
   );
 
   if (result.type !== "select" || result.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "modifier");
+    const crossDomain = await detectCrossDomain(name, "modifier", store);
     throw PragmaError.notFound("modifier", name, {
+      suggestions: suggestNames(name, candidates),
       recovery: {
         message: "List available modifiers.",
         cli: "pragma modifier list",
         mcp: { tool: "modifier_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }
 

package/src/domains/modifier/operations/sample.ts

@@ -0,0 +1,32 @@
+/**
+ * Returns a small number of complete modifier family instances as exemplars.
+ *
+ * Composes the existing list and lookup operations to avoid duplicating
+ * any SPARQL logic. Agents use this to learn the data shape before querying.
+ *
+ * @param store - ke store to query
+ * @param count - number of samples (clamped 1–5, default 2)
+ * @returns sample result with detailed modifier families and total count
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import pickRandom from "../../shared/pickRandom.js";
+import type { ModifierFamily, SampleResult } from "../../shared/types/index.js";
+import listModifiers from "./list.js";
+import lookupModifier from "./lookup.js";
+
+export default async function sampleModifiers(
+  store: Store,
+  count = 2,
+): Promise<SampleResult<ModifierFamily>> {
+  const clamped = Math.max(1, Math.min(5, count));
+  const all = await listModifiers(store);
+  const selected = pickRandom(all, clamped);
+
+  const samples = await Promise.all(
+    selected.map((m) => lookupModifier(store, m.name)),
+  );
+
+  return { samples, totalCount: all.length };
+}

package/src/domains/modifier/orchestration/modifierEmptyError.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import modifierEmptyError from "./modifierEmptyError.js";
+
+describe("modifierEmptyError", () => {
+  it("recovers via a runnable install command (store-empty is its only scenario)", () => {
+    const err = modifierEmptyError();
+
+    // `modifier list` takes no filters, so an empty result is always
+    // store-empty: the recovery is the install, not a widen.
+    expect(err.recovery).toEqual({
+      message: "Install the design system packages that provide modifiers.",
+      cli: "bun add -D @canonical/design-system",
+    });
+  });
+
+  it("cites a real default package, not @canonical/ds-global", () => {
+    const err = modifierEmptyError();
+    expect(err.recovery?.cli).toContain("@canonical/design-system");
+    expect(err.recovery?.cli).not.toContain("ds-global");
+  });
+
+  it("has no mcp retry for store-empty (re-listing would return empty again)", () => {
+    const err = modifierEmptyError();
+    expect(err.recovery?.mcp).toBeUndefined();
+  });
+});

package/src/domains/modifier/orchestration/modifierEmptyError.ts

@@ -1,10 +1,15 @@
 import { PragmaError } from "#error";
 
 export default function modifierEmptyError(): PragmaError {
+  // `modifier list` takes no filters, so an empty result always means the
+  // design system packages that supply modifier triples are absent. The
+  // recovery is the runnable install command, not a (non-existent) widen.
   return PragmaError.emptyResults("modifier", {
     recovery: {
-      message:
-        "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+      // The base error already states "No modifiers found"; the recovery adds
+      // only the cause + the runnable fix (the cli line is what renders on CLI).
+      message: "Install the design system packages that provide modifiers.",
+      cli: "bun add -D @canonical/design-system",
     },
   });
 }

package/src/domains/modifier/orchestration/resolveModifierLookup.ts

@@ -1,6 +1,7 @@
 import type { LookupContract, LookupResult } from "../../shared/contracts.js";
 import lookupMany from "../../shared/lookupMany.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
+import { expandLookupQueries } from "../../shared/suggestions/index.js";
 import type { ModifierFamily } from "../../shared/types/index.js";
 import { lookupModifier } from "../operations/index.js";
 
@@ -8,11 +9,22 @@ export default async function resolveModifierLookup(
   store: Pick<PragmaRuntime, "store">["store"],
   queries: readonly string[],
 ): Promise<LookupContract<ModifierFamily>> {
-  const result: LookupResult<ModifierFamily> = await lookupMany(
+  const { names, globErrors } = await expandLookupQueries(
     queries,
-    (query) => lookupModifier(store, query),
+    store,
+    "modifier",
   );
 
+  const lookupResult: LookupResult<ModifierFamily> =
+    names.length > 0
+      ? await lookupMany(names, (query) => lookupModifier(store, query))
+      : { results: [], errors: [] };
+
+  const result: LookupResult<ModifierFamily> = {
+    results: lookupResult.results,
+    errors: [...lookupResult.errors, ...globErrors],
+  };
+
   return {
     params: { names: queries },
     result,

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

@@ -3,7 +3,7 @@
 export { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
 export type { PackageRef, RawPackageEntry } from "./parseRef.js";
 export { parsePackageEntry } from "./parseRef.js";
-export { cacheRoot, gitCacheDir, globalConfigDir } from "./paths.js";
+export { cacheRoot, dataRoot, gitCacheDir, globalConfigDir } from "./paths.js";
 export { default as readGlobalRefs } from "./readGlobalRefs.js";
 
 export type { UpdateRefsOptions, UpdateResult } from "./updateRefs.js";

package/src/domains/refs/operations/paths.ts

@@ -1,9 +1,10 @@
 /**
- * Cross-platform path resolution for pragma cache and global config.
+ * Cross-platform path resolution for pragma cache, config, and data.
  *
  * Respects XDG Base Directory Specification:
  * - XDG_CACHE_HOME for cache (default: ~/.cache)
  * - XDG_CONFIG_HOME for global config (default: ~/.config)
+ * - XDG_DATA_HOME for persistent data (default: ~/.local/share)
  *
  * Override via PRAGMA_CACHE_DIR for CI and testing.
  * Uses os.homedir() for macOS/WSL/Linux portability.
@@ -42,6 +43,19 @@ export function globalConfigDir(): string {
   return join(base, "pragma");
 }
 
+/**
+ * Root directory for pragma persistent data (extracted skills, etc.).
+ *
+ * Resolution order:
+ * 1. XDG_DATA_HOME/pragma (XDG spec)
+ * 2. ~/.local/share/pragma (default)
+ */
+export function dataRoot(): string {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg ?? join(homedir(), ".local", "share");
+  return join(base, "pragma");
+}
+
 /**
  * Cache directory for a specific git-ref-resolved package.
  *
@@ -54,6 +68,20 @@ export function gitCacheDir(pkg: string, ref: string): string {
   return join(cacheRoot(), "refs", pkg, sanitizedRef);
 }
 
+/**
+ * Root directory for query trace logs.
+ *
+ * Resolution order:
+ * 1. PRAGMA_TRACE_DIR environment variable (CI/testing override)
+ * 2. XDG_DATA_HOME/pragma/traces (default)
+ */
+export function traceDir(): string {
+  if (process.env.PRAGMA_TRACE_DIR) {
+    return process.env.PRAGMA_TRACE_DIR;
+  }
+  return join(dataRoot(), "traces");
+}
+
 /**
  * Sanitize a git ref for use as a directory name.
  * Replaces characters that are invalid or confusing in path segments.