@canonical/pragma-cli 0.34.0 → 0.35.0

package/README.md

@@ -1,72 +1,195 @@
 # @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.
+`pragma` answers questions about Canonical's design system from your terminal — and, run as a Model Context Protocol (MCP) server, from your AI agent. The design system ships as a knowledge graph: every block (a component, pattern, or layout), every tier, modifier family, and code standard is a node `pragma` can read. Reads answer offline, from a snapshot compiled into the package — no network, no build.
 
-## Install
+| You want to… | Run |
+|---|---|
+| See every block in the design system | `pragma block list` — all 251, each with its tier |
+| Read a block's full spec — anatomy, modifiers, properties | `pragma block lookup Button` |
+| Find the design system's name for something you already know | `pragma block lookup 'Nav*'` — lookups take names or globs |
+| Know which tier something belongs to | `pragma tier list`, `pragma tier lookup <name>` |
+| Stay consistent with the modifiers that already exist | `pragma modifier list` — 11 families |
+| Check your code against the coding standards | `pragma standard list --category react` |
+| Scaffold a component, package, or application | `pragma create component react <path>` |
+| Ask the graph something the commands don't cover | `pragma graph query "<sparql>"` |
+| Set it up, and check it's healthy | `pragma setup`, then `pragma doctor` |
+| Give your AI agent the same access | `pragma setup mcp` |
+
+The sections below take these in turn.
+
+## From install to first answer
 
 ```bash
-npm install -g @canonical/pragma-cli
+bun add --global @canonical/pragma-cli
+# or: 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.
+The package ships compiled JavaScript and runs on **Node.js 22.18+ or 23.6+** (any 24 or later), on any platform Node supports. pragma reads its own `pragma.conf.ts` — and your project's `pragma.config.ts` — through Node's TypeScript type stripping, which is on by default from those versions. Node 23.0–23.5 are excluded deliberately: they satisfy a plain `>=22.18` but predate the 23.x line's own default-on release.
 
-Check your environment and confirm the install:
+Then ask for a component:
 
-```bash
-pragma doctor
+````console
+$ pragma block lookup Button
+## Button
+
+- Tier: ds:apps_launchpad
+
+### Summary
+The **Button** component is an interactive element that allows users to trigger an action.
+
+**Main Use Cases:**
+
+- **Actions:** Trigger an action, such as submitting a form or opening a dialog.
+- **Navigation:** Navigate to a different page or view.
+
+### Guidelines
+### Accessibility
+
+- **Label:** Always provide a clear and descriptive label for the button.
+- **Focus state:** Provide a clear focus state for the button.
+
+⋮
+
+### Anatomy (DSL)
+```yaml
+---
+node:
+  uri: app-launchpad.component.button
+  styles:
+    layout.type: stack
+    layout.direction: horizontal
+    layout.align: center
+    spacing.internal: spacing/inline/small
+    appearance.background: color/background/neutral/default
+    appearance.border: border/style/solid
+    appearance.radius: radius/medium
+    typography.size: typography/paragraph/default
+  edges:
+⋮
 ```
 
-## Quickstart
+### Properties
+- name: label | type: text | optional: false
+- name: variant | type: choice | optional: true
+- name: disabled | type: boolean | optional: true
+- name: loading | type: boolean | optional: true
+````
+
+Abridged — the two cuts are marked `⋮`. The full answer is 83 lines: content-writing guidelines, the rest of the anatomy tree (child nodes with slot names and cardinalities, down to their token bindings), and a link to the classic anatomy reference.
+
+That answer came from the snapshot inside the package. No network, no cache, no project setup — `lookup` and `list` work from the moment the install finishes.
+
+## What the graph knows
+
+What this distribution's graph answers today:
+
+| Ask | Answer |
+|---|---|
+| `pragma block list` | **251** blocks — components, patterns, layouts, and subcomponents, each with its tier |
+| `pragma tier list` | **15** tiers — `global`, `apps` plus nine app tiers, `sites` plus one, `stores`, `documentation` |
+| `pragma modifier list` | **11** modifier families — Importance (Primary/Secondary/Tertiary), Anticipation (Caution/Constructive/Destructive), Criticality, Density, Lifecycle, Mode, Release, Surface, and three more |
+| `pragma standard categories` | **21** code-standard categories — react 16, css 15, lit 13, svelte 12, rust 11, storybook 11, code 10, … |
+| `pragma token list` | **0** — this distribution's graph ships no token entities |
+| `pragma prompt list` | **0** — likewise, no prompt entities |
+
+The two zeroes are real answers: the commands say the store is empty rather than inventing, and stay empty until a pack that ships those entities is configured.
 
 ```bash
 pragma block list
-pragma block lookup Button
-pragma sources status
-pragma sources update
-pragma capabilities
+pragma tier list
+pragma modifier list
+pragma standard categories
+pragma token list
+pragma prompt list
+```
+
+The commands are views over one RDF graph. Anything they don't cover, ask directly — prefixes like `ds:` are bound automatically from the active pack:
+
+```bash
+pragma graph query "SELECT ?s WHERE { ?s a ds:Component }"
 ```
 
-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.
+## Find the spec, build from it, check the result
 
-To register pragma with a detected AI harness as an MCP server:
+**Find the spec.** Lookups take a name or a glob — useful when you know roughly what something is called:
+
+```bash
+pragma block lookup 'Nav*'
+pragma tier lookup Global
+```
+
+**Build from it.** The `create` commands scaffold a component, package, or application. They run the `@canonical/summon-*` generator packages directly — those are regular dependencies of this package, so scaffolding works from a clean install. Preview any of them with `--dry-run`:
+
+```bash
+pragma create component react src/components/Button
+```
+
+**Check the result.** List the standards for your stack, then look one up by name for its do/don't code examples:
+
+```bash
+pragma standard list --category react
+```
+
+## Your agent reads the same graph
 
 ```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.
+This registers pragma as an MCP server (over stdio) with the AI coding tools it detects; `pragma mcp` is the manual entry point. The server projects the same reads and scaffolds as MCP tools, plus a `pragma:{+uri}` resource surface for entity reads. Its handshake tells agents to start with the `capabilities` tool and discover from there, and every mutating tool is plan-first: it returns the plan it would apply, and applies nothing until called again with `confirm: true`.
+
+See [docs/mcp-integration.md](./docs/mcp-integration.md) for the full surface.
+
+## Setup and health
+
+```bash
+pragma setup
+pragma doctor
+```
+
+`pragma setup` is one wizard for the whole environment: MCP registration, shell completions, agent skills, and the LSP extension. Each installer can target your project's configuration, your user-level (global) configuration, or both — `--scope project|global|both`, with `--global`/`--local` as shorthands. Preview everything it would write with `pragma setup --dry-run`, or run one installer directly: `pragma setup mcp`, `setup completions`, `setup skills`, `setup lsp`.
 
-## Two planes
+The LSP step installs the Terrazzo extension, and the extension's own log is the fastest way to confirm it took. Open your editor's Output panel, select the `terrazzo-lsp` channel, and look for a startup block like this (timestamps dropped, paths shortened):
 
-pragma is extended along two independent planes:
+```console
+[info] Config loaded from <project>/packages/react/ds-global/terrazzo-lsp.config.json
+[info] Root: <project>/packages/react/ds-global
+[info] Artifacts: <project>/packages/react/ds-global/node_modules/@canonical/design-tokens/dist/tokens.json
+[info] Loaded 781 tokens from 1 artifact
+[info] Global stylesheets: 1 file, 0 declarations
+[info] terrazzo-lsp ready
+```
+
+The token count is the line to read: `terrazzo-lsp ready` says the server started, but a run that loaded 0 tokens resolved its artifact path to nothing and will complete nothing. With tokens loaded, type `color: var(--` in a stylesheet — the design tokens should appear as completions.
 
-- **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.
+`pragma doctor` checks the environment (Node version, store health, registrations) and says what to fix. `pragma info` shows the version, the configuration in effect, and update status; `pragma upgrade` updates the CLI itself.
 
-## Relationship to summon
+## Point it at your own design system
 
-`@canonical/summon` is a separate scaffolding product. pragma reuses summon's generator core so that its scaffolding commands —
+Your project's `pragma.config.ts` names the packs — design-system data packages — the graph is built from:
 
 ```bash
-pragma create component src/components/Button --framework react
+pragma sources update
+pragma sources status
 ```
 
-— 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.
+`sources update` resolves the configured packs and rebuilds the local store; `sources status` reports which store is answering — the shipped snapshot or your build — and exactly what it was built from. Every `list`, `lookup`, and `sample` command then answers from your graph.
+
+The read surface itself is also data, not code. The distribution's own `pragma.conf.ts`, shipped inside the package, declares every read noun — `block`, `standard`, `tier`, their queries, columns, and detail levels — as configuration. A fork serving a different design system rewrites that one file and gets its own CLI commands and MCP tools without writing any command code. (Two files, deliberately distinct: `pragma.config.ts` is your project's; `pragma.conf.ts` is the distribution's.)
 
-## MCP
+[docs/config-model.md](./docs/config-model.md) explains the configuration layers; [docs/architecture.md](./docs/architecture.md) explains how one set of declarations is projected as both CLI commands and MCP tools.
 
-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).
+## Reference
 
-## Documentation
+The [command & tool reference](./docs/reference/index.md) is generated from the same declarations the CLI runs, so it cannot drift from the code.
 
 - [Getting started](./docs/getting-started.md)
+- [The design system graph](./docs/design-system.md)
+- [Setup and health](./docs/setup.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
+License: GPL-3.0

package/dist/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "@canonical/pragma-cli",
+    "description": "CLI and MCP server over Canonical's design-system knowledge graph.",
+    "version": "0.35.0",
+    "type": "module",
+    "module": "src/index.ts",
+    "types": "src/index.ts",
+    "bin": {
+        "pragma": "dist/src/bin.js"
+    },
+    "files": [
+        "src",
+        "dist",
+        "pragma.conf.ts"
+    ],
+    "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",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "bun run scripts/build.ts",
+        "build:all": "bun run build",
+        "bundle": "bun run scripts/bundle.ts",
+        "gen:reference": "bun run scripts/genReference.ts",
+        "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": "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",
+        "eval": "bun run src/testing/eval/report.ts"
+    },
+    "dependencies": {
+        "@canonical/harnesses": "^0.35.0",
+        "@canonical/ke": "^0.35.0",
+        "@canonical/ke-graphql": "^0.35.0",
+        "@canonical/summon-application": "^0.35.0",
+        "@canonical/summon-component": "^0.35.0",
+        "@canonical/summon-core": "^0.35.0",
+        "@canonical/summon-package": "^0.35.0",
+        "@canonical/task": "^0.35.0",
+        "@modelcontextprotocol/sdk": "^1.12.0",
+        "chalk": "^5.6.2",
+        "commander": "^14.0.3",
+        "graphql": "17.0.0-rc.0",
+        "oxigraph": "^0.5.0",
+        "zod": "^3.25.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.4.9",
+        "@canonical/anatomy-dsl": "^0.2.2",
+        "@canonical/biome-config": "^0.35.0",
+        "@canonical/summon": "^0.35.0",
+        "@canonical/typescript-config": "^0.35.0",
+        "@canonical/webarchitect": "^0.35.0",
+        "@types/bun": "^1.3.10",
+        "@types/node": "^26.0.0",
+        "@vitest/coverage-v8": "^4.0.18",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">=22.18 <23 || >=23.6"
+    },
+    "gitHead": "5198c5399ef657959272c0e35924391573d81146"
+}