@canonical/pragma-cli 0.18.0

package/README.md

@@ -0,0 +1,377 @@
+# @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.
+
+## Installation
+
+```bash
+bun add -g @canonical/pragma-cli
+```
+
+## Quick Start
+
+```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 14 domains. 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 with 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 |
+
+### Token
+
+| Command | Description |
+|---------|-------------|
+| `pragma token list` | List all design tokens |
+| `pragma token lookup <name>` | Show token with theme values |
+| `pragma token add-config` | Add Terrazzo config for token build |
+
+### 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 classes and properties for a namespace |
+
+### 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 |
+
+### LLM
+
+| Command | Description |
+|---------|-------------|
+| `pragma llm` | Print LLM orientation context (decision trees, command reference) |
+
+### Setup
+
+All setup commands support `--dry-run`, `--yes`, and `--undo`.
+
+| Command | Description |
+|---------|-------------|
+| `pragma setup all` | Run all setup steps (MCP + completions + skills) |
+| `pragma setup mcp` | Configure pragma MCP server for AI harnesses |
+| `pragma setup completions` | Install shell completions (bash/zsh/fish) |
+| `pragma setup skills` | Symlink agent skills into harness config |
+| `pragma setup lsp` | Configure LSP integration |
+
+### Create
+
+Create commands scaffold new code using summon generators. They support `--undo` to reverse.
+
+| Command | Description |
+|---------|-------------|
+| `pragma create component <name>` | Scaffold a new design system component |
+| `pragma create package <name>` | Scaffold a new monorepo package |
+
+### Doctor
+
+| Command | Description |
+|---------|-------------|
+| `pragma doctor` | Run diagnostic checks on your pragma installation |
+
+### Info
+
+| Command | Description |
+|---------|-------------|
+| `pragma info` | Show pragma version, store summary, installed packages |
+| `pragma info upgrade` | Check for newer pragma versions on the registry |
+
+## 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.
+
+```bash
+pragma setup mcp --undo             # Remove MCP configuration
+pragma setup completions --undo     # Remove shell completions
+pragma create component Foo --undo  # Remove scaffolded component files
+```
+
+## 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
+
+```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 (29)
+
+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 (20)
+
+| 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_batch_lookup` | Look up multiple blocks by name in a single call |
+| `standard_list` | List code standards with optional category/search filtering |
+| `standard_lookup` | Look up standard with do/don't code examples |
+| `standard_batch_lookup` | Look up multiple standards by name in a single call |
+| `standard_categories` | List standard categories with counts |
+| `modifier_list` | List modifier families |
+| `modifier_lookup` | Look up modifier family with values |
+| `modifier_batch_lookup` | Look up multiple modifier families by name in a single call |
+| `token_list` | List design tokens with optional category filtering |
+| `token_lookup` | Look up token with theme-resolved values |
+| `token_batch_lookup` | Look up multiple tokens by name in a single call |
+| `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 |
+
+#### Write Tools (5)
+
+| 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 |
+
+#### 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"] }
+  }
+}
+```
+
+### Batch Results
+
+List tools that accept a `names` filter return partial results — valid items in `results`, failures in `errors`:
+
+```json
+{
+  "results": [{ "name": "Button", ... }],
+  "errors": [{ "name": "Buton", "code": "ENTITY_NOT_FOUND", "message": "..." }]
+}
+```
+
+### 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
+
+Create a `pragma.config.toml` in your project root:
+
+```toml
+tier = "apps/lxd"
+channel = "normal"    # normal | experimental | prerelease
+```
+
+When no config file is present, pragma defaults to no tier and `normal` channel.
+
+## Error Handling
+
+Errors follow a three-part structure: message, context (suggestions or valid options), and recovery hint.
+
+```
+Error: block "Buton" not found.
+
+Did you mean?
+  - Button
+  - ButtonGroup
+
+Run `pragma block list`
+```
+
+With `--format json`, errors are returned as structured JSON with error code, suggestions, and recovery. With `--llm`, errors are rendered as Markdown.
+
+## Exit Codes
+
+| 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 |
+
+## Architecture
+
+pragma is structured as a domain-driven application using the federation pattern from `@canonical/cli-core`:
+
+1. **Domains** — 14 domain modules (block, standard, modifier, token, tier, ontology, graph, config, skill, llm, setup, create, doctor, info), each exporting `CommandDefinition[]`
+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
+
+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
+
+```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
+```
+
+## Compiled Binary
+
+pragma targets a compiled single-file executable via `bun build --compile`. The Oxigraph WASM module embeds automatically — no manual embedding or side-loading required.
+
+```bash
+bun build --compile --minify src/bin.ts --outfile dist/pragma
+```
+
+## Dependencies
+
+- [`@canonical/ke`](../runtime/ke/) — triple store runtime (Oxigraph WASM)
+- [`@canonical/cli-core`](../core/) — shared CLI machinery (Commander.js registration, help formatting)
+- [`@canonical/task`](../../lib/task/) — reversible task trees for setup/create with undo support
+- [`@canonical/harnesses`](../../lib/harnesses/) — AI harness detection (Claude Code, Cursor, Windsurf)
+- [`@canonical/summon-core`](../../lib/summon-core/) — code generation runtime
+- [`@canonical/summon-component`](../../lib/summon-component/) — component generator
+- [`@canonical/summon-package`](../../lib/summon-package/) — package generator
+
+## License
+
+GPL-3.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@canonical/pragma-cli",
+  "description": "CLI and MCP server for Canonical's design system.",
+  "version": "0.18.0",
+  "type": "module",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "pragma": "src/bin.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "author": {
+    "email": "webteam@canonical.com",
+    "name": "Canonical Webteam"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/canonical/pragma"
+  },
+  "license": "GPL-3.0",
+  "bugs": {
+    "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"
+  },
+  "scripts": {
+    "build": "echo 'No build needed - runs directly from TypeScript'",
+    "build:compile": "bun build --compile --minify src/bin.ts --outfile dist/pragma",
+    "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:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:compile": "bun run src/compile-validation.runner.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.6",
+    "@canonical/biome-config": "^0.18.0",
+    "@canonical/typescript-config": "^0.18.0",
+    "@canonical/webarchitect": "^0.18.0",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^24.12.0",
+    "expect-type": "^1.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "optionalDependencies": {
+    "@canonical/anatomy-dsl": "^0.2.2",
+    "@canonical/code-standards": "^0.1.2",
+    "@canonical/design-system": "^0.1.2"
+  },
+  "dependencies": {
+    "@canonical/cli-core": "^0.18.0",
+    "@canonical/harnesses": "^0.18.0",
+    "@canonical/ke": "^0.18.0",
+    "@canonical/summon-component": "^0.18.0",
+    "@canonical/summon-core": "^0.18.0",
+    "@canonical/summon-package": "^0.18.0",
+    "@canonical/task": "^0.18.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "zod": "^3.25.0"
+  }
+}

package/src/bin.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const detectLocalInstallMock = vi.fn();
+const runCliMock = vi.fn(async () => undefined);
+
+vi.mock("./package-manager/index.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./package-manager/index.js")>()),
+  detectLocalInstall: detectLocalInstallMock,
+}));
+
+vi.mock("./pipeline/runCli.js", () => ({
+  default: runCliMock,
+}));
+
+describe("bin", () => {
+  const originalArgv = process.argv;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.argv = ["bun", "pragma", "block", "list"];
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+  });
+
+  it("warns when a local install is detected and forwards argv to runCli", async () => {
+    vi.resetModules();
+    detectLocalInstallMock.mockReturnValue("Use local pragma install");
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await import("./bin.ts");
+
+    expect(warnSpy).toHaveBeenCalledWith("Use local pragma install");
+    expect(runCliMock).toHaveBeenCalledWith(process.argv);
+
+    warnSpy.mockRestore();
+  });
+
+  it("does not warn when no local install warning is needed", async () => {
+    vi.resetModules();
+    detectLocalInstallMock.mockReturnValue(undefined);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await import("./bin.ts");
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(runCliMock).toHaveBeenCalledWith(process.argv);
+
+    warnSpy.mockRestore();
+  });
+});

package/src/bin.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for `pragma`.
+ *
+ * Detects local vs global install, warns if shadowed, then delegates
+ * to the pipeline orchestrator.
+ *
+ * @note Impure
+ */
+
+import { detectLocalInstall } from "./package-manager/index.js";
+import runCli from "./pipeline/runCli.js";
+
+const localWarning = detectLocalInstall();
+if (localWarning) {
+  console.warn(localWarning);
+}
+
+await runCli(process.argv);

package/src/compile-validation.runner.ts

@@ -0,0 +1,137 @@
+/**
+ * E1 WASM Embedding Validation — Compile Test Runner
+ *
+ * Compiles the pragma validation binary via `bun build --compile`, executes it,
+ * and verifies that Oxigraph WASM loads and queries correctly inside the
+ * compiled executable.
+ *
+ * Run: `bun run src/compile-validation.test.ts`
+ *
+ * @note This file is impure — it spawns processes, writes to disk, and reads
+ * process output. It is a build validation script, not a unit test.
+ */
+
+import { existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { $ } from "bun";
+
+const PRAGMA_ROOT = join(import.meta.dir, "..");
+const DIST_DIR = join(PRAGMA_ROOT, "dist");
+const VALIDATION_ENTRY = join(PRAGMA_ROOT, "src", "compile-validation.ts");
+const BINARY_PATH = join(DIST_DIR, "pragma-validate");
+
+async function main() {
+  console.log("=== E1 WASM Embedding Validation ===\n");
+  console.log(`Bun version: ${Bun.version}`);
+  console.log(`Platform: ${process.platform}-${process.arch}\n`);
+
+  // --- Step 1: Compile ---
+  console.log("[1/4] Compiling validation binary...");
+  mkdirSync(DIST_DIR, { recursive: true });
+
+  const compileStart = performance.now();
+  const compileResult =
+    await $`bun build --compile --minify ${VALIDATION_ENTRY} --outfile ${BINARY_PATH}`.quiet();
+  const compileTime = performance.now() - compileStart;
+
+  if (compileResult.exitCode !== 0) {
+    console.error("  COMPILE FAILED:");
+    console.error(compileResult.stderr.toString());
+    process.exit(1);
+  }
+  console.log(`  Compiled in ${compileTime.toFixed(0)}ms`);
+
+  // --- Step 2: Check binary ---
+  console.log("\n[2/4] Checking binary...");
+  if (!existsSync(BINARY_PATH)) {
+    console.error("  Binary not found at", BINARY_PATH);
+    process.exit(1);
+  }
+  const binarySize = statSync(BINARY_PATH).size;
+  console.log(`  Binary size: ${(binarySize / 1024 / 1024).toFixed(1)} MB`);
+  console.log(`  Path: ${BINARY_PATH}`);
+
+  // --- Step 3: Run binary ---
+  console.log("\n[3/4] Running compiled binary...");
+  const runStart = performance.now();
+  const runResult = await $`${BINARY_PATH}`.quiet().nothrow();
+  const runTime = performance.now() - runStart;
+
+  const stdout = runResult.stdout.toString();
+  const stderr = runResult.stderr.toString();
+
+  if (stdout) console.log(stdout.trim());
+  if (stderr) console.error(stderr.trim());
+
+  // --- Step 4: Validate output ---
+  console.log("\n[4/4] Validating results...");
+
+  const checks = [
+    {
+      name: "Exit code is 0",
+      pass: runResult.exitCode === 0,
+      detail: `exit code: ${runResult.exitCode}`,
+    },
+    {
+      name: "WASM loaded",
+      pass: stdout.includes("[validate] WASM loaded"),
+      detail: "oxigraph dynamic import succeeded",
+    },
+    {
+      name: "Store created",
+      pass: stdout.includes("[validate] Store created"),
+      detail: "createStore() completed",
+    },
+    {
+      name: "Query executed",
+      pass: stdout.includes("[validate] Query returned"),
+      detail: "SPARQL SELECT ran successfully",
+    },
+    {
+      name: "Correct results",
+      pass: stdout.includes('"Alice"') && stdout.includes('"Bob"'),
+      detail: "expected bindings present",
+    },
+    {
+      name: "All checks passed marker",
+      pass: stdout.includes("[validate] ALL CHECKS PASSED"),
+      detail: "internal validation succeeded",
+    },
+  ];
+
+  let allPassed = true;
+  for (const check of checks) {
+    const status = check.pass ? "PASS" : "FAIL";
+    console.log(`  [${status}] ${check.name} — ${check.detail}`);
+    if (!check.pass) allPassed = false;
+  }
+
+  // --- Summary ---
+  console.log("\n=== Summary ===");
+  console.log(`Binary size:    ${(binarySize / 1024 / 1024).toFixed(1)} MB`);
+  console.log(`Compile time:   ${compileTime.toFixed(0)}ms`);
+  console.log(`Runtime:        ${runTime.toFixed(0)}ms`);
+  console.log(`Platform:       ${process.platform}-${process.arch}`);
+  console.log(`Bun version:    ${Bun.version}`);
+  console.log(`Result:         ${allPassed ? "SUCCESS" : "FAILED"}`);
+
+  // --- Cleanup ---
+  rmSync(BINARY_PATH, { force: true });
+
+  if (!allPassed) {
+    process.exit(1);
+  }
+
+  console.log(
+    "\nConclusion: Oxigraph WASM embeds correctly in `bun build --compile`.",
+  );
+  console.log("Strategy DI.02 option 1 (manual WASM embedding) is NOT needed.");
+  console.log(
+    "Bun 1.3.9+ handles WASM embedding automatically via its bundler.",
+  );
+}
+
+main().catch((err) => {
+  console.error("Validation runner failed:", err);
+  process.exit(1);
+});