@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/README.md

@@ -22,7 +22,7 @@ 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).
+pragma organizes commands into 17 domains — counting every directory under `src/domains/` except `shared/`, which holds cross-domain infrastructure rather than commands. The 14 day-to-day domains are documented below; the remaining three are specialised: `graphql` (compile TTL ontologies into GraphQL schema artifacts), `refs` (`pragma update-refs`, package reference data), and `trace` (query access tracing). Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
 
 ### Block
 
@@ -87,6 +87,7 @@ pragma organizes commands into 14 domains. Every command supports three output m
 | 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
 
@@ -173,11 +174,11 @@ Or add manually to your `.mcp.json`:
 }
 ```
 
-### MCP Tools (29)
+### MCP Tools (30)
 
 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)
+#### Read Tools (21)
 
 | Tool | Description |
 |------|-------------|
@@ -201,6 +202,7 @@ All tools return a consistent envelope: `{ ok: true, data, meta }` for success,
 | `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 |
 
 #### Write Tools (5)
 
@@ -295,14 +297,64 @@ Every subject URI in the ke graph is exposed as a discoverable MCP resource via
 
 ## Configuration
 
-Create a `pragma.config.toml` in your project root:
+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:
 
-```toml
-tier = "apps/lxd"
-channel = "normal"    # normal | experimental | prerelease
+```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" }]
+      }
+    }
+  ]
+}
 ```
 
-When no config file is present, pragma defaults to no tier and `normal` channel.
+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
 
@@ -336,7 +388,7 @@ With `--format json`, errors are returned as structured JSON with error code, su
 
 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[]`
+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
@@ -364,13 +416,13 @@ bun build --compile --minify src/bin.ts --outfile dist/pragma
 
 ## Dependencies
 
-- [`@canonical/ke`](../runtime/ke/) — triple store runtime (Oxigraph WASM)
+- [`@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
+- [`@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
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.27.1-experimental.0",
+  "version": "0.30.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
+    "build": "bun run scripts/build.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",
@@ -60,9 +60,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.27.1-experimental.0",
-    "@canonical/typescript-config": "^0.27.1-experimental.0",
-    "@canonical/webarchitect": "^0.27.1-experimental.0",
+    "@canonical/biome-config": "^0.30.0",
+    "@canonical/typescript-config": "^0.30.0",
+    "@canonical/webarchitect": "^0.30.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
@@ -70,19 +70,18 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "optionalDependencies": {
+  "dependencies": {
     "@canonical/anatomy-dsl": "^0.2.2",
+    "@canonical/cli-core": "^0.30.0",
     "@canonical/code-standards": "^0.1.2",
-    "@canonical/design-system": "^0.1.2"
-  },
-  "dependencies": {
-    "@canonical/cli-core": "^0.27.1-experimental.0",
-    "@canonical/harnesses": "^0.27.1-experimental.0",
-    "@canonical/ke": "^0.27.1-experimental.0",
-    "@canonical/summon-component": "^0.27.1-experimental.0",
-    "@canonical/summon-core": "^0.27.1-experimental.0",
-    "@canonical/summon-package": "^0.27.1-experimental.0",
-    "@canonical/task": "^0.27.1-experimental.0",
+    "@canonical/design-system": "^0.1.2",
+    "@canonical/harnesses": "^0.30.0",
+    "@canonical/ke": "^0.30.0",
+    "@canonical/ke-graphql": "^0.30.0",
+    "@canonical/summon-component": "^0.30.0",
+    "@canonical/summon-core": "^0.30.0",
+    "@canonical/summon-package": "^0.30.0",
+    "@canonical/task": "^0.30.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -91,5 +90,5 @@
     "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "d3f5b9aab7bec07fce40a12b45097d28d3cf0201"
+  "gitHead": "40fe86ac955473536ac14f074812a9821f5b65c0"
 }

package/src/config/defaultConfig.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { VALID_CHANNELS } from "../constants.js";
+import { parsePackageEntry } from "../domains/refs/operations/parseRef.js";
+import { DEFAULT_CONFIG } from "./defaultConfig.js";
+
+describe("DEFAULT_CONFIG", () => {
+  it("declares a valid channel", () => {
+    expect(VALID_CHANNELS).toContain(DEFAULT_CONFIG.channel);
+  });
+
+  it("declares at least one package, all parseable", () => {
+    expect(DEFAULT_CONFIG.packages.length).toBeGreaterThan(0);
+    for (const entry of DEFAULT_CONFIG.packages) {
+      const ref = parsePackageEntry(entry);
+      expect(ref.pkg.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("carries the canonical design-system package by default", () => {
+    const names = DEFAULT_CONFIG.packages.map((entry) =>
+      typeof entry === "string" ? entry : entry.name,
+    );
+    expect(names).toContain("@canonical/design-system");
+  });
+
+  it("does not declare fields the document must not layer", () => {
+    // tier/trace/framework defaults are semantic absences, and packages
+    // must reach the merge via DEFAULT_PACKAGES (see defaultConfig.ts).
+    expect(DEFAULT_CONFIG.tier).toBeUndefined();
+    expect(DEFAULT_CONFIG.trace).toBeUndefined();
+    expect(DEFAULT_CONFIG.framework).toBeUndefined();
+  });
+});

package/src/config/defaultConfig.ts

@@ -0,0 +1,59 @@
+import type { Channel } from "../constants.js";
+import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
+import { PragmaError } from "../error/PragmaError.js";
+import defaultsDocument from "./defaults.json" with { type: "json" };
+import parseConfigValues from "./parseConfigValues.js";
+import type { ConfigFileValues } from "./types.js";
+
+/** The built-in defaults with the fields every install relies on present. */
+interface DefaultConfig extends ConfigFileValues {
+  /** Release channel active when no config file sets one. */
+  readonly channel: Channel;
+  /** Semantic packages loaded when no config or global refs declare any. */
+  readonly packages: ReadonlyArray<RawPackageEntry>;
+}
+
+/**
+ * Validate the embedded defaults document into the built-in config layer.
+ *
+ * The document goes through the same parser as user config files, so an
+ * invalid edit to `defaults.json` fails loudly at first import (and in
+ * tests) instead of silently changing behavior.
+ *
+ * @throws PragmaError with code `CONFIG_ERROR` when the document is
+ *         invalid or misses a required default.
+ */
+function parseDefaultsDocument(): DefaultConfig {
+  const values = parseConfigValues(
+    JSON.stringify(defaultsDocument),
+    "built-in defaults (src/config/defaults.json)",
+  );
+  if (values.channel === undefined) {
+    throw PragmaError.configError("Built-in defaults must declare a channel.", {
+      recovery: { message: "Restore `channel` in src/config/defaults.json." },
+    });
+  }
+  if (values.packages === undefined || values.packages.length === 0) {
+    throw PragmaError.configError(
+      "Built-in defaults must declare at least one semantic package.",
+      {
+        recovery: {
+          message: "Restore `packages` in src/config/defaults.json.",
+        },
+      },
+    );
+  }
+  return { ...values, channel: values.channel, packages: values.packages };
+}
+
+/**
+ * The built-in configuration layer, sourced from the embedded declarative
+ * `defaults.json` document rather than hardcoded values.
+ *
+ * `packages` is deliberately NOT surfaced through the layered `pick()` in
+ * `readConfigLayers` — it feeds `DEFAULT_PACKAGES` (and from there the
+ * ref merge), where global `refs.json` entries still merge over it by
+ * package name. Sourcing it as an ordinary config layer would make it
+ * look user-declared and shut global refs out.
+ */
+export const DEFAULT_CONFIG: DefaultConfig = parseDefaultsDocument();

package/src/config/defaults.json

@@ -0,0 +1,17 @@
+{
+  "channel": "normal",
+  "packages": [
+    {
+      "name": "@canonical/design-system",
+      "source": "git+https://github.com/canonical/design-system.git#main"
+    },
+    {
+      "name": "@canonical/anatomy-dsl",
+      "source": "git+https://github.com/canonical/anatomy-dsl.git#main"
+    },
+    {
+      "name": "@canonical/code-standards",
+      "source": "git+https://github.com/canonical/web-code-standards.git#main"
+    }
+  ]
+}

package/src/config/findProjectConfigPath.test.ts

@@ -0,0 +1,53 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import findProjectConfigPath from "./findProjectConfigPath.js";
+
+describe("findProjectConfigPath", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "pragma-find-config-"));
+    mkdirSync(join(root, ".git"));
+    mkdirSync(join(root, "packages/app/src"), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("finds the config in the starting directory", () => {
+    writeFileSync(join(root, "packages/app/pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app"))).toBe(
+      join(root, "packages/app/pragma.config.json"),
+    );
+  });
+
+  it("walks up to the nearest config", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      join(root, "pragma.config.json"),
+    );
+  });
+
+  it("prefers the nearest config over a higher one", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    writeFileSync(join(root, "packages/app/pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      join(root, "packages/app/pragma.config.json"),
+    );
+  });
+
+  it("stops at the repository root (.git) without escaping", () => {
+    // The fixture root has .git and no config; nothing above it may leak in.
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      undefined,
+    );
+  });
+
+  it("checks the .git directory's own level before stopping", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    expect(findProjectConfigPath(root)).toBe(join(root, "pragma.config.json"));
+  });
+});

package/src/config/findProjectConfigPath.ts

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Find the nearest `pragma.config.json` at or above `cwd`.
+ *
+ * Walks up the directory tree so pragma works from anywhere inside a
+ * project. The walk is bounded: it stops after checking the first
+ * directory that contains `.git` (the repository root), after checking
+ * the home directory, and at the filesystem root — a config outside the
+ * repository or home never leaks in.
+ *
+ * @param cwd - Directory to start from.
+ * @returns Absolute path of the nearest config file, or `undefined`.
+ * @note Impure — probes the filesystem while walking up.
+ */
+export default function findProjectConfigPath(cwd: string): string | undefined {
+  const home = homedir();
+  let dir = resolve(cwd);
+
+  while (true) {
+    const candidate = join(dir, "pragma.config.json");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    if (existsSync(join(dir, ".git")) || dir === home) {
+      return undefined;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}

package/src/config/index.ts

@@ -1,6 +1,21 @@
-/** @module Configuration file reading, writing, and path resolution. */
+/** @module Configuration reading, writing, layered resolution, and paths. */
 export { default as configExists } from "./configExists.js";
+export { default as findProjectConfigPath } from "./findProjectConfigPath.js";
+export { default as mergeConfigFileUpdate } from "./mergeConfigFileUpdate.js";
+export { default as parseConfigValues } from "./parseConfigValues.js";
 export { default as readConfig } from "./readConfig.js";
+export { default as readConfigLayers } from "./readConfigLayers.js";
 export { default as resolveConfigPath } from "./resolveConfigPath.js";
-export type { ConfigUpdate, PragmaConfig } from "./types.js";
+export { default as resolveGlobalConfigPath } from "./resolveGlobalConfigPath.js";
+export { default as resolveWriteConfigPath } from "./resolveWriteConfigPath.js";
+export type {
+  ConfigFileValues,
+  ConfigLayer,
+  ConfigLayers,
+  ConfigOrigin,
+  ConfigOrigins,
+  ConfigScope,
+  ConfigUpdate,
+  PragmaConfig,
+} from "./types.js";
 export { default as writeConfig } from "./writeConfig.js";

package/src/config/mergeConfigFileUpdate.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import type { ConfigUpdate } from "./types.js";
+
+/**
+ * Compute a config file's new contents after applying an update.
+ *
+ * Reads the target file itself (not the merged layers — a write must
+ * never copy values from another layer into this file), applies the
+ * update per field (`undefined` with the key present removes the field),
+ * and returns the serialized JSON. Unknown keys already in the file are
+ * preserved verbatim.
+ *
+ * @param configPath - Absolute path of the config file to update.
+ * @param update - Fields to set or remove.
+ * @returns The file's new contents, newline-terminated.
+ * @throws The raw filesystem/parse error when the existing file is
+ *   present but unreadable or not valid JSON — never silently clobbers.
+ * @note Impure — reads the current file contents.
+ */
+export default function mergeConfigFileUpdate(
+  configPath: string,
+  update: ConfigUpdate,
+): string {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err: unknown) {
+    // Only swallow "file not found" — surface parse or permission errors.
+    const isNotFound =
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (!isNotFound) {
+      throw err;
+    }
+  }
+
+  applyField(existing, update, "tier");
+  applyField(existing, update, "channel");
+  applyField(existing, update, "packages");
+  applyField(existing, update, "trace");
+  applyField(existing, update, "framework");
+
+  return `${JSON.stringify(existing, null, 2)}\n`;
+}
+
+function applyField(
+  existing: Record<string, unknown>,
+  update: ConfigUpdate,
+  field: keyof ConfigUpdate,
+): void {
+  if (update[field] !== undefined) {
+    existing[field] = update[field];
+  } else if (field in update) {
+    delete existing[field];
+  }
+}