@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/testing/helpers/fixtureGraph.ts

@@ -0,0 +1,148 @@
+/**
+ * Test helper: boot a store-backed {@link PragmaRuntime} at a REAL `cwd` whose
+ * `pragma.lock.json` points at a built fixture pack.
+ *
+ * This is distinct from (and complements) `packRuntime.ts#buildFixtureRuntime`:
+ * that helper hands back an in-process runtime wired to a custom `LazyStore`,
+ * perfect for calling `verb.run()` directly against ONE surface. This helper
+ * generalizes the `runtimeFor` + `buildUpdateTask` pattern proven in
+ * `capabilities/sources/sources.test.ts`: it writes an actual
+ * `pragma.config.ts` + package directory, runs the REAL `sources update` Task
+ * (resolve → build → lock), and returns a `cwd`. Because the lock is a real
+ * file, EVERY independent runtime construction that resolves config from that
+ * `cwd` — `bootRuntime(flags, cwd)` (CLI dispatch), `projectMcp(modules, cwd)`
+ * (MCP), and `runCli(args, { cwd })` (spawn) — boots the SAME cached pack. That
+ * is the property PR4's cross-surface parity tests need and PR3's single-surface
+ * parity tests did not: proof that CLI-json and MCP-json agree over a graph
+ * built the same way `sources update` builds one for a real project.
+ *
+ * Hermetic: the pack cache lives under the isolated `$XDG_CACHE_HOME`
+ * `setupXdgIsolation` installs; `dispose()` removes the temp directories (the
+ * shared content-addressed pack cache itself is left for reuse/cleanup by the
+ * isolation teardown).
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runTask } from "@canonical/task/node";
+import { buildUpdateTask } from "../../capabilities/sources/runUpdate.js";
+import { VERSION } from "../../constants.js";
+import type {
+  ConfigLayers,
+  PackageEntry,
+  PragmaConfig,
+} from "../../kernel/config/types.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import { createLazyStore } from "../../kernel/runtime/store.js";
+import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
+
+/** Neutral flags for a plain-text, non-agent fixture invocation. */
+const FIXTURE_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/** Options for {@link bootFixtureRuntime}. */
+export interface FixtureGraphOptions {
+  /** Inline TTL for the fixture graph (ontology + individuals). */
+  readonly ttl: string;
+  /**
+   * Config fields to bake into the written `pragma.config.ts`, e.g.
+   * `{ tier: "apps/lxd", channel: "prerelease" }`. `packages` is always set by
+   * this helper (to the fixture package) — do not override it here.
+   */
+  readonly config?: Omit<Partial<PragmaConfig>, "packages">;
+}
+
+/** A booted fixture runtime plus its `cwd` (usable by any surface) and disposal. */
+export interface FixtureGraph {
+  /** A REAL `bootRuntime` at {@link cwd} — the same one CLI dispatch uses. */
+  readonly runtime: PragmaRuntime;
+  /** The project directory whose `pragma.lock.json`/`pragma.config.ts` were written. */
+  readonly cwd: string;
+  /** Remove the temp directories and dispose the store session, if booted. */
+  dispose(): Promise<void>;
+}
+
+/** A synthetic runtime with an IN-MEMORY config — used only to drive the build Task. */
+function builderRuntime(cwd: string, packages: PackageEntry[]): PragmaRuntime {
+  const layers: ConfigLayers = {
+    config: { channel: "normal", packages },
+    origins: {
+      tier: "default",
+      channel: "default",
+      detail: "default",
+      packages: "project",
+      stories: "default",
+      prefixes: "default",
+      prompts: "default",
+    },
+    global: { path: "/nonexistent", exists: false },
+    project: { exists: false },
+  };
+  const loadConfig = async (): Promise<ConfigLayers> => layers;
+  const store = createLazyStore({ cwd, loadConfig });
+  return {
+    cwd,
+    version: VERSION,
+    globalFlags: FIXTURE_FLAGS,
+    loadConfig,
+    store,
+    query: createQueryFacade(store),
+  };
+}
+
+/** Serialize a config value as a `pragma.config.ts` field assignment. */
+function configField(key: string, value: unknown): string {
+  return `  ${key}: ${JSON.stringify(value)},`;
+}
+
+/**
+ * Build a store-backed runtime whose `cwd` carries a real lock file — the ONE
+ * shared store-backed fixture path for cross-surface (CLI/MCP/spawn) tests.
+ *
+ * @param options - The fixture graph TTL and any config overrides.
+ * @returns The runtime, its cwd, and a disposer.
+ * @note Impure — writes a package + project config, builds and caches a pack.
+ */
+export async function bootFixtureRuntime(
+  options: FixtureGraphOptions,
+): Promise<FixtureGraph> {
+  const cwd = mkdtempSync(join(tmpdir(), "pragma-fixture-proj-"));
+  const pkgDir = mkdtempSync(join(tmpdir(), "pragma-fixture-pkg-"));
+  mkdirSync(join(pkgDir, "definitions"), { recursive: true });
+  writeFileSync(join(pkgDir, "definitions", "fixture.ttl"), options.ttl);
+
+  const packages: PackageEntry[] = [
+    { name: "fixture", source: `file://${pkgDir}` },
+  ];
+  const fields = [configField("packages", packages)];
+  for (const [key, value] of Object.entries(options.config ?? {})) {
+    fields.push(configField(key, value));
+  }
+  writeFileSync(
+    join(cwd, "pragma.config.ts"),
+    `export default {\n${fields.join("\n")}\n};\n`,
+  );
+
+  await runTask(await buildUpdateTask(builderRuntime(cwd, packages), false));
+
+  const runtime = bootRuntime(FIXTURE_FLAGS, cwd);
+
+  return {
+    runtime,
+    cwd,
+    async dispose() {
+      if (runtime.store.booted) {
+        const session = await runtime.store.get();
+        session.store.dispose();
+      }
+      rmSync(cwd, { recursive: true, force: true });
+      rmSync(pkgDir, { recursive: true, force: true });
+    },
+  };
+}

package/src/testing/helpers/golden.ts

@@ -0,0 +1,45 @@
+/**
+ * Golden-snapshot normalizer for spawn-captured / rendered text.
+ *
+ * Ported from the old-shell `executor-golden.test.ts#plain()` idiom: strip ANSI
+ * escapes and tokenize machine-specific paths so a snapshot compares equal in
+ * CI and on a developer's machine. Apply to any stdout/stderr text before
+ * `toMatchSnapshot()`.
+ */
+
+import { homedir, tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+/** ANSI CSI escape sequences (colors, cursor movement, …). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching the literal ESC byte is the point
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+
+/** The package repo root (`packages/cli/pragma`), for tokenizing absolute paths. */
+const REPO_ROOT = fileURLToPath(new URL("../../../", import.meta.url)).replace(
+  /\/$/,
+  "",
+);
+
+/**
+ * Normalize volatile text for stable golden comparison: strips ANSI escapes,
+ * then replaces the repo root, `$HOME`, and the OS temp directory with stable
+ * tokens (longest/most-specific first, so a temp dir under `$HOME` still
+ * tokenizes as `<tmp>` rather than a `<home>/…` prefix).
+ *
+ * @param text - Raw stdout/stderr/rendered text.
+ * @returns The normalized text, safe to snapshot across machines.
+ */
+export function plain(text: string): string {
+  const tmp = tmpdir().replace(/\/$/, "");
+  const home = homedir().replace(/\/$/, "");
+
+  let normalized = text.replace(ANSI_PATTERN, "");
+  for (const [needle, token] of [
+    [tmp, "<tmp>"],
+    [REPO_ROOT, "<repo>"],
+    [home, "<home>"],
+  ] as const) {
+    normalized = normalized.split(needle).join(token);
+  }
+  return normalized;
+}

package/src/testing/helpers/packRuntime.ts

@@ -0,0 +1,118 @@
+/**
+ * Test helper: build a store-backed {@link PragmaRuntime} from inline TTL.
+ *
+ * Compiles a pack from the fixture graph (the ONE place the live 7-pass compile
+ * runs), then wires a lazy store + query facade over it — the same seam the
+ * dispatcher uses, so compiled pack verbs run exactly as in production. Used by
+ * the pack compiler, disclosure, and block/standard parity suites.
+ */
+
+import type { DetailLevel } from "../../constants.js";
+import { VERSION } from "../../constants.js";
+import type { ConfigLayers, ConfigOrigin } from "../../kernel/config/types.js";
+import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import { buildPack } from "../../kernel/runtime/graphpack/build.js";
+import { readPack } from "../../kernel/runtime/graphpack/read.js";
+import type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+} from "../../kernel/runtime/types.js";
+
+/** Neutral flags for a plain-text, non-agent fixture invocation. */
+const FIXTURE_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/** Options for {@link buildFixtureRuntime}. */
+export interface FixtureRuntimeOptions {
+  /** Inline TTL for the fixture graph (ontology + individuals). */
+  readonly ttl: string;
+  /** The prefixes the store is built and queried with. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** Explicit `--detail` level for this invocation. */
+  readonly detail?: DetailLevel;
+  /** Config `detail` value and its origin (drives {@link resolvePackDetail}). */
+  readonly configDetail?: string;
+  /** Origin of the config `detail` (default `"default"`). */
+  readonly detailOrigin?: ConfigOrigin;
+}
+
+/** A built fixture runtime plus the lazy store handle (to inspect `booted`). */
+export interface FixtureRuntime {
+  readonly rt: PragmaRuntime;
+  readonly store: LazyStore;
+}
+
+/**
+ * Build a runtime backed by a pack compiled from inline TTL.
+ *
+ * @param options - The fixture graph, prefixes, and disclosure inputs.
+ * @returns The runtime and its lazy store.
+ * @note Impure — writes a content-addressed pack under the isolated XDG cache.
+ */
+export async function buildFixtureRuntime(
+  options: FixtureRuntimeOptions,
+): Promise<FixtureRuntime> {
+  const built = await buildPack(
+    [{ path: "fixture.ttl", content: options.ttl }],
+    {
+      name: "pack-fixture",
+      version: "0.0.0",
+      sourceRef: "test:inline",
+      prefixes: options.prefixes,
+    },
+  );
+
+  let booted = false;
+  const store: LazyStore = {
+    get booted() {
+      return booted;
+    },
+    async get() {
+      const session = await readPack(built.dir);
+      booted = true;
+      return session;
+    },
+    invalidate() {
+      booted = false;
+    },
+  };
+
+  const layers: ConfigLayers = {
+    config: {
+      channel: "normal",
+      ...(options.configDetail !== undefined
+        ? { detail: options.configDetail }
+        : {}),
+    },
+    origins: {
+      tier: "default",
+      channel: "default",
+      detail: options.detailOrigin ?? "default",
+      packages: "default",
+      stories: "default",
+      prefixes: "default",
+      prompts: "default",
+    },
+    global: { path: "", exists: false },
+    project: { exists: false },
+  };
+
+  const rt: PragmaRuntime = {
+    cwd: process.cwd(),
+    version: VERSION,
+    globalFlags: {
+      ...FIXTURE_FLAGS,
+      ...(options.detail !== undefined ? { detail: options.detail } : {}),
+    },
+    loadConfig: async () => layers,
+    store,
+    query: createQueryFacade(store),
+  };
+
+  return { rt, store };
+}

package/src/testing/helpers/parity.ts

@@ -0,0 +1,86 @@
+/**
+ * Uniform CLI-json == MCP-json parity asserter.
+ *
+ * v2's MCP envelope IS the CLI `--format json` `{ ok, data, meta }` envelope —
+ * both projectors build it from the SAME `successEnvelope`/`errorEnvelope`
+ * (`kernel/render/envelope.ts` via `kernel/project/mcp/envelope.ts`). There is
+ * no separate condensed/text/tokens MCP shape in v2 (confirmed:
+ * `mcp/envelope.ts` reuses the CLI's envelope builders verbatim), so parity
+ * simplifies to structural data-equality — no byte-exact `condensed ===
+ * fmt.llm(...)` comparison to reproduce. This generalizes the pattern already
+ * proven ad hoc in `mcp/parity.test.ts` (`probe echo`) and `sources.test.ts`
+ * (`sources status`) into one reusable helper every read noun's tests drive.
+ */
+
+import { expect } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "./projectMcp.js";
+
+/** `--format json`, plain (non-agent) global flags. */
+export const JSON_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+/** No dry-run/undo/confirm — the shape every read verb ignores. */
+export const NO_MUTATION = { dryRun: false, undo: false, yes: false } as const;
+
+/** One CLI-vs-MCP parity check. */
+export interface ParityCase {
+  /** The modules to project on the MCP side (must include `verb`'s module). */
+  readonly modules: readonly CapabilityModule[];
+  /** The verb to dispatch on the CLI side. */
+  readonly verb: VerbSpec;
+  /** The MCP tool name (`kernel/spec/emitSurface.ts#toolName(verb.path)`). */
+  readonly tool: string;
+  /** The working directory both surfaces resolve config/store from. */
+  readonly cwd: string;
+  /**
+   * The param bag — passed to `executeVerb` AS the coerced CLI params, and to
+   * `mcp.callTool` AS the tool arguments. Valid because both dispatch paths
+   * key off the same `VerbSpec.params` names (`dispatch.extractParams` /
+   * `registerVerb.paramsFromArgs`), so one bag serves both surfaces.
+   */
+  readonly params?: Record<string, unknown>;
+  /** Optional global-flag overrides (e.g. `{ detail: "detailed" }`) for the CLI side. */
+  readonly flags?: Partial<GlobalFlags>;
+}
+
+/**
+ * Run the same read through the CLI (`--format json`) and MCP, and assert the
+ * two envelopes are deep-equal.
+ *
+ * @param opts - The verb, tool, cwd, and params to drive both surfaces with.
+ * @returns The (shared) envelope, for further assertions.
+ * @note Impure — dispatches a verb and spins up an in-process MCP server.
+ */
+export async function assertCliMcpParity(
+  opts: ParityCase,
+): Promise<Record<string, unknown>> {
+  const params = opts.params ?? {};
+  const runtime = bootRuntime({ ...JSON_FLAGS, ...opts.flags }, opts.cwd);
+  const cli = await executeVerb(opts.verb, params, NO_MUTATION, runtime);
+  const cliEnvelope = JSON.parse(cli.stdout as string) as Record<
+    string,
+    unknown
+  >;
+
+  const mcp = await projectMcp(opts.modules, opts.cwd);
+  let mcpEnvelope: Record<string, unknown>;
+  try {
+    const toolArgs = opts.flags?.detail
+      ? { ...params, detail: opts.flags.detail }
+      : params;
+    mcpEnvelope = await mcp.callTool(opts.tool, toolArgs);
+  } finally {
+    await mcp.cleanup();
+  }
+
+  expect(cliEnvelope).toEqual(mcpEnvelope);
+  return cliEnvelope;
+}

package/src/testing/helpers/projectCli.ts

@@ -0,0 +1,35 @@
+/**
+ * Test helper: build a Commander program from arbitrary capability modules.
+ *
+ * Lets a test project any set of modules (fixtures or real capabilities) into a
+ * CLI without the bin's global-flag/first-run machinery, so the projector can
+ * be exercised in isolation.
+ */
+
+import type { Command } from "commander";
+import { buildProgram } from "../../kernel/project/cli/buildProgram.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+
+/** Neutral global flags for a plain-text, non-agent invocation. */
+export const TEST_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/**
+ * Build a program from the given modules' verbs.
+ *
+ * @param modules - Capability modules whose verbs are projected.
+ * @param globalFlags - Global flags to close over (defaults to {@link TEST_FLAGS}).
+ * @returns The configured Commander program.
+ */
+export function projectCli(
+  modules: readonly CapabilityModule[],
+  globalFlags: GlobalFlags = TEST_FLAGS,
+): Command {
+  const verbs: VerbSpec[] = modules.flatMap((module) => [...module.verbs]);
+  return buildProgram(verbs, { globalFlags, programName: "pragma" });
+}

package/src/testing/helpers/projectMcp.ts

@@ -0,0 +1,145 @@
+/**
+ * Test helper: an in-process MCP client wired to a server built from modules.
+ *
+ * Uses the SDK's in-memory transport — no stdio, no network — so a test can
+ * list tools, call a tool, and read back the parsed `{ ok, data, meta }`
+ * envelope. The caller owns the lifecycle via {@link McpHarness.cleanup}.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type {
+  CallToolResult,
+  ServerCapabilities,
+} from "@modelcontextprotocol/sdk/types.js";
+import { buildServer } from "../../kernel/project/mcp/buildServer.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+
+/** A description of a registered tool (name + annotations + full schema). */
+export interface ToolInfo {
+  readonly name: string;
+  readonly annotations?: Record<string, unknown>;
+  /** The tool's one-line description, as an agent sees it in the catalog. */
+  readonly description?: string;
+  /** The tool's JSON-schema input shape, as an agent sees it in the catalog. */
+  readonly inputSchema?: unknown;
+}
+
+/** An in-process MCP harness. */
+export interface McpHarness {
+  /** Call a tool and return its parsed envelope. */
+  callTool(
+    name: string,
+    args?: Record<string, unknown>,
+  ): 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 }[]>;
+  /** 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[]>;
+  /** The server capabilities negotiated at initialize (tools/resources/prompts). */
+  serverCapabilities(): ServerCapabilities | undefined;
+  /** The server `instructions` string sent at initialize. */
+  instructions(): string | undefined;
+  /** List the native MCP prompts (`prompts/list`). */
+  listPrompts(): Promise<{ name: string; description?: string }[]>;
+  /** Get one native MCP prompt (`prompts/get`), with optional arguments. */
+  getPrompt(
+    name: string,
+    args?: Record<string, string>,
+  ): Promise<{ description?: string; messages: unknown[] }>;
+  /** Close the client and server. */
+  cleanup(): Promise<void>;
+}
+
+/**
+ * Build a server from `modules` and connect an in-process client to it.
+ *
+ * @param modules - The capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @returns The connected harness.
+ * @note Impure — connects transports.
+ */
+export async function projectMcp(
+  modules: readonly CapabilityModule[],
+  cwd?: string,
+): Promise<McpHarness> {
+  const server = await buildServer(modules, cwd);
+  const [serverTransport, clientTransport] =
+    InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "pragma-test-client", version: "0.0.0" });
+
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  return {
+    async callTool(name, args = {}) {
+      const result = (await client.callTool({
+        name,
+        arguments: args,
+      })) as CallToolResult;
+      const first = result.content[0];
+      if (!first || first.type !== "text") {
+        throw new Error(`tool "${name}" returned no text content`);
+      }
+      return JSON.parse(first.text) as Record<string, unknown>;
+    },
+    async listTools() {
+      const { tools } = await client.listTools();
+      return tools.map((tool) => ({
+        name: tool.name,
+        annotations: tool.annotations as Record<string, unknown> | undefined,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      }));
+    },
+    async listResources() {
+      const { resources } = await client.listResources();
+      return resources.map((r) => ({ uri: r.uri, name: r.name }));
+    },
+    async readResource(uri) {
+      const result = await client.readResource({ uri });
+      const first = result.contents[0] as
+        | { mimeType?: string; text?: string }
+        | undefined;
+      return {
+        ...(first?.mimeType ? { mimeType: first.mimeType } : {}),
+        text: first?.text ?? "",
+      };
+    },
+    async completeResource(partial) {
+      const result = await client.complete({
+        ref: { type: "ref/resource", uri: "pragma:{+uri}" },
+        argument: { name: "uri", value: partial },
+      });
+      return result.completion.values;
+    },
+    serverCapabilities() {
+      return client.getServerCapabilities();
+    },
+    instructions() {
+      return client.getInstructions();
+    },
+    async listPrompts() {
+      const { prompts } = await client.listPrompts();
+      return prompts.map((prompt) => ({
+        name: prompt.name,
+        ...(prompt.description ? { description: prompt.description } : {}),
+      }));
+    },
+    async getPrompt(name, args) {
+      const result = await client.getPrompt({ name, arguments: args });
+      return {
+        ...(result.description ? { description: result.description } : {}),
+        messages: result.messages,
+      };
+    },
+    async cleanup() {
+      await client.close();
+      await server.close();
+    },
+  };
+}