@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/surface.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { buildOptionInfo } from "@canonical/summon-core/projection";
 import { describe, expect, it } from "vitest";
 import { MCP_SERVER_NAME, VERSION } from "../constants.js";
 import { emitSurface } from "../kernel/spec/emitSurface.js";
@@ -8,6 +9,7 @@ import {
   type Covenant,
 } from "../kernel/spec/surfaceConformance.js";
 import { projectMcp } from "../testing/helpers/projectMcp.js";
+import { CREATE_SURFACE } from "./create/createSurface.generated.js";
 import { capabilities } from "./index.js";
 
 /** The committed covenant, read from disk exactly as a consumer would. */
@@ -25,22 +27,40 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     expect(() => assertConforms(emitted, golden)).not.toThrow();
   });
 
-  it("emits config show + the one-command config set, in covenant order (field-verbs retired, B3)", () => {
+  it("emits the four config verbs — show, get, set, unset — in covenant order", () => {
     // AV-228 B3 retired the per-field `tier`/`channel`/`detail` setters; the
-    // config noun is now just the `show` reader and the `set <key> <value>` writer.
+    // config noun is the `show` dump, the `get <key>` single read, the
+    // `set <key> <value>` writer, and the `unset <key>` clearer. Reading one
+    // value and clearing one field are commands of their own — neither hides
+    // inside `show --format json` nor inside a reserved `set` value.
     expect(emitted.nouns.config?.verbs).toEqual([
       { v: "show", mcp: "config_show" },
+      { v: "get", args: ["<key>"], mcp: "config_get" },
       {
         v: "set",
         args: ["<key>", "<value>"],
         mutates: true,
         mcp: "config_set",
       },
+      {
+        v: "unset",
+        args: ["<key>"],
+        mutates: true,
+        mcp: "config_unset",
+      },
     ]);
     // 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();
+    // `version` is the command form of `--version`: one value, two spellings
+    // of the same read, and no tool — the version already rides `info`.
+    expect(emitted.nouns.version?.verbs).toEqual([
+      { v: "version", mcp: false },
+    ]);
+    // The server entry is a real noun/verb pair, emitted like any other and
+    // carrying no tool — it serves a protocol, it is not an agent tool.
+    expect(emitted.nouns.mcp?.verbs).toEqual([{ v: "serve", mcp: false }]);
+    // The completion resolver stays hidden — it is a protocol between the
+    // shell script and the bin, not a command anyone types.
     expect(emitted.nouns.__complete).toBeUndefined();
   });
 
@@ -105,15 +125,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         needsStore: true,
         mcp: "ontology_lookup",
       },
-      // `show` is the deprecated alias of `lookup` (AV-228 B1) — same shape,
-      // both blessed in the covenant.
-      {
-        v: "show",
-        args: ["<prefix>"],
-        flags: ["--properties", "--full-uris", "--class"],
-        needsStore: true,
-        mcp: "ontology_show",
-      },
+      // One job, one spelling: `lookup` is the by-name read, and nothing
+      // else answers to it.
     ]);
     // skill discovery is storeless (filesystem) — no needsStore.
     expect(emitted.nouns.skill?.verbs).toEqual([
@@ -137,6 +150,92 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     ]);
   });
 
+  it("emits the L-CIS create noun — projected grammar, deep-equal to the covenant", () => {
+    // The create surface DERIVES from the generators' prompts (L-CIS): the
+    // framework tree segment is a required positional enum, component's flags
+    // are the framework union (incl. the svelte-only --use-ts-stories), and
+    // every flag AND positional token is the REGISTERED spelling (L-CIS-2) —
+    // a default-true confirm registers ONLY its `--no-<kebab>` form, and the
+    // args carry the kebab positional the usage line prints, so the covenant
+    // names `--no-with-styles` and `[component-path]`, never a
+    // `--with-styles` the CLI rejects or a `[componentPath]` its help never
+    // prints. Pin the three entries verbatim so a prompt edit that moves the
+    // covenant is SEEN.
+    expect(emitted.nouns.create?.verbs).toEqual([
+      {
+        v: "component",
+        args: ["<framework>", "[component-path]"],
+        flags: [
+          "--no-with-styles",
+          "--no-with-stories",
+          "--no-with-ssr-tests",
+          "--use-ts-stories",
+        ],
+        mutates: true,
+        mcp: "create_component",
+      },
+      {
+        v: "package",
+        flags: [
+          "--name",
+          "--type",
+          "--description",
+          "--with-react",
+          "--with-storybook",
+          "--with-cli",
+          "--with-pr-template",
+          "--no-run-install",
+        ],
+        mutates: true,
+        mcp: "create_package",
+      },
+      {
+        v: "application",
+        args: ["[app-path]"],
+        // ssr/router are GONE: always-on facts, not prompts — the pair had no
+        // reachable explicit form (only `--no-` spellings the generator's own
+        // guard rejected), so the projection no longer carries them.
+        flags: ["--no-forms", "--intl", "--relay", "--no-run-install"],
+        mutates: true,
+        mcp: "create_application",
+      },
+    ]);
+  });
+
+  it("every create covenant flag token is buildOptionInfo's primary registered long form (L-CIS-2)", () => {
+    // The derivation tie: the covenant's create tokens must be EXACTLY the
+    // long forms the single flag-shape authority yields for the projected
+    // prompts — the same expression both binaries register from — so the
+    // covenant can never again teach a spelling the CLI rejects (the
+    // round-15 F2 defect: kebab-cased param names blessed `--with-styles`
+    // and rejected the real `--no-with-styles`).
+    const registered = new Map<string, string>();
+    for (const surface of Object.values(CREATE_SURFACE)) {
+      for (const prompt of surface.prompts) {
+        if (prompt.positional === true) continue;
+        registered.set(
+          prompt.name,
+          buildOptionInfo(prompt).flags.split(" ")[0] as string,
+        );
+      }
+    }
+    for (const verb of emitted.nouns.create?.verbs ?? []) {
+      expect(verb.flags?.length ?? 0).toBeGreaterThan(0);
+      for (const token of verb.flags ?? []) {
+        expect([...registered.values()]).toContain(token);
+      }
+    }
+    // …and every non-positional projected prompt is named by some entry.
+    const covenantTokens = new Set(
+      (emitted.nouns.create?.verbs ?? []).flatMap((verb) => verb.flags ?? []),
+    );
+    for (const [name, token] of registered) {
+      expect(covenantTokens.has(token), `${name} → ${token} missing`).toBe(
+        true,
+      );
+    }
+  });
+
   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([
@@ -158,8 +257,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
   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).
-    // The band-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
-    // flags; completions/lsp are single-band installers with no scope.
+    // The scope-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
+    // flags; completions/lsp are single-scope installers with no scope.
     expect(emitted.nouns.setup?.verbs).toEqual([
       {
         v: "setup",
@@ -167,20 +266,36 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         mutates: true,
         mcp: "setup",
       },
+      {
+        v: "config",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "completions",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "lsp",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
       {
         v: "mcp",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "completions", mutates: true, mcp: false },
       {
         v: "skills",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "lsp", mutates: true, mcp: false },
     ]);
   });
 
@@ -200,6 +315,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       "standard_sample",
       "tier_list",
       "config_show",
+      "config_get",
+      "config_unset",
       "colophon",
     ]) {
       expect(tools).toContain(tool);
@@ -213,14 +330,14 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
   // 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 37) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 42) — 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(37);
+    expect(emitted.mcpSurface.tools).toHaveLength(42);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.

package/src/capabilities/upgrade/runUpgrade.ts

@@ -13,6 +13,11 @@
  *   by `assertExecOk` as an actionable UNSUPPORTED (exit 1) — the interpreter
  *   RESOLVES on a nonzero exit, so the check is the consumer's job.
  * - offline / already-latest carry NO exec — a real run just returns the status.
+ * - a non-global install (linked / ephemeral / workspace / unknown) also
+ *   carries NO exec even when an update exists: there is no command pragma may
+ *   run for it, so the task reports the delta plus the state's guidance and
+ *   mutates nothing. `pmUpdateCommand` only accepts the global arm, so this is
+ *   enforced by the types, not by convention.
  *
  * The whole registry read is preview-safe, so no `mutation.preview` gating is
  * needed here (unlike `sources update`, whose heavy resolve must be gated).
@@ -21,13 +26,16 @@
  */
 
 import { $, exec, gen, info, type Task, warn } from "@canonical/task";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { assertExecOk, guardMissingBinary } from "../shared/assertExecOk.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import {
+  assertExecOk,
+  checkRegistryVersion,
   detectInstallSource,
+  guardMissingBinary,
+  PRAGMA_PACKAGE,
   pmUpdateCommand,
-} from "../shared/packageManager.js";
-import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+  updateGuidance,
+} from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 /**
@@ -44,8 +52,15 @@ export async function runUpgrade(
 ): Promise<Task<UpgradeData>> {
   const { channel } = (await rt.loadConfig()).config;
   const install = detectInstallSource();
-  const command = pmUpdateCommand(install.pm, PRAGMA_PACKAGE);
+  // Only a GLOBAL install has a sanctioned update command — the type of
+  // `pmUpdateCommand` enforces the narrowing. A linked checkout in particular
+  // must never be handed `npm i -g`: it would overwrite the development link.
+  const command =
+    install.kind === "global"
+      ? pmUpdateCommand(install, PRAGMA_PACKAGE)
+      : undefined;
   const pm = install.label;
+  const kind = install.kind;
   const current = rt.version;
 
   const registry = await checkRegistryVersion(PRAGMA_PACKAGE, channel);
@@ -53,17 +68,16 @@ export async function runUpgrade(
   if (registry === undefined) {
     const data: UpgradeData = {
       pm,
+      kind,
       current,
       latest: undefined,
-      command,
+      ...(command !== undefined ? { command } : {}),
       offline: true,
       alreadyLatest: false,
       executed: false,
     };
     return gen(function* () {
-      yield* $(
-        warn("Could not reach the registry — skipped the update check."),
-      );
+      yield* $(warn("Cannot reach the registry — skipped the update check."));
       return data;
     });
   }
@@ -71,9 +85,10 @@ export async function runUpgrade(
   if (registry.latest === current) {
     const data: UpgradeData = {
       pm,
+      kind,
       current,
       latest: registry.latest,
-      command,
+      ...(command !== undefined ? { command } : {}),
       offline: false,
       alreadyLatest: true,
       executed: false,
@@ -84,20 +99,44 @@ export async function runUpgrade(
     });
   }
 
+  if (install.kind !== "global") {
+    // An update exists, but this install has no command pragma may run for
+    // it — say so honestly and run NOTHING. (The discriminant narrowing is
+    // what lets `updateGuidance` accept `install` here.)
+    const guidance = updateGuidance(install);
+    const data: UpgradeData = {
+      pm,
+      kind,
+      current,
+      latest: registry.latest,
+      guidance,
+      offline: false,
+      alreadyLatest: false,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(info(`${current} → ${registry.latest}`));
+      yield* $(warn(`No automatic upgrade for this install: ${guidance}`));
+      return data;
+    });
+  }
+
+  const updateCommand = pmUpdateCommand(install, PRAGMA_PACKAGE);
   const data: UpgradeData = {
     pm,
+    kind,
     current,
     latest: registry.latest,
-    command,
+    command: updateCommand,
     offline: false,
     alreadyLatest: false,
     executed: true,
   };
-  const parts = command.split(" ");
+  const parts = updateCommand.split(" ");
   const bin = parts[0] ?? "npm";
   const args = parts.slice(1);
   // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
-  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("please report
+  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("report
   // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
   return guardMissingBinary(
     bin,
@@ -112,7 +151,7 @@ export async function runUpgrade(
       // so inspect the result: a failed install (e.g. EACCES on a global
       // `npm i -g`) must fail loudly, not report a silent success.
       const result = yield* $(exec(bin, args, rt.cwd));
-      assertExecOk(command, result);
+      assertExecOk(updateCommand, result);
       return data;
     }),
   );

package/src/capabilities/upgrade/types.ts

@@ -2,16 +2,24 @@
  * Data shape for `pragma upgrade`.
  */
 
+import type { InstallKind } from "../../kernel/render/vocabulary.js";
+
 /** The outcome of an upgrade run (or its plan). */
 export interface UpgradeData {
   /** The install-source label (e.g. `bun (global)`). */
   readonly pm: string;
+  /** The install-source state behind the label. */
+  readonly kind: InstallKind;
   /** The currently-installed version. */
   readonly current: string;
   /** The latest published version, or `undefined` when offline. */
   readonly latest: string | undefined;
-  /** The package-manager command that applies the update. */
-  readonly command: string;
+  /** The package-manager command that applies the update — only for a GLOBAL
+   * install; every other state carries {@link guidance} instead. */
+  readonly command?: string;
+  /** The honest sentence for an install with no sanctioned update command
+   * (linked / ephemeral / workspace / unknown). */
+  readonly guidance?: string;
   /** True when the registry could not be reached. */
   readonly offline: boolean;
   /** True when the installed version is already the latest. */

package/src/capabilities/upgrade/upgrade.render.ts

@@ -7,15 +7,15 @@
  */
 
 import chalk from "chalk";
-import type { Formatters } from "../../kernel/spec/types.js";
-import { PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import { PRAGMA_PACKAGE } from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 export const upgradeFormatters: Formatters<UpgradeData> = {
   plain(data) {
     const lines = [`Installed via: ${data.pm}`];
     if (data.offline) {
-      lines.push("Could not reach the registry — try again later.");
+      lines.push("Cannot reach the registry — try again later.");
       return lines.join("\n");
     }
     if (data.alreadyLatest) {
@@ -33,20 +33,26 @@ export const upgradeFormatters: Formatters<UpgradeData> = {
         "",
         `Updated to ${data.latest}.`,
       );
-    } else {
+    } else if (data.command) {
       lines.push(`Run: ${chalk.cyan(data.command)}`);
+    } else {
+      // No sanctioned command for this install (linked / ephemeral /
+      // workspace / unknown) — the guidance sentence is the whole story.
+      lines.push(`No automatic upgrade for this install: ${data.guidance}`);
     }
     return lines.join("\n");
   },
 
   llm(data) {
-    if (data.offline)
-      return "Upgrade check failed: could not reach the registry.";
+    if (data.offline) return "Upgrade check failed: cannot reach the registry.";
     if (data.alreadyLatest) {
       return `Already at the latest version (${data.current}).`;
     }
     if (data.executed) return `Upgraded: ${data.current} → ${data.latest}`;
-    return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+    if (data.command) {
+      return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+    }
+    return `Update available: ${data.current} → ${data.latest} — ${data.guidance}`;
   },
 
   json(data) {

package/src/capabilities/upgrade/upgrade.test.ts

@@ -28,6 +28,7 @@ import {
   guardMissingBinary,
   isMissingBinaryError,
 } from "../shared/assertExecOk.js";
+import type { InstallSource } from "../shared/index.js";
 import {
   checkRegistryVersion,
   REGISTRY_TIMEOUT_MS,
@@ -36,6 +37,22 @@ import { runUpgrade } from "./runUpgrade.js";
 import type { UpgradeData } from "./types.js";
 import { upgradeModule } from "./upgrade.verb.js";
 
+// Pin the install-source detection: the real detector reads THIS process
+// (whose entry is a source checkout — an honest `unknown` with no command,
+// which would starve every update-needed case of its exec). Detection itself
+// is covered by `shared/packageManager.test.ts`; here it is a fixture.
+const detection = vi.hoisted(() => ({ install: undefined as unknown }));
+vi.mock("../shared/index.js", async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  detectInstallSource: () => detection.install,
+}));
+
+const GLOBAL_NPM: InstallSource = {
+  kind: "global",
+  pm: "npm",
+  label: "npm (global)",
+};
+
 const upgradeVerb = upgradeModule.verbs[0] as VerbSpec;
 const FLAGS_JSON: GlobalFlags = {
   llm: false,
@@ -71,6 +88,7 @@ let prevXdg: string | undefined;
 beforeEach(() => {
   prevXdg = process.env.XDG_CONFIG_HOME;
   process.env.XDG_CONFIG_HOME = tmpCwd();
+  detection.install = GLOBAL_NPM;
 });
 afterEach(() => {
   process.env.XDG_CONFIG_HOME = prevXdg;
@@ -181,6 +199,60 @@ describe("upgrade — update needed", () => {
   });
 });
 
+describe("upgrade — a non-global install NEVER gets an exec (the headline)", () => {
+  const LINKED: InstallSource = {
+    kind: "linked",
+    pm: "npm",
+    target: "/home/u/code/pragma/packages/cli/pragma",
+    label: "npm link (development checkout)",
+  };
+
+  it("linked + update available: no command, no exec — guidance instead", async () => {
+    // The case that must never regress: `npm i -g` against an npm-linked
+    // install would OVERWRITE the symlink to the development worktree.
+    detection.install = LINKED;
+    stubRegistry("99.0.0");
+    const task = await runUpgrade(bootRuntime(FLAGS_JSON, tmpCwd()));
+    const { value, effects } = dryRun(task);
+    expect(value.executed).toBe(false);
+    expect(value.command).toBeUndefined();
+    expect(value.kind).toBe("linked");
+    expect(value.guidance).toMatch(/development checkout/i);
+    expect(effects.some((e) => e._tag === "Exec")).toBe(false);
+  });
+
+  it("--dry-run through dispatch plans NO Execute line for a linked install", async () => {
+    detection.install = LINKED;
+    stubRegistry("99.0.0");
+    const outcome = await executeVerb(
+      upgradeVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS_JSON, tmpCwd()),
+    );
+    const plan = JSON.parse(outcome.stdout as string).data.plan as string[];
+    expect(plan.some((line) => line.startsWith("Execute:"))).toBe(false);
+    expect(plan.some((line) => line.includes("No automatic upgrade"))).toBe(
+      true,
+    );
+  });
+
+  it("an ephemeral run reports its state with no command either", async () => {
+    detection.install = {
+      kind: "ephemeral",
+      runner: "npx",
+      label: "npx (ephemeral)",
+    } satisfies InstallSource;
+    stubRegistry("99.0.0");
+    const { value, effects } = dryRun(
+      await runUpgrade(bootRuntime(FLAGS_JSON, tmpCwd())),
+    );
+    expect(value.executed).toBe(false);
+    expect(value.command).toBeUndefined();
+    expect(effects.some((e) => e._tag === "Exec")).toBe(false);
+  });
+});
+
 describe("assertExecOk — the exec-exitCode guard", () => {
   it("returns on a zero exit and throws an actionable UNSUPPORTED (with stderr) on nonzero", () => {
     expect(() =>
@@ -199,10 +271,10 @@ describe("assertExecOk — the exec-exitCode guard", () => {
     }
     const err = asPragmaError(thrown);
     // A denied `npm i -g` is user-fixable, NOT a bug — so it must not tell the
-    // user to "please report this issue" (that is INTERNAL_ERROR's recovery).
+    // user to "report this issue" (that is INTERNAL_ERROR's recovery).
     expect(err.code).toBe("UNSUPPORTED");
     expect(err.recovery?.message).not.toContain("report this issue");
-    expect(err.recovery?.message).toMatch(/permissions or network/i);
+    expect(err.recovery?.message).toMatch(/elevated privileges/i);
     // Surfaces the command + exit code + the captured stderr (trimmed).
     expect(err.message).toContain("npm i -g @canonical/pragma-cli");
     expect(err.message).toContain("code 13");
@@ -276,7 +348,7 @@ describe("upgrade — a failed exec maps to an actionable runtime error (exit 1)
 
   it("a missing-binary spawn (ENOENT) at a guarded site is a named UNSUPPORTED, not INTERNAL_ERROR", async () => {
     // The same wrapper `runUpgrade`/`setupLsp` apply: a spawn ENOENT REJECTS the
-    // exec, which used to collapse to INTERNAL_ERROR ("please report this issue").
+    // exec, which used to collapse to INTERNAL_ERROR ("report this issue").
     // `guardMissingBinary` names it instead.
     const thrown = await runToError(
       failVerbWith((_p, rt) =>

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -16,7 +16,7 @@
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/index.js";
 import type { UpgradeData } from "./types.js";
 import { upgradeFormatters } from "./upgrade.render.js";
 

package/src/capabilities/version/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `version` capability barrel — the command form of `--version`.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { versionVerbSpec } from "./version.verb.js";
+
+/** The `version` capability module. */
+export const versionModule: CapabilityModule = {
+  name: "version",
+  verbs: [versionVerbSpec],
+};

package/src/capabilities/version/version.test.ts

@@ -0,0 +1,66 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * The verb exists because users type it; the ONLY thing worth pinning is that
+ * it is not a second answer to the same question. The process-boundary cell
+ * compares the two spellings byte for byte through the shipped entry, so a
+ * change to either one that does not change the other reddens here. The rest
+ * pins the covenant slice and the storeless, tool-free shape.
+ */
+
+import { describe, expect, it } from "vitest";
+import { VERSION } from "../../constants.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { emitVerb } from "../../kernel/spec/emitSurface.js";
+import { runCli } from "../../testing/helpers/runCli.js";
+import { versionModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const REAL = { dryRun: false, undo: false, yes: false };
+const versionVerb = versionModule.verbs[0];
+
+describe("version — covenant-exact emission (PROTECTED)", () => {
+  it("emits a no-argument self-verb with NO tool", () => {
+    // The version already rides `info` and the MCP handshake's serverInfo, so
+    // a tool here would be a third way to ask one question.
+    expect(emitVerb(versionVerb)).toEqual({ v: "version", mcp: false });
+  });
+});
+
+describe("version — one value, two spellings of the same read", () => {
+  it("prints the version and never boots the store", async () => {
+    const rt = bootRuntime(FLAGS, process.cwd());
+    const outcome = await executeVerb(versionVerb, {}, REAL, rt);
+    expect(outcome.stdout).toBe(`${VERSION}\n`);
+    expect(outcome.exitCode).toBe(0);
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("json carries the value under a named field, not a bare scalar", async () => {
+    const outcome = await executeVerb(
+      versionVerb,
+      {},
+      REAL,
+      bootRuntime({ ...FLAGS, format: "json" }, process.cwd()),
+    );
+    expect(JSON.parse(outcome.stdout ?? "").data).toEqual({
+      version: VERSION,
+    });
+  });
+
+  it("the verb and the flag print the SAME bytes through the shipped entry", () => {
+    const fromVerb = runCli(["version"]);
+    const fromFlag = runCli(["--version"]);
+    expect(fromVerb.exitCode).toBe(0);
+    expect(fromFlag.exitCode).toBe(0);
+    expect(fromVerb.stdout).toBe(fromFlag.stdout);
+    expect(fromVerb.stdout).toBe(`${VERSION}\n`);
+  });
+});