@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/capabilities/capabilities.verb.ts

@@ -0,0 +1,48 @@
+/**
+ * The `capabilities` orientation verb (noun `capabilities`, self-verb).
+ *
+ * Storeless read: it returns the grammar-derived tool catalog + conventions +
+ * discovery sequence an agent reads at session start. It replaces the retired
+ * old-shell `llm` tool — the live-context half of that tool (tier/channel/entity
+ * counts) is deliberately DROPPED here (it would require a store boot at
+ * orientation) and lives in `info` / `config show` / `sources status` instead.
+ *
+ * `run` is a lazy thunk that dynamic-imports the catalog + the capability
+ * registry barrel, so building the command tree never pulls the derivation onto
+ * the `--help`/`__complete` fast path, and the tool never boots the store
+ * (`store.booted` stays false — the storeless-spy invariant).
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { capabilitiesFormatters } from "./capabilities.render.js";
+import type { CapabilitiesData } from "./types.js";
+
+const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
+  path: ["capabilities"],
+  summary:
+    "Discover pragma conventions, the annotated tool catalog, and the discovery sequence.",
+  doc: "Storeless orientation for agents. Returns the conventions (KG / tier-channel / SPARQL model), a four-stage discovery sequence, and every live tool with a behavioural use_when hint and category — all derived from the live grammar, so it never drifts. Call it first at session start.",
+  params: [],
+  output: { formatters: capabilitiesFormatters },
+  examples: [
+    { cmd: "pragma capabilities", note: "the annotated tool catalog" },
+    { cmd: "pragma capabilities --format json", note: "the structured map" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, _runtime) =>
+    Promise.all([import("./catalog.js"), import("../index.js")]).then(
+      ([catalog, registry]) =>
+        catalog.buildCapabilitiesData(registry.capabilities),
+    ),
+};
+
+/** The `capabilities` verb, widened for registry composition. */
+export const capabilitiesSelfVerb = asVerb(capabilitiesVerb);

package/src/capabilities/capabilities/catalog.ts

@@ -0,0 +1,148 @@
+/**
+ * The SELF-UPDATING capabilities catalog.
+ *
+ * `buildCapabilitiesData(modules)` projects the LIVE grammar: it emits the
+ * surface, walks `mcpSurface.tools` (the sorted, covenant-conformant set), and
+ * annotates each tool from the authored `TOOL_HINTS` table. The tool set, the
+ * category counts, and the discovery-sample list are all DERIVED — never pinned
+ * — so the catalog tracks the surface automatically (the fix for the old shell's
+ * hand-maintained list, which drifted to name retired tools).
+ *
+ * Pure + zod-free: it reads only `emitSurface` (itself fast-path-safe), so the
+ * verb's storeless guarantee holds. The conventions + discovery strings are
+ * exported so `kernel/project/mcp/instructions.ts` derives the handshake
+ * orientation from the SAME source and the two can never diverge.
+ */
+
+import { VERSION } from "../../constants.js";
+import { emitSurface } from "../../kernel/spec/emitSurface.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { TOOL_HINTS } from "./hints.js";
+import type {
+  CapabilitiesData,
+  CatalogTool,
+  DiscoveryStage,
+  ToolCounts,
+} from "./types.js";
+
+/**
+ * The four orientation conventions. The first three (system/model/querying) are
+ * verbatim from the old shell — they describe the KG / tier-channel / SPARQL
+ * model and are still accurate for v2; `mutations` is new in v2, surfacing the
+ * plan-first/confirm gate.
+ */
+export const 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_set (e.g. config_set tier apps/lxd, config_set channel experimental).",
+  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.",
+  mutations:
+    "Mutating tools are plan-first: call once WITHOUT confirm to get a plan (meta.planOnly, no writes), then repeat the call with confirm: true to execute.",
+} as const;
+
+/** The output modes v2 renders (dropped "text" → "plain"; condensed retired). */
+const OUTPUT_MODES = ["plain", "json", "llm"] as const;
+
+/** The set of tool names that mutate, read from the emitted surface. */
+function mutatingTools(modules: readonly CapabilityModule[]): Set<string> {
+  const mutating = new Set<string>();
+  for (const { verbs } of Object.values(emitSurface(modules).nouns)) {
+    for (const verb of verbs) {
+      if (verb.mutates && typeof verb.mcp === "string") mutating.add(verb.mcp);
+    }
+  }
+  return mutating;
+}
+
+/** The live sorted tool names the covenant blesses, from the emitted surface. */
+export function liveTools(modules: readonly CapabilityModule[]): string[] {
+  return emitSurface(modules).mcpSurface.tools;
+}
+
+/**
+ * Build the discovery sequence, deriving the sample list from the tools that
+ * ACTUALLY exist (v2 ships block/standard/modifier/token samples). Wording is
+ * ported from the old `buildCapabilitiesData`, plus a store-state pre-check so a
+ * cold agent is never sent into `*_sample` (or any store read) blind — every
+ * store read fails STORE_UNAVAILABLE until `sources_update` has built the store.
+ */
+export function buildDiscoverySequence(
+  tools: readonly string[],
+): DiscoveryStage[] {
+  const samples = tools.filter((tool) => tool.endsWith("_sample"));
+  const sampleList = samples.length > 0 ? samples.join(", ") : "the *_sample";
+  return [
+    {
+      stage: 1,
+      tool: "capabilities",
+      purpose: "Understand conventions, available tools, and how to navigate",
+    },
+    {
+      stage: 2,
+      tool: "sources_status",
+      purpose:
+        "Confirm the store is built before any query. If it reports unavailable, call sources_update (confirm: true) first — otherwise the sample and domain reads below fail with STORE_UNAVAILABLE.",
+    },
+    {
+      stage: 3,
+      tool: "*_sample",
+      purpose: `Call ${sampleList} tools to see real data shapes before querying. Prevents guessing at property names.`,
+    },
+    {
+      stage: 4,
+      tool: "domain tools",
+      purpose:
+        "Query specific entities — block_list, standard_lookup, etc. Use the use_when hints above to pick the right tool.",
+    },
+  ];
+}
+
+/** Tally the catalog tools by category (all counts DERIVED, never pinned). */
+function countByCategory(tools: readonly CatalogTool[]): ToolCounts {
+  const of = (category: CatalogTool["category"]) =>
+    tools.filter((tool) => tool.category === category).length;
+  return {
+    total: tools.length,
+    read: of("read"),
+    write: of("write"),
+    orientation: of("orientation"),
+    diagnostic: of("diagnostic"),
+  };
+}
+
+/**
+ * Build the capabilities payload from a set of capability modules.
+ *
+ * @param modules - The live capability modules (passed in to avoid a static
+ *   self-cycle; the verb's `run` dynamic-imports the registry barrel).
+ * @returns The structured, self-consistent capabilities map.
+ */
+export function buildCapabilitiesData(
+  modules: readonly CapabilityModule[],
+): CapabilitiesData {
+  const tools = liveTools(modules);
+  const catalogTools: CatalogTool[] = tools.map((name) => {
+    const hint = TOOL_HINTS[name];
+    // A missing hint is a drift bug caught by `capabilities.test.ts`; degrade
+    // to a truthful placeholder rather than throwing inside a tool call.
+    return {
+      name,
+      category: hint?.category ?? "read",
+      use_when:
+        hint?.use_when ?? "(no hint authored — see capabilities/hints.ts)",
+    };
+  });
+
+  return {
+    version: VERSION,
+    conventions: CONVENTIONS,
+    discovery_sequence: buildDiscoverySequence(tools),
+    tools: catalogTools,
+    counts: countByCategory(catalogTools),
+    limits: { output_modes: OUTPUT_MODES, condensed_available: false },
+  };
+}
+
+export { mutatingTools };

package/src/capabilities/capabilities/hints.ts

@@ -0,0 +1,212 @@
+/**
+ * The one authored input to the `capabilities` catalog: a `use_when` behavioural
+ * hint + category per tool. Everything else (the tool SET, counts, discovery
+ * samples) is DERIVED from the live grammar at build time, so this table is the
+ * only thing to keep in sync — and the drift-guard test (`capabilities.test.ts`)
+ * fails CI if a live tool has no hint, a hint names a tool that no longer
+ * exists, or a hint's category disagrees with the tool's real `mutates` flag.
+ *
+ * `use_when` strings for the surviving tools are ported verbatim from the old
+ * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_set,
+ * graph_query, setup, upgrade, doctor, capabilities, prompt_*, token_add-config,
+ * sources_*, tier_lookup, create_*) are authored here.
+ */
+
+import type { ToolHint } from "./types.js";
+
+/**
+ * Behavioural hints keyed by the LIVE tool name (`emitSurface` naming rule:
+ * `noun` or `noun_verb`). Categories: `write` ⟺ the verb mutates; `orientation`
+ * = the session-start map; `diagnostic` = environment/version reporting; else
+ * `read`. The drift guard enforces every one of those invariants.
+ */
+export const TOOL_HINTS: Record<string, ToolHint> = {
+  // — Orientation ————————————————————————————————————————————————————————————
+  capabilities: {
+    category: "orientation",
+    use_when:
+      "Starting a session — understand conventions, available tools, and the discovery flow",
+  },
+
+  // — Diagnostic ————————————————————————————————————————————————————————————
+  doctor: {
+    category: "diagnostic",
+    use_when:
+      "Diagnosing environment issues — config, store, completions, MCP health",
+  },
+  info: {
+    category: "diagnostic",
+    use_when: "Checking pragma version, configuration summary, and store state",
+  },
+
+  // — Read ——————————————————————————————————————————————————————————————————
+  block_list: {
+    category: "read",
+    use_when:
+      "Browsing available components, patterns, layouts under current tier/channel",
+  },
+  block_lookup: {
+    category: "read",
+    use_when:
+      "Need full anatomy, modifiers, tokens, and standards for specific blocks by name or IRI",
+  },
+  block_sample: {
+    category: "read",
+    use_when:
+      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
+  },
+  colophon: {
+    category: "read",
+    use_when:
+      "Understanding how pragma and the active domain are built — the toolchain + design-system colophon, for onboarding or a demo",
+  },
+  config_show: {
+    category: "read",
+    use_when: "Checking active tier and channel before querying",
+  },
+  graph_inspect: {
+    category: "read",
+    use_when:
+      "Examining all triples for a specific URI — predicates, objects, and types",
+  },
+  graph_query: {
+    category: "read",
+    use_when:
+      "Complex SPARQL joins or aggregations that other tools cannot express",
+  },
+  modifier_list: {
+    category: "read",
+    use_when: "Listing all modifier families and their allowed values",
+  },
+  modifier_lookup: {
+    category: "read",
+    use_when:
+      "Need values and usage details for specific modifier families by name",
+  },
+  modifier_sample: {
+    category: "read",
+    use_when:
+      "See actual modifier data shapes (with value lists) before querying — returns random instances each call",
+  },
+  ontology_list: {
+    category: "read",
+    use_when:
+      "Discovering loaded namespaces, prefixes, and class/property counts",
+  },
+  ontology_lookup: {
+    category: "read",
+    use_when:
+      "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
+  },
+  ontology_show: {
+    category: "read",
+    use_when:
+      "Deprecated alias of ontology_lookup — exploring a namespace's schema (prefer ontology_lookup)",
+  },
+  prompt_list: {
+    category: "read",
+    use_when:
+      "Browsing the workflow prompt templates the design-system graph offers",
+  },
+  prompt_lookup: {
+    category: "read",
+    use_when:
+      "Fetching a specific workflow prompt template's body and arguments by name",
+  },
+  skill_list: {
+    category: "read",
+    use_when: "Discovering agent skills provided by installed packages",
+  },
+  skill_lookup: {
+    category: "read",
+    use_when:
+      "Loading full SKILL.md instructions for a specific agent skill by name",
+  },
+  sources_status: {
+    category: "read",
+    use_when:
+      "Checking whether the local knowledge-graph pack is built and current",
+  },
+  standard_list: {
+    category: "read",
+    use_when:
+      "Browsing code standards, optionally filtered by category or search term",
+  },
+  standard_lookup: {
+    category: "read",
+    use_when:
+      "Need do/don't code examples for specific coding standards by name or IRI",
+  },
+  standard_categories: {
+    category: "read",
+    use_when: "Discovering which standard categories exist before filtering",
+  },
+  standard_sample: {
+    category: "read",
+    use_when:
+      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
+  },
+  tier_list: {
+    category: "read",
+    use_when: "Understanding the tier hierarchy before setting a tier filter",
+  },
+  tier_lookup: {
+    category: "read",
+    use_when: "Need the blocks scoped to a specific tier by name",
+  },
+  token_list: {
+    category: "read",
+    use_when:
+      "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
+  },
+  token_lookup: {
+    category: "read",
+    use_when:
+      "Need theme values and resolution details for specific tokens by name or IRI",
+  },
+  token_sample: {
+    category: "read",
+    use_when:
+      "See actual token data shapes (with theme values) before querying — returns random instances each call",
+  },
+
+  // — Write ——————————————————————————————————————————————————————————————————
+  config_set: {
+    category: "write",
+    use_when:
+      "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
+  },
+  create_component: {
+    category: "write",
+    use_when:
+      "Scaffolding a new design-system component (React, Svelte, or Lit)",
+  },
+  create_package: {
+    category: "write",
+    use_when:
+      "Scaffolding a new npm package with proper monorepo configuration",
+  },
+  create_application: {
+    category: "write",
+    use_when:
+      "Scaffolding a new React application with SSR, routing, and optional Relay",
+  },
+  setup: {
+    category: "write",
+    use_when:
+      "Installing pragma's shell completions, MCP config, skills, and LSP into the environment",
+  },
+  sources_update: {
+    category: "write",
+    use_when:
+      "Building or refreshing the knowledge-graph pack from the configured packages",
+  },
+  "token_add-config": {
+    category: "write",
+    use_when: "Generating a tokens.config.mjs for the terrazzo token pipeline",
+  },
+  upgrade: {
+    category: "write",
+    use_when: "Upgrading the pragma CLI itself to the latest release",
+  },
+};

package/src/capabilities/capabilities/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The `capabilities` capability module — the grammar-derived orientation tool
+ * that replaces the retired `llm` tool.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { capabilitiesSelfVerb } from "./capabilities.verb.js";
+
+/** The `capabilities` capability module (a single storeless self-verb). */
+export const capabilitiesModule: CapabilityModule = {
+  name: "capabilities",
+  verbs: [capabilitiesSelfVerb],
+};

package/src/capabilities/capabilities/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for the `capabilities` orientation tool.
+ *
+ * The catalog is DERIVED from the live grammar (`emitSurface`) plus an authored
+ * hint table — never a hand-maintained tool list — so it cannot drift from the
+ * real surface (the exact failure mode of the old shell's `TOOL_CATALOG`, which
+ * still named retired tools). See {@link ToolHint} + `hints.ts` for the one
+ * authored input, and `catalog.ts` for the derivation.
+ */
+
+/** A tool's behavioural category, used for grouping + counts. */
+export type ToolCategory = "read" | "write" | "orientation" | "diagnostic";
+
+/** The one authored fact per tool: its category + a one-line "use when" hint. */
+export interface ToolHint {
+  readonly category: ToolCategory;
+  readonly use_when: string;
+}
+
+/** One tool as it appears in the catalog — its live name plus its hint. */
+export interface CatalogTool {
+  readonly name: string;
+  readonly category: ToolCategory;
+  readonly use_when: string;
+}
+
+/** A single stage in the discovery flow an agent follows at session start. */
+export interface DiscoveryStage {
+  readonly stage: number;
+  readonly tool: string;
+  readonly purpose: string;
+}
+
+/** Tool counts by category (all DERIVED from the live catalog, never pinned). */
+export interface ToolCounts {
+  readonly total: number;
+  readonly read: number;
+  readonly write: number;
+  readonly orientation: number;
+  readonly diagnostic: number;
+}
+
+/** The structured system map returned by the `capabilities` tool. */
+export interface CapabilitiesData {
+  readonly version: string;
+  readonly conventions: {
+    readonly system: string;
+    readonly model: string;
+    readonly querying: string;
+    /** The plan-first/confirm gate every mutating tool follows (D2). */
+    readonly mutations: string;
+  };
+  readonly discovery_sequence: readonly DiscoveryStage[];
+  readonly tools: readonly CatalogTool[];
+  readonly counts: ToolCounts;
+  readonly limits: {
+    readonly output_modes: readonly string[];
+    readonly condensed_available: boolean;
+  };
+}

package/src/capabilities/colophon/collectColophon.ts

@@ -0,0 +1,68 @@
+/**
+ * Collect the `colophon` payload — the verb's run body (lazily imported).
+ *
+ * STORELESS: it reads the layered config (memoized) and resolves the EFFECTIVE
+ * capability modules exactly as a real command would, so a config story that
+ * overrides a bundled pack is reflected here — "active domain" is expressed the
+ * way the rest of the CLI expresses it. It never boots the triple store, so the
+ * storeless-guarantee spy still sees `store.booted === false`.
+ *
+ * The registry is reached through a RUNTIME dynamic `import("../index.js")`
+ * inside this async body — never a static import — so the static
+ * `index → colophonModule → index` cycle can never form. Do NOT "clean it up"
+ * into a static import.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { PRAGMA_COLOPHON, PRAGMA_COLOPHON_SUMMARY } from "./pragmaColophon.js";
+import type { ColophonData, ColophonSection } from "./types.js";
+
+/**
+ * Assemble the colophon data for the current runtime.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns The storeless colophon payload: pragma's section, then each active
+ *   pack/domain that declares a `colophon`.
+ * @note Impure — reads the config layers (never boots the store).
+ */
+export async function collectColophon(
+  runtime: PragmaRuntime,
+): Promise<ColophonData> {
+  const sections: ColophonSection[] = [
+    {
+      kind: "pragma",
+      title: "pragma",
+      markdown: PRAGMA_COLOPHON,
+      summary: PRAGMA_COLOPHON_SUMMARY,
+      source: "built-in",
+    },
+  ];
+
+  const { assembleEffectiveModules } = await import(
+    "../../kernel/packs/collect.js"
+  );
+  const { capabilities } = await import("../index.js");
+
+  let modules: readonly CapabilityModule[] = capabilities;
+  try {
+    const layers = await runtime.loadConfig();
+    modules = assembleEffectiveModules(capabilities, layers);
+  } catch {
+    // A bad config story is surfaced by the real commands; the colophon degrades
+    // to the static (bundled) modules rather than failing the narrative.
+  }
+
+  for (const module of modules) {
+    if (module.colophon) {
+      sections.push({
+        kind: "pack",
+        title: module.name,
+        markdown: module.colophon,
+        source: `pack:${module.name}`,
+      });
+    }
+  }
+
+  return { sections };
+}

package/src/capabilities/colophon/colophon.render.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Render golden for `pragma colophon`.
+ *
+ * Forces `chalk.level = 0` for a deterministic, color-free proof of the plain
+ * Markdown→terminal styling (headings, bullets, inline `**bold**`/`` `code` ``
+ * consumed) and the llm condensed passthrough (`summary ?? markdown`, no color),
+ * plus one assertion that color-ON emits an ANSI escape. This is the
+ * "human-styled / condensed-for-llm" render model in one file.
+ */
+
+import chalk from "chalk";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { colophonFormatters } from "./colophon.render.js";
+import type { ColophonData } from "./types.js";
+
+/** A tiny, fixed two-section fixture (double-quoted so backticks stay literal). */
+const FIXTURE: ColophonData = {
+  sections: [
+    {
+      kind: "pragma",
+      title: "pragma",
+      markdown: "How it is **made**.\n\n## Effects\n- describe\n- interpret",
+      summary: "condensed",
+      source: "built-in",
+    },
+    {
+      kind: "pack",
+      title: "block",
+      markdown: "The `ds:` domain.",
+      source: "pack:block",
+    },
+  ],
+};
+
+let prevLevel: number;
+beforeAll(() => {
+  prevLevel = chalk.level;
+});
+afterAll(() => {
+  chalk.level = prevLevel;
+});
+
+describe("colophon render golden — color-free (chalk.level = 0)", () => {
+  it("plain styles the title/heading/bullets and consumes inline markers", () => {
+    chalk.level = 0;
+    const expected = [
+      "pragma",
+      "",
+      "How it is made.",
+      "",
+      "Effects",
+      "  • describe",
+      "  • interpret",
+      "",
+      "block",
+      "",
+      "The ds: domain.",
+    ].join("\n");
+    expect(colophonFormatters.plain(FIXTURE)).toBe(expected);
+  });
+
+  it("llm emits condensed Markdown (summary preferred, no color)", () => {
+    chalk.level = 0;
+    const expected = [
+      "## pragma",
+      "",
+      "condensed",
+      "",
+      "## block",
+      "",
+      "The `ds:` domain.",
+    ].join("\n");
+    expect(colophonFormatters.llm(FIXTURE)).toBe(expected);
+  });
+
+  it("json is the exact ColophonData round-trip", () => {
+    expect(JSON.parse(colophonFormatters.json(FIXTURE))).toEqual(FIXTURE);
+  });
+});
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+describe("colophon render — color ON (attended TTY)", () => {
+  it("plain emits ANSI escapes on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(colophonFormatters.plain(FIXTURE)).toMatch(/\x1b\[/);
+    });
+  });
+});
+
+describe("colophon render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    // The CI leak: `supports-color` sets a non-zero level off a TTY under
+    // GITHUB_ACTIONS / FORCE_COLOR, so gating on `chalk.level` alone bled ANSI
+    // into `colophon --format plain | tee`. The isTTY gate closes it.
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(colophonFormatters.plain(FIXTURE)).not.toMatch(/\x1b\[/);
+    });
+  });
+});