@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/testing/helpers/projectMcp.ts

@@ -10,6 +10,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import type {
   CallToolResult,
+  Resource,
   ServerCapabilities,
 } from "@modelcontextprotocol/sdk/types.js";
 import { buildServer } from "../../kernel/project/mcp/buildServer.js";
@@ -34,12 +35,29 @@ export interface McpHarness {
   ): Promise<Record<string, unknown>>;
   /** List the registered tools. */
   listTools(): Promise<ToolInfo[]>;
-  /** List the resources exposed by the `{+uri}` template's list callback. */
-  listResources(): Promise<{ uri: string; name: string }[]>;
+  /**
+   * List the resources exposed by the `{+uri}` template's list callback.
+   *
+   * The WHOLE wire entry (title, annotations, `_meta`, …), not a projection of
+   * it: the listing's cost and its navigability are both properties of what
+   * actually crosses the wire, and a helper that trimmed the entry would hide
+   * exactly the fields under test.
+   */
+  listResources(): Promise<Resource[]>;
   /** Read one resource by URI; returns the first content's parsed/raw text. */
   readResource(uri: string): Promise<{ mimeType?: string; text: string }>;
-  /** Complete a resource-template variable against a partial value. */
-  completeResource(partial: string): Promise<string[]>;
+  /**
+   * Complete a resource-template variable against a partial value.
+   *
+   * Returns the full completion result — `total` and `hasMore` are derived by
+   * the SDK from the callback's array, so they are the only witness that a
+   * truncated result admits to being truncated.
+   */
+  completeResource(partial: string): Promise<{
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+  }>;
   /** The server capabilities negotiated at initialize (tools/resources/prompts). */
   serverCapabilities(): ServerCapabilities | undefined;
   /** The `serverInfo` the server introduced itself with at initialize. */
@@ -100,7 +118,7 @@ export async function projectMcp(
     },
     async listResources() {
       const { resources } = await client.listResources();
-      return resources.map((r) => ({ uri: r.uri, name: r.name }));
+      return resources;
     },
     async readResource(uri) {
       const result = await client.readResource({ uri });
@@ -117,7 +135,15 @@ export async function projectMcp(
         ref: { type: "ref/resource", uri: "pragma:{+uri}" },
         argument: { name: "uri", value: partial },
       });
-      return result.completion.values;
+      return {
+        values: result.completion.values,
+        ...(result.completion.total === undefined
+          ? {}
+          : { total: result.completion.total }),
+        ...(result.completion.hasMore === undefined
+          ? {}
+          : { hasMore: result.completion.hasMore }),
+      };
     },
     serverCapabilities() {
       return client.getServerCapabilities();

package/src/testing/helpers/runCli.ts

@@ -1,10 +1,10 @@
 /**
- * Test helper: spawn-and-CAPTURE the real `pragma` binary.
+ * Test helper: spawn-and-CAPTURE the real `pragma` entry point.
  *
  * {@link measureCommand} (the perf helper) discards stdout/stderr — it only
  * times spawns. This is the complementary helper for tests that need to READ
  * what the process printed: the true end-to-end boundary (argv parsing,
- * first-run, the compiled/`bun` entry point, real process exit codes).
+ * first-run, the shipped entry point, real process exit codes).
  *
  * Kept THIN — most behavioral coverage should run in-process via
  * `executeVerb`/`projectCli`/`projectMcp`; reserve `runCli` for tests where the
@@ -18,9 +18,12 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** The compiled binary the perf `globalSetup` guarantees exists before tests run. */
-const COMPILED_BINARY = fileURLToPath(
-  new URL("../../../dist/pragma", import.meta.url),
+/**
+ * The shipped entry the perf `globalSetup` guarantees exists before tests run —
+ * the `bin` the published package points at, run the way a consumer runs it.
+ */
+const SHIPPED_ENTRY = fileURLToPath(
+  new URL("../../../dist/src/bin.js", import.meta.url),
 );
 
 /** The `bin.ts` entry point, for fast source-mode spawns (no rebuild). */
@@ -37,11 +40,12 @@ export interface RunCliOptions {
    */
   readonly env?: Record<string, string | undefined>;
   /**
-   * `"compiled"` (default) spawns `dist/pragma` — the true release boundary.
-   * `"source"` spawns `bun src/bin.ts` — faster, no rebuild required, for
-   * journeys that do not test the compiled-binary boundary itself.
+   * `"shipped"` (default) spawns `node dist/src/bin.js` — the true release
+   * boundary, exactly what a consumer's `pragma` runs. `"source"` spawns
+   * `bun src/bin.ts` — faster, no rebuild required, for journeys that do not
+   * test the shipped-entry boundary itself.
    */
-  readonly mode?: "compiled" | "source";
+  readonly mode?: "shipped" | "source";
   /** Spawn timeout in milliseconds (default 20000). */
   readonly timeoutMs?: number;
 }
@@ -76,7 +80,7 @@ function seededXdgConfigHome(): string {
 /**
  * Spawn the real `pragma` CLI and capture its output.
  *
- * @param args - Argv passed to the binary (no `pragma`/`bun` prefix).
+ * @param args - Argv passed to the CLI (no `pragma`/runtime prefix).
  * @param options - cwd, env overrides, mode, and timeout.
  * @returns The captured stdout/stderr/exitCode/signal.
  * @note Impure — spawns a child process.
@@ -85,17 +89,30 @@ export function runCli(
   args: readonly string[],
   options: RunCliOptions = {},
 ): RunCliResult {
-  const mode = options.mode ?? "compiled";
-  const command = mode === "compiled" ? COMPILED_BINARY : "bun";
-  const spawnArgs = mode === "compiled" ? [...args] : [SOURCE_ENTRY, ...args];
+  const mode = options.mode ?? "shipped";
+  // Both modes spawn a RUNTIME with an entry argument now — the built entry is
+  // emitted JavaScript, not a self-executing binary, so `node` names it.
+  const command = mode === "shipped" ? process.execPath : "bun";
+  const entry = mode === "shipped" ? SHIPPED_ENTRY : SOURCE_ENTRY;
+  const spawnArgs = [entry, ...args];
+
+  // Colour OFF by default: these tests assert on bytes, and nx exports
+  // FORCE_COLOR to its test tasks, so a spawned CLI colours its help even
+  // through a pipe — green locally, red in CI, for a difference no assertion
+  // meant to make. NO_COLOR is the one convention the style seam obeys
+  // unconditionally. FORCE_COLOR is DELETED rather than overridden: Bun warns
+  // on stderr when it sees both, and stderr is part of what is asserted.
+  // `options.env` still wins, so a test that wants colour asks for it.
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    NO_COLOR: "1",
+    XDG_CONFIG_HOME: seededXdgConfigHome(),
+  };
+  delete env.FORCE_COLOR;
 
   const result = spawnSync(command, spawnArgs, {
     cwd: options.cwd,
-    env: {
-      ...process.env,
-      XDG_CONFIG_HOME: seededXdgConfigHome(),
-      ...options.env,
-    },
+    env: { ...env, ...options.env },
     encoding: "utf-8",
     timeout: options.timeoutMs ?? 20_000,
   });

package/src/testing/perf/budgets.test.ts

@@ -15,8 +15,19 @@ import {
 } from "./budgets.js";
 import { measureCommand, percentile, trimmedMean } from "./measure.js";
 
-/** The compiled binary the perf globalSetup guarantees exists. */
-const BINARY = fileURLToPath(new URL("../../../dist/pragma", import.meta.url));
+/**
+ * The shipped entry the perf globalSetup guarantees exists, spawned through
+ * `node` — which is what a consumer's `pragma` does, so node's own startup is
+ * inside every sample rather than excluded from it. The budgets below are
+ * ceilings on what a user waits, not on what a bundler produced.
+ */
+const NODE = process.execPath;
+const ENTRY = fileURLToPath(
+  new URL("../../../dist/src/bin.js", import.meta.url),
+);
+
+/** Argv for one CLI invocation through the shipped entry. */
+const cli = (...args: string[]): string[] => [ENTRY, ...args];
 
 /** Fresh XDG dirs so spawned runs never touch real state (and first-run is isolated). */
 const perfEnv = {
@@ -25,7 +36,7 @@ const perfEnv = {
 };
 
 /**
- * Protected budget suite. Spawns the standalone `dist/pragma`, discards
+ * Protected budget suite. Spawns the shipped entry through `node`, discards
  * warmups, and asserts median + p95 against the ceilings in budgets.ts. Given
  * spawn-time variance, each spawn case retries.
  */
@@ -45,7 +56,7 @@ describe("perf budgets (PROTECTED)", () => {
   });
 
   it("pragma --help stays under budget", { retry: 2 }, () => {
-    const result = measureCommand(BINARY, ["--help"], {
+    const result = measureCommand(NODE, cli("--help"), {
       runs: 15,
       warmups: 3,
       env: perfEnv,
@@ -55,7 +66,7 @@ describe("perf budgets (PROTECTED)", () => {
   });
 
   it("pragma __complete stays under budget", { retry: 3 }, () => {
-    const result = measureCommand(BINARY, ["__complete", "config"], {
+    const result = measureCommand(NODE, cli("__complete", "config"), {
       runs: 30,
       warmups: 5,
       env: perfEnv,
@@ -77,8 +88,8 @@ describe("perf budgets (PROTECTED)", () => {
     // dir → an empty walk, but it exercises the discoverSkills path per spawn;
     // enforce the same robust statistic as the noun case.
     const result = measureCommand(
-      BINARY,
-      ["__complete", "skill", "lookup", "do"],
+      NODE,
+      cli("__complete", "skill", "lookup", "do"),
       {
         runs: 30,
         warmups: 5,
@@ -94,13 +105,13 @@ describe("perf budgets (PROTECTED)", () => {
 
   it("warm store-backed verb stays under budget", { retry: 2 }, () => {
     // __store-probe boots the embedded pack from its n-quads cache and queries
-    // it — the full store-backed verb cost in the compiled binary. The first
+    // it — the full store-backed verb cost through the shipped entry. The first
     // spawn materializes the pack; warmups absorb it, then it is a cache hit.
     // Note that with 9 kept samples a nearest-rank p95 IS the maximum (see
     // BUDGETS.md's p95-stabilization section) — deliberately kept, because the
     // honest statistic here is the one that catches real cost, and the ceiling
     // is sized with a 1.25× margin over a projected p95 to absorb it.
-    const result = measureCommand(BINARY, ["__store-probe"], {
+    const result = measureCommand(NODE, cli("__store-probe"), {
       runs: 12,
       warmups: 3,
       env: {

package/src/testing/perf/budgets.ts

@@ -1,29 +1,78 @@
 /**
- * Performance budgets for the compiled `pragma` binary.
+ * Performance budgets for the shipped `pragma` entry.
  *
  * The ceilings the protected budget tests assert against. The surface
  * covenant's designed target for `--help`/`__complete` is 50 ms; the day-1 perf
- * spike (commit 6) found that unrealistic on the build hardware (cold Bun
- * process start alone is ~45 ms here), so — per the plan — those ceilings are
- * set to roughly 2× the measured median rather than silently weakening the
- * target. {@link BUDGET_WARM_STORE_MS} is derived differently (from a projected
+ * spike (commit 6) found that unrealistic on the build hardware (cold process
+ * start alone is ~45 ms here), so — per the plan — those ceilings are set to
+ * roughly 2× the measured median rather than silently weakening the target.
+ *
+ * A CEILING IS RELATIVE TO THE ARTIFACT IT WAS MEASURED ON. These were derived
+ * against a `bun build --compile` executable. The distribution now ships
+ * JavaScript that `node` executes, which costs roughly 2× on the fast paths, so
+ * a ceiling set at 2× the binary's median lands at the emit's median — where it
+ * cannot separate a regression from a slow runner. `__complete` proved that
+ * exactly: three CI attempts at 100.15, 100.20 and 100.37 ms against a 100 ms
+ * ceiling. Re-derived below on the same rule, against the artifact that now
+ * ships; the designed 50 ms target is recorded as unmet rather than quietly
+ * moved. {@link BUDGET_WARM_STORE_MS} is derived differently (from a projected
  * p95, and it lands TIGHTER than 2× its median); its arithmetic is written out
  * in full in BUDGETS.md, as are the measurements and environment for all of
  * them.
  */
 
-/** `pragma --help` ceiling (ms). Designed 50; measured median ~61 → 2×. */
+/**
+ * `pragma --help` ceiling (ms). Designed 50; the rule is 2× the measured median.
+ *
+ * Down from the provisional 220, which covered the create surface's eager
+ * registration imports on the capabilities barrel. Those are gone — the
+ * registered flag spellings are baked into `createSurface.generated.ts` at
+ * build time, the mount's adapter loads behind `CliProjection.prepare()`, and
+ * the bare-help path no longer loads Commander at all — and the lazy-graph
+ * guard in `lazy.test.ts` pins all three so the cost cannot creep back
+ * silently.
+ *
+ * MEASURED, paired: the pre-refactor tree and this one were each built and
+ * spawned alternately, 40 kept samples per cell, so drift on a shared box hits
+ * both arms. Median 74.6 → 64.7 ms; net of each arm's own `--version` control,
+ * the work this path does went 49.3 → 35.3 ms (−28%). 2 × 64.7 = 129.5, so
+ * 130 is the rule's own number rather than a number the rule tolerates. It is
+ * also where this path sat before the regression. BUDGETS.md carries the full
+ * table, the reference-box projection, and why this is the floor.
+ */
 export const BUDGET_HELP_MS = 130;
 
-/** `pragma __complete …` ceiling (ms). Designed 50; measured median ~46 → 2×. */
-export const BUDGET_COMPLETE_MS = 100;
+/**
+ * `pragma __complete …` ceiling (ms). Designed 50 — **not met, and recorded as
+ * such**: the shipped entry cannot reach it, because node's own start is most
+ * of that number before pragma runs a line.
+ *
+ * Down from the provisional 220 for the same reason as {@link BUDGET_HELP_MS}:
+ * the eager create-surface imports both fast paths paid for are deferred, and
+ * completion additionally sheds Commander — nothing on the `__complete`
+ * closure imports it any more.
+ *
+ * MEASURED in the same paired run: median 79.1 → 69.2 ms for the noun case and
+ * 74.2 → 69.3 ms for the name-source case; net of the control, 53.7 → 39.7 ms
+ * and 48.9 → 39.8 ms.
+ *
+ * 2× the slower median is 138.5, BELOW this 150 — and it stays 150 anyway,
+ * because a ceiling is relative to the box as well as the artifact. This box's
+ * cold start is 25–30 ms against the reference box's 45.5; projecting the
+ * measured work onto the reference box gives a ~85 ms median, whose 2× is
+ * ~170. CI has already run this path at a ~100 ms trimmed mean. Cutting to 140
+ * on a local median would be deriving a ceiling on hardware the suite does not
+ * run on. Completion is typed interactively, so this stays the budget most
+ * worth defending — see BUDGETS.md for the arithmetic.
+ */
+export const BUDGET_COMPLETE_MS = 150;
 
 /** Warm project-config (`pragma.config.ts`) load ceiling (ms). Cache hit is sub-ms. */
 export const BUDGET_PROJECT_CONFIG_MS = 10;
 
 /**
  * Warm store-backed verb ceiling (ms) — a store boot from the cached n-quads
- * dump plus a query, in the compiled binary.
+ * dump plus a query, through the shipped entry.
  *
  * Re-derived when the embed became the distribution's real 8 479-triple graph
  * instead of a 23-triple sample. Netted against a `--version` control from the

package/src/testing/perf/codegen.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Unit pins for the committed-codegen CHECK seam (`scripts/codegen.ts`) —
+ * the mechanism behind two loop MAJORs: a gate's build must COMPARE the
+ * committed generated module and fail on staleness instead of silently
+ * repairing it before the PROTECTED drift guard (create.test.ts's
+ * projection-fidelity cell) reads it. The generator cell drives the EXPORTED
+ * generator with an injected `out` in a tmpdir — no spawn, no build, no repo
+ * write. The wiring cells pin the two halves the
+ * seam is made of and the fact that they MEET: the flag's VALUE (the
+ * exported GATE_BUILD_ENV) and its READER (the exported
+ * checkModeFromEnv). They do NOT pin the two CALL SITES — the gate
+ * spawn's `...GATE_BUILD_ENV` spread (perf/globalSetup.ts) and
+ * build.ts's `checkModeFromEnv(process.env)` read — which stay pinned by
+ * CONSTRUCTION: scripts/build.ts is executed by no test at all, and
+ * dropping the spread leaves every cell here green. A refactor that
+ * severs either call site still reverts gate builds to write mode
+ * silently; only a VALUE or READER change reddens.
+ */
+
+import {
+  copyFileSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  checkModeFromEnv,
+  generateCreateSurface,
+} from "../../../scripts/codegen.js";
+import { GATE_BUILD_ENV } from "./globalSetup.js";
+
+const SURFACE_COMMITTED = fileURLToPath(
+  new URL(
+    "../../capabilities/create/createSurface.generated.ts",
+    import.meta.url,
+  ),
+);
+describe("the committed-codegen CHECK seam (scripts/codegen.ts)", () => {
+  let surfaceOut: string;
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "codegen-check-"));
+    surfaceOut = join(dir, "createSurface.generated.ts");
+    copyFileSync(SURFACE_COMMITTED, surfaceOut);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("check mode over the committed bytes: green, nothing written, ZERO notices — the healthy-tree gate", () => {
+    // Seeded with the bytes git holds, check mode must compute NO change (this
+    // is also the healthy gate build's determinism: a fresh render equals the
+    // committed bytes), must never write — and must log NOTHING. The
+    // zero-notices half is what separates "byte-identical" from "tolerated".
+    const before = readFileSync(surfaceOut, "utf-8");
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const surface = generateCreateSurface({ check: true, out: surfaceOut });
+    expect(surface.changed).toBe(false);
+    expect(surface.surfaced).toBeGreaterThan(0);
+    expect(log).not.toHaveBeenCalled();
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(before);
+  });
+
+  it("check mode over STALE bytes: throws naming the module — and never repairs it", () => {
+    // The other arm of the seam — the one the gate exists for. Seed bytes
+    // that differ from a fresh render; check mode must FAIL loudly (naming
+    // the committed module and the repair) and must leave the seeded bytes
+    // untouched: a check that silently rewrote them would green the stale
+    // tree before the PROTECTED drift guard reads it.
+    const stale = "// stale committed projection\n";
+    writeFileSync(surfaceOut, stale);
+    expect(() =>
+      generateCreateSurface({ check: true, out: surfaceOut }),
+    ).toThrowError(/createSurface\.generated\.ts is STALE[\s\S]*bun run build/);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(stale);
+  });
+
+  it("write mode over STALE bytes repairs them to the committed render", () => {
+    // The developer path `bun run build` takes: the same seeded staleness,
+    // check off — the module is rewritten to exactly the bytes a fresh
+    // render produces (the committed generation this suite copied in).
+    const committed = readFileSync(SURFACE_COMMITTED, "utf-8");
+    writeFileSync(surfaceOut, "// stale committed projection\n");
+    const result = generateCreateSurface({ check: false, out: surfaceOut });
+    expect(result.changed).toBe(true);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(committed);
+  });
+});
+
+describe("the CHECK seam's wiring (GATE_BUILD_ENV → checkModeFromEnv)", () => {
+  it("checkModeFromEnv: exactly the documented flag value flips a build into the gate's check", () => {
+    // The READ side of the seam, pinned: build.ts consumes this one-liner
+    // over its process.env, so a build enters check mode exactly when the
+    // flag is the string "1" — an ordinary developer env (no flag) and a
+    // flag EXPLICITLY set to any other value both stay in write mode,
+    // where `bun run build` repairs the committed artifacts. The
+    // third case is what makes "exactly" true: a predicate that merely
+    // tested for the key's presence, or accepted "0" as well, would pass
+    // the first two.
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "1" })).toBe(true);
+    expect(checkModeFromEnv({})).toBe(false);
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "0" })).toBe(false);
+  });
+
+  it("GATE_BUILD_ENV carries the check-mode flag — the gate spawn's env enters check mode", () => {
+    // The SET side of the seam, pinned against the read side: the exported
+    // constant IS the object the gate spawn spreads into its child env
+    // (perf/globalSetup.ts), and feeding it to checkModeFromEnv proves the
+    // VALUE and the READER meet — changing the flag's value, or renaming
+    // the key on either side, reddens here. What this cell does NOT see is
+    // the spawn's `...GATE_BUILD_ENV` spread itself: dropping that leaves
+    // every cell in this file green while gate builds silently revert to
+    // write mode (repairing the stale committed tree every drift guard
+    // exists to catch), so the call site stays pinned by construction.
+    expect(GATE_BUILD_ENV.PRAGMA_BUILD_SKIP_DOCS).toBe("1");
+    expect(checkModeFromEnv(GATE_BUILD_ENV)).toBe(true);
+  });
+});