@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/surface.test.ts

@@ -0,0 +1,208 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { emitSurface } from "../kernel/spec/emitSurface.js";
+import {
+  assertConforms,
+  type Covenant,
+} from "../kernel/spec/surfaceConformance.js";
+import { capabilities } from "./index.js";
+
+/** The committed covenant, read from disk exactly as a consumer would. */
+const golden = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("../../surface/surface.v2.json", import.meta.url)),
+    "utf-8",
+  ),
+) as Covenant;
+
+describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () => {
+  const emitted = emitSurface(capabilities);
+
+  it("the live capabilities conform to the frozen covenant", () => {
+    expect(() => assertConforms(emitted, golden)).not.toThrow();
+  });
+
+  it("emits config show + the PR6 setters + the PR9 additive set, in covenant order", () => {
+    expect(emitted.nouns.config?.verbs).toEqual([
+      { v: "show", mcp: "config_show" },
+      { v: "tier", args: ["<path>"], mutates: true, mcp: "config_tier" },
+      { v: "channel", args: ["<name>"], mutates: true, mcp: "config_channel" },
+      { v: "detail", args: ["<level>"], mutates: true, mcp: "config_detail" },
+      {
+        v: "set",
+        args: ["<key>", "<value>"],
+        mutates: true,
+        mcp: "config_set",
+      },
+    ]);
+    // info stays a data-only enrichment — its emitted verb is unchanged.
+    expect(emitted.nouns.info?.verbs).toEqual([{ v: "info", mcp: "info" }]);
+    // Hidden meta verbs (__complete, mcp) are excluded from the surface.
+    expect(emitted.nouns.mcp).toBeUndefined();
+    expect(emitted.nouns.__complete).toBeUndefined();
+  });
+
+  it("emits the read nouns/verbs the packs add (block list hand-written, sample only where declared)", () => {
+    expect(emitted.nouns.standard?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "categories",
+      "lookup",
+      "sample",
+    ]);
+    // PR7 completes the surface: tier gains a bespoke single-name lookup;
+    // block/modifier/token gain no-argument samples (fixedCount).
+    expect(emitted.nouns.tier?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+    ]);
+    expect(emitted.nouns.modifier?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+      "sample",
+    ]);
+    expect(emitted.nouns.token?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+      "sample",
+      "add-config",
+    ]);
+    expect(emitted.nouns.block?.verbs).toEqual([
+      {
+        v: "list",
+        flags: ["--all-tiers"],
+        needsStore: true,
+        mcp: "block_list",
+      },
+      {
+        v: "lookup",
+        args: ["<name...>"],
+        needsStore: true,
+        mcp: "block_lookup",
+      },
+      { v: "sample", needsStore: true, mcp: "block_sample" },
+    ]);
+    // The bespoke tier lookup emits the SINGLE-name positional the covenant
+    // freezes (a pack lookup would emit the variadic `<name...>`).
+    expect(emitted.nouns.tier?.verbs).toContainEqual({
+      v: "lookup",
+      args: ["<name>"],
+      needsStore: true,
+      mcp: "tier_lookup",
+    });
+  });
+
+  it("emits the authored read nouns (ontology TBox, storeless skill, graph inspect)", () => {
+    expect(emitted.nouns.ontology?.verbs).toEqual([
+      { v: "list", needsStore: true, mcp: "ontology_list" },
+      {
+        v: "show",
+        args: ["<prefix>"],
+        flags: ["--properties", "--full-uris", "--class"],
+        needsStore: true,
+        mcp: "ontology_show",
+      },
+    ]);
+    // skill discovery is storeless (filesystem) — no needsStore.
+    expect(emitted.nouns.skill?.verbs).toEqual([
+      { v: "list", mcp: "skill_list" },
+      { v: "lookup", args: ["<name>"], mcp: "skill_lookup" },
+    ]);
+    // graph adds the SPARQL escape hatch (`query`) in PR6, alongside `inspect`.
+    expect(emitted.nouns.graph?.verbs).toEqual([
+      {
+        v: "inspect",
+        args: ["<uri>"],
+        needsStore: true,
+        mcp: "graph_inspect",
+      },
+      {
+        v: "query",
+        args: ["<sparql>"],
+        needsStore: true,
+        mcp: "graph_query",
+      },
+    ]);
+  });
+
+  it("emits the PR6 effect/diagnostic self-verbs (doctor, upgrade)", () => {
+    // doctor is a storeless read self-verb — no args, no flags, no needsStore.
+    expect(emitted.nouns.doctor?.verbs).toEqual([
+      { v: "doctor", mcp: "doctor" },
+    ]);
+    // upgrade is a storeless mutation self-verb — mutates, no args, no needsStore.
+    expect(emitted.nouns.upgrade?.verbs).toEqual([
+      { v: "upgrade", mutates: true, mcp: "upgrade" },
+    ]);
+  });
+
+  it("emits the PR10 colophon self-verb (storeless read)", () => {
+    // colophon is a storeless read self-verb — no args, no flags, no needsStore.
+    expect(emitted.nouns.colophon?.verbs).toEqual([
+      { v: "colophon", mcp: "colophon" },
+    ]);
+  });
+
+  it("emits setup as a mixed self+sub noun (self is a tool, sub-verbs are mcp:false)", () => {
+    // The one covenant noun both directly runnable AND with sub-verbs. The self
+    // verb is the `setup` tool; the four installers are CLI-only (mcp:false).
+    expect(emitted.nouns.setup?.verbs).toEqual([
+      { v: "setup", mutates: true, mcp: "setup" },
+      { v: "mcp", mutates: true, mcp: false },
+      { v: "completions", mutates: true, mcp: false },
+      { v: "skills", mutates: true, mcp: false },
+      { v: "lsp", mutates: true, mcp: false },
+    ]);
+  });
+
+  it("emits sorted tools, every one blessed by the covenant", () => {
+    const { tools } = emitted.mcpSurface;
+    expect(tools).toEqual([...tools].sort());
+    for (const tool of tools) {
+      expect(golden.mcpSurface.tools).toContain(tool);
+    }
+    // The ratified read tool names are load-bearing (lookup, NOT get).
+    for (const tool of [
+      "standard_lookup",
+      "block_lookup",
+      "modifier_lookup",
+      "token_lookup",
+      "standard_categories",
+      "standard_sample",
+      "tier_list",
+      "config_show",
+      "colophon",
+    ]) {
+      expect(tools).toContain(tool);
+    }
+  });
+});
+
+describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
+  const emitted = emitSurface(capabilities);
+
+  // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
+  // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
+  // surface-complete milestone. After PR7, every covenant tool is realized.
+  it("emits every covenant tool (all 40) — set equality with the covenant", () => {
+    const emittedTools = new Set(emitted.mcpSurface.tools);
+    const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
+    expect(missing).toEqual([]);
+    expect([...emitted.mcpSurface.tools].sort()).toEqual(
+      [...golden.mcpSurface.tools].sort(),
+    );
+    expect(emitted.mcpSurface.tools).toHaveLength(40);
+  });
+
+  // The covenant edit: the non-tool MCP surface is frozen too.
+  it("freezes the non-tool MCP surface (resources/prompts/instructions)", () => {
+    expect(emitted.mcpSurface.resources).toEqual(["pragma:{+uri}"]);
+    expect(emitted.mcpSurface.resources).toEqual(golden.mcpSurface.resources);
+    expect(emitted.mcpSurface.prompts).toBe(true);
+    expect(emitted.mcpSurface.prompts).toBe(golden.mcpSurface.prompts);
+    expect(emitted.mcpSurface.instructions).toBe(true);
+    expect(emitted.mcpSurface.instructions).toBe(
+      golden.mcpSurface.instructions,
+    );
+  });
+});

package/src/capabilities/tier/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The `tier` capability module — the bundled flat-list pack compiled to `list`.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { tierLookupVerb } from "./lookup.verb.js";
+import { tierPack } from "./pack.js";
+
+/** The `tier` capability module — the bundled flat-list pack plus the bespoke
+ * single-name `lookup` (a pack lookup would emit the variadic `<name...>`). */
+export const tierModule: CapabilityModule = {
+  name: "tier",
+  verbs: [
+    ...compilePack(tierPack, "bundled:tier", DEFAULT_PREFIX_MAP),
+    tierLookupVerb,
+  ],
+};

package/src/capabilities/tier/lookup.render.ts

@@ -0,0 +1,34 @@
+/**
+ * Formatters + data shape for `tier lookup <name>`.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+
+/** The looked-up tier: its IRI, name, and the blocks scoped directly to it. */
+export interface TierLookupData {
+  readonly uri: string;
+  readonly name: string;
+  readonly blocks: readonly string[];
+}
+
+export const tierLookupFormatters: Formatters<TierLookupData> = {
+  plain(data) {
+    const lines = [`${data.name} (${data.uri})`];
+    lines.push(
+      data.blocks.length > 0
+        ? `  blocks: ${data.blocks.join(", ")}`
+        : "  blocks: (none scoped directly to this tier)",
+    );
+    return lines.join("\n");
+  },
+  llm(data) {
+    const lines = [`# ${data.name}`, `- IRI: \`${data.uri}\``];
+    if (data.blocks.length > 0) {
+      lines.push(`- Blocks: ${data.blocks.map((b) => `\`${b}\``).join(", ")}`);
+    }
+    return lines.join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/tier/lookup.test.ts

@@ -0,0 +1,68 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import type { McpHarness } from "../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+import { runTierLookup } from "./runLookup.js";
+
+let fixture: FixtureGraph;
+let mcp: McpHarness;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("tier_lookup — bespoke single-name lookup (PROTECTED)", () => {
+  it("resolves a tier and the blocks scoped directly to it", async () => {
+    const result = await mcp.callTool("tier_lookup", { name: "apps/lxd" });
+    expect(result.ok).toBe(true);
+    const data = result.data as { name: string; blocks: string[] };
+    expect(data.name).toBe("apps/lxd");
+    // The canonical fixture scopes "LXD Panel" to apps/lxd.
+    expect(data.blocks).toContain("LXD Panel");
+  });
+
+  it("errors on an unknown tier name with a tier_list recovery", async () => {
+    const result = await mcp.callTool("tier_lookup", { name: "not-a-tier" });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string };
+    expect(error.code).toBe("ENTITY_NOT_FOUND");
+  });
+});
+
+describe("tier_lookup — cold/unseeded store (ROOT A)", () => {
+  it("remaps a 'Prefix not found' to STORE_UNAVAILABLE, not INTERNAL_ERROR", async () => {
+    // The bespoke lookup used to call `rt.query.sparql` directly, bypassing the
+    // `runSelect` remap — so a cold store's raw "Prefix not found" collapsed to
+    // INTERNAL_ERROR. It now routes through `runSelect`, inheriting the remap.
+    const coldRuntime = {
+      query: {
+        sparql: async () => {
+          throw new Error("Prefix not found: ds");
+        },
+      },
+    } as unknown as PragmaRuntime;
+
+    let caught: unknown;
+    try {
+      await runTierLookup(coldRuntime, "apps/lxd");
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+    expect(
+      (caught as { recovery?: { mcp?: { tool: string } } }).recovery?.mcp,
+    ).toMatchObject({ tool: "sources_update" });
+  });
+});

package/src/capabilities/tier/lookup.verb.ts

@@ -0,0 +1,44 @@
+/**
+ * `tier lookup <name>` — the covenant `tier_lookup` tool.
+ *
+ * Bespoke store-backed lookup with a SINGLE `<name>` positional (a pack lookup
+ * would emit the variadic `<name...>`), so it emits
+ * `{ v: "lookup", args: ["<name>"], needsStore: true, mcp: "tier_lookup" }`.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { type TierLookupData, tierLookupFormatters } from "./lookup.render.js";
+
+const tierLookupSpec: VerbSpec<Record<string, unknown>, TierLookupData> = {
+  path: ["tier", "lookup"],
+  summary: "Show one tier by name, with the blocks scoped to it.",
+  doc: "Look up a single tier by its name (e.g. apps/lxd) and list the blocks scoped directly to it.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "The tier name (e.g. apps/lxd).",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "tiers" } },
+    },
+  ],
+  output: { formatters: tierLookupFormatters },
+  examples: [{ cmd: "pragma tier lookup apps/lxd" }],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params, rt) =>
+    import("./runLookup.js").then((m) =>
+      m.runTierLookup(rt, String(params.name)),
+    ),
+};
+
+/** The `tier lookup` verb, widened for registry composition. */
+export const tierLookupVerb = asVerb(tierLookupSpec);

package/src/capabilities/tier/pack.ts

@@ -0,0 +1,28 @@
+/**
+ * The bundled `tier` pack — a flat, name-ordered list story.
+ *
+ * Tier hierarchy is encoded in the slash-separated path string (`apps/lxd`), not
+ * in graph edges, so `tier list` is a flat list; the ordered-inheritance logic
+ * lives in the block list's tier chain. SPARQL-sourced (a flat-ordered list).
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const tierPack: PackDefinition = {
+  noun: "tier",
+  description: "List all tiers in the design system ontology.",
+  toolDescription:
+    "List all tiers in the design-system ontology. Use when understanding the tier hierarchy before setting a tier filter. Example: tier_list {}.",
+  list: {
+    query: [
+      "SELECT ?uri ?name WHERE {",
+      "  ?uri a ds:Tier ;",
+      "       ds:name ?name .",
+      "} ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+    ],
+  },
+};

package/src/capabilities/tier/runLookup.ts

@@ -0,0 +1,59 @@
+/**
+ * The `tier lookup` run body (lazily imported, off the fast path).
+ *
+ * Bespoke (not a pack lookup): the covenant freezes `tier_lookup` with a SINGLE
+ * `<name>` positional, whereas a pack lookup emits the variadic `<name...>`.
+ * Resolves the tier by its `ds:name` and returns the blocks scoped directly to
+ * it (a joined OPTIONAL, so a tier with no direct members still resolves).
+ */
+
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
+import { compactUri } from "../../kernel/render/compactUri.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { TierLookupData } from "./lookup.render.js";
+
+/**
+ * Look up one tier by name.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @param name - The tier name (its `ds:name`, e.g. `apps/lxd`).
+ * @returns The tier's IRI, name, and directly-scoped block names.
+ * @throws PragmaError ENTITY_NOT_FOUND when no tier has that name;
+ *   STORE_UNAVAILABLE (exit 3) when the store is unseeded for this project.
+ */
+export async function runTierLookup(
+  rt: PragmaRuntime,
+  name: string,
+): Promise<TierLookupData> {
+  const query = [
+    "SELECT ?uri ?blockName WHERE {",
+    "  ?uri a ds:Tier ; ds:name ?tierName .",
+    `  FILTER(STR(?tierName) = ${JSON.stringify(name)})`,
+    "  OPTIONAL { ?block ds:tier ?uri ; ds:name ?blockName }",
+    "}",
+    "ORDER BY ?blockName",
+  ].join("\n");
+
+  // Route through `runSelect` (not `rt.query.sparql` directly) so a cold/unseeded
+  // store — a generated `ds:` query hitting an unknown prefix — is remapped to an
+  // actionable STORE_UNAVAILABLE with `pragma sources update` recovery, instead of
+  // a raw "Prefix not found" collapsing to INTERNAL_ERROR at the boundary.
+  const rows = await runSelect(rt, query, "tier");
+  const uri = rows[0]?.uri;
+  if (!uri) {
+    throw PragmaError.notFound("tier", name, {
+      recovery: {
+        message: "List available tiers.",
+        cli: "pragma tier list",
+        mcp: { tool: "tier_list" },
+      },
+    });
+  }
+  const blocks = rows
+    // `blockName` rides an OPTIONAL, so the key is absent for a memberless tier.
+    .map((row) => row.blockName as string | undefined)
+    .filter((block): block is string => Boolean(block));
+  return { uri: compactUri(uri, DEFAULT_PREFIX_MAP), name, blocks };
+}

package/src/capabilities/token/addConfig.render.ts

@@ -0,0 +1,27 @@
+/**
+ * Formatters for `token add-config` — plain, llm, json.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { AddConfigResult } from "./runAddConfig.js";
+
+export const addConfigFormatters: Formatters<AddConfigResult> = {
+  plain(data) {
+    const lines = [
+      `${data.alreadyExisted ? "Updated" : "Wrote"} ${data.path}`,
+      `  ${data.tokenCount} token${data.tokenCount === 1 ? "" : "s"} in the active graph`,
+      `  sources: ${data.sources.join(", ")}`,
+    ];
+    return lines.join("\n");
+  },
+  llm(data) {
+    return [
+      `${data.alreadyExisted ? "Updated" : "Wrote"} \`${data.path}\` for the terrazzo token pipeline.`,
+      `- ${data.tokenCount} token(s) in the active graph`,
+      `- sources: ${data.sources.map((source) => `\`${source}\``).join(", ")}`,
+    ].join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/token/addConfig.test.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import type { McpHarness } from "../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+
+let fixture: FixtureGraph;
+let mcp: McpHarness;
+let configPath: string;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+  configPath = join(fixture.cwd, "tokens.config.mjs");
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+beforeEach(() => {
+  rmSync(configPath, { force: true });
+});
+
+describe("token_add-config — plan-first mutation (PROTECTED)", () => {
+  it("without confirm, returns a plan and writes NOTHING", async () => {
+    const result = await mcp.callTool("token_add-config");
+    expect(result.ok).toBe(true);
+    const meta = result.meta as {
+      planOnly?: boolean;
+      confirmRequired?: boolean;
+    };
+    expect(meta.planOnly).toBe(true);
+    expect(meta.confirmRequired).toBe(true);
+    const data = result.data as { plan: string[] };
+    expect(data.plan.join("\n")).toMatch(/tokens\.config\.mjs/);
+    expect(existsSync(configPath)).toBe(false);
+  });
+
+  it("with confirm, writes a terrazzo config reflecting the store token count", async () => {
+    const result = await mcp.callTool("token_add-config", { confirm: true });
+    expect(result.ok).toBe(true);
+    const data = result.data as {
+      path: string;
+      tokenCount: number;
+      sources: string[];
+    };
+    expect(existsSync(configPath)).toBe(true);
+    // The canonical fixture holds 2 ds:Token entities.
+    expect(data.tokenCount).toBe(2);
+    const written = readFileSync(configPath, "utf-8");
+    expect(written).toContain("defineConfig");
+    expect(written).toContain("@canonical/terrazzo");
+  });
+});

package/src/capabilities/token/addConfig.verb.ts

@@ -0,0 +1,40 @@
+/**
+ * `token add-config` — generate a terrazzo `tokens.config.mjs` (the one `token`
+ * mutation). Store-backed (needsStore, per covenant) so it can report the token
+ * count; plan-first through the uniform mutation seam (a tool call without
+ * `confirm` returns the write plan; `--dry-run`/`--yes` on the CLI). No params —
+ * the covenant emits `{ v: "add-config", mutates: true, needsStore: true }`.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { addConfigFormatters } from "./addConfig.render.js";
+import type { AddConfigResult } from "./runAddConfig.js";
+
+const addConfigVerb: VerbSpec<Record<string, unknown>, AddConfigResult> = {
+  path: ["token", "add-config"],
+  summary: "Generate a tokens.config.mjs for the terrazzo token pipeline.",
+  doc: "Writes a terrazzo `defineConfig` at the project root, sourcing token JSON from the configured design-system packages. Store-backed so it reports how many tokens the active graph holds. Plan-first: returns the write plan until you confirm.",
+  params: [],
+  output: { formatters: addConfigFormatters },
+  examples: [
+    { cmd: "pragma token add-config --dry-run", note: "preview the write" },
+    { cmd: "pragma token add-config --yes", note: "write the config" },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+  },
+  run: (_params, rt) =>
+    import("./runAddConfig.js").then((m) =>
+      m.runAddConfig(rt),
+    ) as unknown as Task<AddConfigResult>,
+};
+
+/** The `token add-config` verb, widened for registry composition. */
+export const tokenAddConfigVerb = asVerb(addConfigVerb);

package/src/capabilities/token/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The `token` capability module — the bundled SPARQL pack compiled to verbs.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { tokenAddConfigVerb } from "./addConfig.verb.js";
+import { tokenPack } from "./pack.js";
+
+/** The `token` capability module — the bundled read pack plus the `add-config`
+ * mutation (hand-written; the pack compiler emits reads only). */
+export const tokenModule: CapabilityModule = {
+  name: "token",
+  verbs: [
+    ...compilePack(tokenPack, "bundled:token", DEFAULT_PREFIX_MAP),
+    tokenAddConfigVerb,
+  ],
+};

package/src/capabilities/token/pack.ts

@@ -0,0 +1,58 @@
+/**
+ * The bundled `token` pack — design tokens as data.
+ *
+ * SPARQL-sourced on both verbs: there is no `ds:Token` GraphQL type to project
+ * against when the graph ships no tokens, and the lookup reads a property path
+ * (`ds:tokenType/rdfs:label`) only SPARQL can express. `token add-config` (a
+ * mutation) is out of PR3; the `emptyRecovery` install hint is the story users
+ * see on an empty store.
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const tokenPack: PackDefinition = {
+  noun: "token",
+  description: "List all design tokens.",
+  toolDescription:
+    "List all design tokens with their type. Use when browsing which tokens exist under the active scope. Example: token_list {}.",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?category WHERE {",
+      "  ?uri a ds:Token ;",
+      "       ds:tokenId ?name .",
+      "  OPTIONAL {",
+      "    ?uri ds:tokenType ?type .",
+      "    ?type rdfs:label ?category .",
+      "  }",
+      "}",
+      "ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "category", label: "Type" },
+    ],
+    emptyRecovery: {
+      message:
+        "No tokens in the store. Build it from the configured design-system packages.",
+      cli: "pragma sources update",
+    },
+  },
+  lookup: {
+    source: "sparql",
+    by: "ds:tokenId",
+    type: "ds:Token",
+    toolDescription:
+      'Get type and theme values for one or more design tokens by name. Use when resolving specific tokens\' light/dark values. Example: token_lookup { names: ["color.primary"] }.',
+    fields: [
+      { name: "category", property: "ds:tokenType/rdfs:label", label: "Type" },
+      { name: "valueLight", property: "ds:valueLight", label: "Light value" },
+      { name: "valueDark", property: "ds:valueDark", label: "Dark value" },
+    ],
+    sample: {
+      fixedCount: true,
+      toolDescription:
+        "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes.",
+    },
+  },
+};