@canonical/pragma-cli 0.32.0 → 0.34.0

package/README.md

@@ -0,0 +1,72 @@
+# @canonical/pragma-cli
+
+`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 packs.
+
+## Install
+
+```bash
+npm install -g @canonical/pragma-cli
+```
+
+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.
+
+Check your environment and confirm the install:
+
+```bash
+pragma doctor
+```
+
+## Quickstart
+
+```bash
+pragma block list
+pragma block lookup Button
+pragma sources status
+pragma sources update
+pragma capabilities
+```
+
+Reads answer from the moment you install: the binary carries a compiled snapshot of the design system, so `block list` and `block lookup` work with no cache and no network. `pragma sources update` rebuilds the store from the live packs named in your `pragma.config.ts`; `pragma sources status` reports which of the two is answering and what it was built from.
+
+To register pragma with a detected AI harness as an MCP server:
+
+```bash
+pragma setup mcp
+```
+
+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.
+
+## Two planes
+
+pragma is extended along two independent planes:
+
+- **Data plane — the content.** Your design system is a set of packs listed in `pragma.config.ts` (`packs: [...]`). `pragma sources update` compiles them into the local knowledge graph the read commands query. Point pragma at different packs and every `list` / `lookup` / `sample` command answers from that graph — and until you build them, the reads say so rather than answering from the shipped snapshot.
+- **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.
+
+## Relationship to summon
+
+`@canonical/summon` is a separate scaffolding product. pragma reuses summon's generator core so that its scaffolding commands —
+
+```bash
+pragma create component src/components/Button --framework react
+```
+
+— produce output byte-identical to summon's own `component`, `package`, and `application` generators. summon is not a runtime dependency. The binary carries the **component** generator's templates, so `pragma create component` runs from a clean install; `pragma create package` and `pragma create application` read their templates from disk and so refuse from the binary with `UNSUPPORTED` — run those from a source checkout, or use the `summon` CLI.
+
+## MCP
+
+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, whatever workflow prompts the active graph declares (none, for this distribution's current graph), 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).
+
+## Documentation
+
+- [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
+
+GPL-3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
-  "description": "Next-generation CLI and MCP kernel for Canonical's design system (pragma v2).",
-  "version": "0.32.0",
+  "description": "CLI and MCP server over Canonical's design-system knowledge graph.",
+  "version": "0.34.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -10,7 +10,8 @@
   },
   "files": [
     "src",
-    "dist"
+    "dist",
+    "pragma.conf.ts"
   ],
   "author": {
     "email": "webteam@canonical.com",
@@ -36,6 +37,8 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
+    "bundle": "bun run scripts/bundle.ts",
+    "gen:reference": "bun run scripts/genReference.ts",
     "build:compile": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
     "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
     "check:webarchitect": "webarchitect tool-ts",
@@ -51,14 +54,14 @@
     "eval": "bun run src/testing/eval/report.ts"
   },
   "dependencies": {
-    "@canonical/harnesses": "^0.32.0",
-    "@canonical/ke": "^0.32.0",
-    "@canonical/ke-graphql": "^0.32.0",
-    "@canonical/summon-application": "^0.32.0",
-    "@canonical/summon-component": "^0.32.0",
-    "@canonical/summon-core": "^0.32.0",
-    "@canonical/summon-package": "^0.32.0",
-    "@canonical/task": "^0.32.0",
+    "@canonical/harnesses": "^0.34.0",
+    "@canonical/ke": "^0.34.0",
+    "@canonical/ke-graphql": "^0.34.0",
+    "@canonical/summon-application": "^0.34.0",
+    "@canonical/summon-component": "^0.34.0",
+    "@canonical/summon-core": "^0.34.0",
+    "@canonical/summon-package": "^0.34.0",
+    "@canonical/task": "^0.34.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -68,14 +71,15 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.32.0",
-    "@canonical/typescript-config": "^0.32.0",
-    "@canonical/webarchitect": "^0.32.0",
+    "@canonical/anatomy-dsl": "^0.2.2",
+    "@canonical/biome-config": "^0.34.0",
+    "@canonical/typescript-config": "^0.34.0",
+    "@canonical/webarchitect": "^0.34.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": "5b279d8150e3988c68c6c2a741046bcd425624ca"
+  "gitHead": "e8d25fecbe6e70edfc4cb300bad65f691dbbd26e"
 }