@canonical/pragma-cli 0.31.0 → 0.33.0

package/README.md

@@ -1,457 +1,71 @@
 # @canonical/pragma-cli
 
-CLI and MCP server for Canonical's design system. Query blocks, standards, modifiers, tokens, tiers, ontologies, and skills from the terminal or your AI editor.
+`pragma` is a command-line tool **and** a Model Context Protocol (MCP) server over Canonical's design-system knowledge graph. A single grammar of capabilities is projected two ways — as CLI commands for humans and as MCP tools for agents — both reading the same local, content-addressed store built from your design-system packages.
 
-## Installation
+## Install
 
 ```bash
-bun add -g @canonical/pragma-cli
+npm install -g @canonical/pragma-cli
 ```
 
-## Quick Start
+This installs the `pragma` binary: a prebuilt, standalone executable (`dist/pragma`). The package publishes for **Linux x64 only** (`"os": ["linux"]`, `"cpu": ["x64"]`) — other platforms are not yet shipped.
 
-```bash
-pragma --help                     # Show all commands
-pragma block list                 # List design system blocks
-pragma block lookup Button        # Detailed block info
-pragma standard list              # List code standards
-pragma setup mcp                  # Configure MCP for your editor
-```
-
-See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
-
-## CLI Commands
-
-pragma organizes commands into 17 domains — counting every directory under `src/domains/` except `shared/`, which holds cross-domain infrastructure rather than commands. The day-to-day domains are documented below; two are specialised and not covered here: `graphql` (compile TTL ontologies into GraphQL schema artifacts) and `trace` (query access tracing). Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
-
-### Block
-
-| Command | Description |
-|---------|-------------|
-| `pragma block list` | List all blocks (components) visible under current tier/channel |
-| `pragma block lookup <name>` | Show detailed block info: anatomy, modifiers, tokens, standards |
-
-### Standard
-
-| Command | Description |
-|---------|-------------|
-| `pragma standard list` | List all code standards |
-| `pragma standard lookup <name>` | Show standard details (`--detailed` adds do/don't examples) |
-| `pragma standard categories` | List standard categories with counts |
-
-### Modifier
-
-| Command | Description |
-|---------|-------------|
-| `pragma modifier list` | List all modifier families |
-| `pragma modifier lookup <name>` | Show modifier family with values |
-
-### Tokens
-
-| Command | Description |
-|---------|-------------|
-| `pragma tokens add-config` | Add Terrazzo config for token build |
-
-> **Note:** The token *read* commands (`token list`, `token lookup`, `token sample`)
-> are currently disabled behind a feature flag
-> (`src/domains/token/featureFlag.ts`) because the published design-system
-> data does not yet contain token instances. They will return once token
-> data ships.
-
-### Tier
-
-| Command | Description |
-|---------|-------------|
-| `pragma tier list` | List all tiers in the tier hierarchy |
-
-### Ontology
-
-| Command | Description |
-|---------|-------------|
-| `pragma ontology list` | List loaded ontology namespaces |
-| `pragma ontology show <prefix>` | Show the TBox: name, metadata, class hierarchy tree with instance counts and relations |
-| `pragma ontology show <prefix> --properties` | Also show datatype properties (attributes) |
-| `pragma ontology show <prefix> --full-uris` | Show full URIs instead of compact prefixed IRIs |
-| `pragma ontology show <prefix> --class <Class>` | Deep-dive into one class: super chain, direct/inherited properties, reverse references, sample instances, and ready-to-run follow-up queries |
-
-### Graph
-
-| Command | Description |
-|---------|-------------|
-| `pragma graph query <sparql>` | Execute a raw SPARQL query against the ke store |
-| `pragma graph inspect <uri>` | Inspect all triples for a given URI |
-
-### Config
-
-| Command | Description |
-|---------|-------------|
-| `pragma config show` | Show current configuration (tier, channel) |
-| `pragma config tier <path>` | Set the project's tier |
-| `pragma config channel <name>` | Set the release channel |
-
-### Skill
-
-| Command | Description |
-|---------|-------------|
-| `pragma skill list` | List discovered agent skills from installed packages |
-| `pragma skill lookup <name...>` | Show full SKILL.md instructions for skills by name |
-
-### LLM
-
-| Command | Description |
-|---------|-------------|
-| `pragma llm` | Print LLM orientation context (decision trees, command reference) |
-
-### Setup
-
-All setup commands support `--dry-run`; `--yes` and `--undo` are supported
-where shown below.
-
-| Command | Description |
-|---------|-------------|
-| `pragma setup` | Run all setup steps (completions + LSP + MCP); supports `--yes`, `--undo` |
-| `pragma setup mcp` | Configure pragma MCP server for AI harnesses; supports `--yes`, `--undo` |
-| `pragma setup completions` | Install shell completions (bash/zsh/fish); supports `--undo` |
-| `pragma setup skills` | Symlink agent skills into harness config; supports `--yes` |
-| `pragma setup lsp` | Install the Terrazzo LSP VS Code extension; supports `--undo` |
-
-### Create
-
-Create commands scaffold new code using summon generators. They support `--undo` to reverse.
-
-| Command | Description |
-|---------|-------------|
-| `pragma create component <framework> [path]` | Scaffold a new design system component |
-| `pragma create package` | Scaffold a new monorepo package (`--name`, `--type`, …) |
-| `pragma create application [path]` | Scaffold a complete React application with SSR and routing |
-
-### Doctor
-
-| Command | Description |
-|---------|-------------|
-| `pragma doctor` | Run diagnostic checks on your pragma installation |
-
-### Info
-
-| Command | Description |
-|---------|-------------|
-| `pragma info` | Show pragma version, config, update status, and store summary |
-
-### Upgrade
-
-| Command | Description |
-|---------|-------------|
-| `pragma upgrade` | Upgrade the pragma CLI to the latest version (`--dry-run` to check only) |
-
-### Refs
-
-| Command | Description |
-|---------|-------------|
-| `pragma update-refs` | Fetch or clone git-referenced semantic packages into the local cache (needed before `skill list` can discover skills) |
-
-## Global Flags
-
-| Flag | Description |
-|------|-------------|
-| `--llm` | Condensed Markdown output for LLM consumption |
-| `--format json` | Structured JSON output |
-| `--verbose` | Diagnostic output to stderr |
-
-## The `--undo` Flag
-
-Setup and create commands support `--undo` to reverse previous operations. The undo interpreter walks the task tree produced by the original command, collects all registered undo steps, and executes them in reverse order.
+Check your environment and confirm the install:
 
 ```bash
-pragma setup mcp --undo             # Remove MCP configuration
-pragma setup completions --undo     # Remove shell completions
-pragma create component react src/lib/Foo --undo  # Remove scaffolded component files
+pragma doctor
 ```
 
-## MCP Integration
-
-pragma ships a built-in MCP server accessible via `pragma mcp` (stdio transport). See [docs/mcp-integration.md](docs/mcp-integration.md) for the complete integration guide.
-
-### Setup
+## Quickstart
 
 ```bash
-pragma setup mcp                 # Auto-detect harness and configure
-pragma setup mcp --claude-code   # Configure for Claude Code only
-pragma setup mcp --cursor        # Configure for Cursor only
-pragma setup mcp --windsurf      # Configure for Windsurf only
-```
-
-Or add manually to your `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "pragma": {
-      "command": "pragma",
-      "args": ["mcp"],
-      "type": "stdio"
-    }
-  }
-}
-```
-
-### MCP Tools (28)
-
-All tools return a consistent envelope: `{ ok: true, data, meta }` for success, `{ ok: true, condensed: true, text, tokens }` for condensed mode, or `{ ok: false, error }` with structured recovery on failure.
-
-#### Read Tools (18)
-
-Lookup tools accept a `names` array, so several entities can be fetched in
-one call (partial results are returned alongside per-name errors).
-
-| Tool | Description |
-|------|-------------|
-| `block_list` | List blocks with optional tier filtering and disclosure levels |
-| `block_lookup` | Look up detailed block info (anatomy, modifiers, tokens, standards) |
-| `block_sample` | Return random complete block instances for shape discovery |
-| `standard_list` | List code standards with optional category/search filtering |
-| `standard_lookup` | Look up standard with do/don't code examples |
-| `standard_categories` | List standard categories with counts |
-| `standard_sample` | Return random complete standard instances for shape discovery |
-| `modifier_list` | List modifier families |
-| `modifier_lookup` | Look up modifier family with values |
-| `modifier_sample` | Return random complete modifier instances for shape discovery |
-| `tier_list` | List all tiers in the hierarchy |
-| `config_show` | Show current tier and channel configuration |
-| `ontology_list` | List loaded ontology namespaces with class/property counts |
-| `ontology_show` | Show classes and properties for a namespace |
-| `graph_query` | Execute raw SPARQL against the ke store |
-| `graph_inspect` | Inspect all triples for a URI |
-| `skill_list` | List discovered agent skills |
-| `skill_lookup` | Get full SKILL.md content for skills by name |
-
-`token_list`, `token_lookup`, and `token_sample` are feature-flagged off
-until token data ships (see the Tokens note above).
-
-#### Write Tools (6)
-
-| Tool | Description |
-|------|-------------|
-| `config_tier` | Set the project's tier |
-| `config_channel` | Set the release channel |
-| `tokens_add_config` | Add Terrazzo token build configuration |
-| `create_component` | Scaffold a new design system component |
-| `create_package` | Scaffold a new monorepo package |
-| `create_application` | Scaffold a complete React application |
-
-#### Orientation Tools (2)
-
-| Tool | Description |
-|------|-------------|
-| `capabilities` | List all available tools with category counts (~100 tokens) |
-| `llm` | Get full LLM orientation: context, decision trees, command reference |
-
-#### Diagnostic Tools (2)
-
-| Tool | Description |
-|------|-------------|
-| `doctor` | Run installation diagnostic checks |
-| `info` | Show version, store summary, installed packages |
-
-### Envelope Format
-
-Every MCP tool response is wrapped by `wrapTool` into one of three envelopes:
-
-**Success (structured):**
-```json
-{ "ok": true, "data": { ... }, "meta": { "count": 42, "filters": {} } }
-```
-
-**Success (condensed):**
-```json
-{ "ok": true, "condensed": true, "text": "...", "tokens": "~1.2k" }
-```
-
-**Error (structured recovery):**
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "ENTITY_NOT_FOUND",
-    "message": "block \"Buton\" not found.",
-    "suggestions": ["Button", "ButtonGroup"],
-    "recovery": { "tool": "block_list" }
-  }
-}
-```
-
-### Disclosure Levels
-
-List tools support disclosure levels that control response verbosity:
-
-- **summary** (default) — names and metadata only
-- **digest** — summary plus implementation paths and key details
-- **detailed** — full entity data including anatomy, tokens, and standards
-
-### Condensed Mode
-
-Pass `condensed: true` to any read tool to receive token-optimized Markdown instead of structured JSON. The condensed output reuses the `--llm` formatter, keeping responses compact for token-budgeted agents.
-
-### Structured Recovery
-
-Error responses include a `recovery` object that tells agents what tool to call next:
-
-```json
-{
-  "recovery": {
-    "tool": "block_list",
-    "params": { "names": ["Button"] }
-  }
-}
+pragma sources update
+pragma sources status
+pragma block list
+pragma block lookup Button
+pragma capabilities
 ```
 
-### Batch Results
+`pragma sources update` resolves the design-system packages named in your `pragma.config.ts`, builds one local store, and writes `pragma.lock.json`. Once built, every read command answers from the store with no network access.
 
-Lookup tools accept a `names` array and return partial results — valid items in `results`, failures in `errors`:
+To register pragma with a detected AI harness as an MCP server:
 
-```json
-{
-  "results": [{ "name": "Button", ... }],
-  "errors": [{ "query": "Buton", "code": "ENTITY_NOT_FOUND", "message": "...", "suggestions": ["Button"] }]
-}
-```
-
-### MCP Resources
-
-Every subject URI in the ke graph is exposed as a discoverable MCP resource via the `pragma:{uri}` template. Reading a resource returns all properties with level-1 object relations resolved to summaries.
-
-## Configuration
-
-Configuration is layered: built-in defaults, then the global file at
-`$XDG_CONFIG_HOME/pragma/config.json` (default `~/.config/pragma/config.json`),
-then the nearest `pragma.config.json` at or above the current directory —
-each field won by the most specific layer that sets it. Install pragma
-globally, configure once, and override per project:
-
-```json
-{
-  "tier": "apps/lxd",
-  "channel": "normal"
-}
-```
-
-`pragma config tier|channel|framework|trace` writes to the nearest existing
-project file, or to the global file when no project is configured; pass
-`--local` or `--global` to pick the layer explicitly. Every write echoes the
-file it wrote, and `pragma config show` reports which layer supplied each
-value.
-
-### Custom read stories (experimental)
-
-A config (or a semantic package, via `stories/*.json`) can declare
-declarative read stories — any ontology loaded through `packages` gets
-`pragma <noun> list` / `<noun> lookup` on both the CLI and MCP:
-
-```json
-{
-  "prefixes": { "ex": "http://example.org/recipes/" },
-  "packages": [{ "name": "my-recipes", "source": "file:///data/recipes" }],
-  "stories": [
-    {
-      "noun": "recipe",
-      "description": "List recipes",
-      "list": {
-        "query": "SELECT ?uri ?name ?category WHERE { ?uri a ex:Recipe ; ex:name ?name ; ex:category ?category } ORDER BY ?name",
-        "columns": [{ "field": "name" }, { "field": "category" }],
-        "filters": [
-          { "param": "category", "variable": "category", "values": ["breakfast", "soup"] }
-        ]
-      },
-      "lookup": {
-        "type": "ex:Recipe",
-        "by": "ex:name",
-        "fields": [{ "name": "category", "property": "ex:category" }],
-        "sections": [{ "name": "instructions", "property": "ex:instructions" }]
-      }
-    }
-  ]
-}
-```
-
-The lookup query is generated (user input is escaped, never interpolated by
-the pack), the store stays read-only, and config-declared stories override
-package-shipped ones on noun collisions. Declared `filters` become
-`pragma recipe list --category soup` on the CLI and an enum parameter on the
-MCP tool; they are row predicates applied after the query runs, so filter
-input can never inject SPARQL and the query's ordering is preserved. The
-format is experimental and may change.
-
-## Error Handling
-
-Lookup errors report each failed name with typo suggestions:
-
-```
-**Errors:**
-- Buton: block "Buton" not found.
-  Did you mean: Button?
-```
-
-Other errors carry a code and, where available, a recovery hint:
-
-```
-## Error: EMPTY_RESULTS
-No standards found.
-Filters: category=nope
-Recovery: `pragma standard list`
+```bash
+pragma setup mcp
 ```
 
-With `--format json`, errors are returned as structured JSON with error code, suggestions, and recovery. With `--llm`, errors are rendered as Markdown.
-
-## Exit Codes
+See [docs/mcp-integration.md](./docs/mcp-integration.md) for the full MCP surface, and the [command & tool reference](./docs/reference/index.md) for every command and tool.
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Entity not found |
-| 2 | Empty results |
-| 3 | Invalid or ambiguous input |
-| 4 | Configuration error |
-| 5 | Store error |
-| 127 | Internal error |
+## Two planes
 
-## Architecture
+pragma is extended along two independent planes:
 
-pragma is structured as a domain-driven application using the federation pattern from `@canonical/cli-core`:
+- **Data plane — the content.** Your design system is a set of semantic packages listed in `pragma.config.ts` (`packages: [...]`). `pragma sources update` compiles them into the local knowledge graph the read commands query. Point pragma at different packages and every `list` / `lookup` / `sample` command answers from that graph.
+- **Behaviour plane — the capabilities.** Every command and MCP tool is one entry in a single capability grammar, projected to both the CLI and the MCP server. The [reference](./docs/reference/index.md) is generated from that grammar, so it can never drift from the code.
 
-1. **Domains** — 17 domain modules (block, config, create, doctor, graph, graphql, info, llm, modifier, ontology, refs, setup, skill, standard, tier, token, trace — every directory under `src/domains/` except the `shared/` infrastructure folder), each contributing `CommandDefinition`s
-2. **Operations** — data retrieval functions that query the ke triple store via SPARQL
-3. **Formatters** — three-mode output adapters (plain/llm/json) for each operation
-4. **Commands** — thin wiring layer connecting Commander.js parameters to operations + formatters
-5. **MCP tools** — parallel surface that reuses the same operations, with `wrapTool` envelope construction
-6. **Pipeline** — `runCli` orchestrates boot, flag parsing, command resolution, and program execution
+## Relationship to summon
 
-The ke store (Oxigraph WASM) holds RDF data from three packages: `@canonical/design-system` (ontology + component data), `@canonical/code-standards` (standard definitions + examples), and `@canonical/anatomy-dsl` (anatomy definitions).
-
-## Scripts
+`@canonical/summon` is a separate scaffolding product. pragma reuses summon's generator core so that its scaffolding commands —
 
 ```bash
-bun run check          # biome + tsc + webarchitect
-bun run test           # vitest
-bun run build:compile  # bun build --compile (produces dist/pragma)
-bun run test:compile   # WASM embedding validation
+pragma create component src/components/Button --framework react
 ```
 
-## Compiled Binary
+— produce output byte-identical to summon's own `component`, `package`, and `application` generators. summon is not a runtime dependency: the generators are embedded in the `pragma` binary, so `pragma create component` runs from a clean install.
 
-pragma targets a compiled single-file executable via `bun build --compile`. The Oxigraph WASM module embeds automatically — no manual embedding or side-loading required.
+## MCP
 
-```bash
-bun build --compile --minify src/bin.ts --outfile dist/pragma
-```
+Run pragma as an MCP server over stdio via `pragma setup mcp` (automatic harness registration) or the manual `pragma mcp` entry point. The server exposes the read and scaffold tools, a `pragma:{+uri}` resource surface for entity reads, the design system's workflow prompts, and handshake instructions describing the discovery sequence. Mutating tools are plan-first — they return the plan they would apply until called with `confirm: true`. See [docs/mcp-integration.md](./docs/mcp-integration.md).
 
-## Dependencies
+## Documentation
 
-- [`@canonical/ke`](../../runtime/ke/) — triple store runtime (Oxigraph WASM)
-- [`@canonical/cli-core`](../core/) — shared CLI machinery (Commander.js registration, help formatting)
-- [`@canonical/task`](../../runtime/task/) — reversible task trees for setup/create with undo support
-- [`@canonical/harnesses`](../../runtime/harnesses/) — AI harness detection (Claude Code, Cursor, Windsurf)
-- [`@canonical/summon-core`](../../summon/core/) — code generation runtime
-- [`@canonical/summon-component`](../../summon/component/) — component generator
-- [`@canonical/summon-package`](../../summon/package/) — package generator
+- [Getting started](./docs/getting-started.md)
+- [MCP integration](./docs/mcp-integration.md)
+- [Configuration model](./docs/config-model.md)
+- [Architecture](./docs/architecture.md)
+- [Skills](./docs/skills.md)
+- [Command & tool reference](./docs/reference/index.md)
+- [Changelog](./CHANGELOG.md)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
-  "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.31.0",
+  "description": "Next-generation CLI and MCP kernel for Canonical's design system (pragma v2).",
+  "version": "0.33.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -31,66 +31,52 @@
     "url": "https://github.com/canonical/pragma/issues"
   },
   "homepage": "https://github.com/canonical/pragma#readme",
-  "imports": {
-    "#config": "./src/config/index.ts",
-    "#constants": "./src/constants.ts",
-    "#error": "./src/error/index.ts",
-    "#package-manager": "./src/package-manager/index.ts",
-    "#pipeline": "./src/pipeline/index.ts",
-    "#testing": "./src/testing/index.ts",
-    "#tui": "./src/tui/index.ts"
-  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
+    "gen:reference": "bun run scripts/genReference.ts",
     "build:compile": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
-    "prepublishOnly": "bun run build",
     "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
     "check:webarchitect": "webarchitect tool-ts",
     "check:fix": "bun run check:biome:fix && bun run check:ts",
     "check:biome": "biome check",
     "check:biome:fix": "biome check --write",
     "check:ts": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "bun run test:vitest && bun run test:perf",
+    "test:vitest": "vitest run --coverage",
+    "test:perf": "vitest run --config vitest.perf.config.ts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:compile": "bun run src/compile-validation.runner.ts"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.31.0",
-    "@canonical/typescript-config": "^0.31.0",
-    "@canonical/webarchitect": "^0.31.0",
-    "@types/bun": "^1.3.10",
-    "@types/node": "^24.12.0",
-    "@types/react": "^19.2.14",
-    "expect-type": "^1.3.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "eval": "bun run src/testing/eval/report.ts"
   },
   "dependencies": {
-    "@canonical/anatomy-dsl": "^0.2.2",
-    "@canonical/cli-core": "^0.31.0",
-    "@canonical/code-standards": "^0.1.2",
-    "@canonical/design-system": "^0.1.2",
-    "@canonical/harnesses": "^0.31.0",
-    "@canonical/ke": "^0.31.0",
-    "@canonical/ke-graphql": "^0.31.0",
-    "@canonical/summon": "^0.31.0",
-    "@canonical/summon-application": "^0.31.0",
-    "@canonical/summon-component": "^0.31.0",
-    "@canonical/summon-core": "^0.31.0",
-    "@canonical/summon-package": "^0.31.0",
-    "@canonical/task": "^0.31.0",
+    "@canonical/harnesses": "^0.33.0",
+    "@canonical/ke": "^0.33.0",
+    "@canonical/ke-graphql": "^0.33.0",
+    "@canonical/summon-application": "^0.33.0",
+    "@canonical/summon-component": "^0.33.0",
+    "@canonical/summon-core": "^0.33.0",
+    "@canonical/summon-package": "^0.33.0",
+    "@canonical/task": "^0.33.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "ink": "^6.8.0",
+    "graphql": "17.0.0-rc.0",
     "oxigraph": "^0.5.0",
-    "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "d4a67ebe42e62b8cf3de77f42f537309ca88d672"
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@canonical/biome-config": "^0.33.0",
+    "@canonical/typescript-config": "^0.33.0",
+    "@canonical/webarchitect": "^0.33.0",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "gitHead": "fca2bc4440fff2d511fc8db6686f9b19222fdbc7"
 }