@indigoai-us/hq-cli 5.16.0 → 5.17.0-sources-rc.0

package/test/commands/sources.test.ts

@@ -0,0 +1,225 @@
+/**
+ * sources.test.ts — E2E tests for `hq sources` (US-006).
+ *
+ * Drives the full CLI through `runCli` with `globalThis.fetch` stubbed
+ * (vault-service) and the hq-cloud sources S3 factory swapped to an
+ * in-memory stub. Tests the four e2e cases defined in the PRD:
+ *
+ *   1. `hq sources list --entity indigo --type meeting --format json`
+ *      → exit 0, JSON entry with sourceId='abc'.
+ *   2. `hq sources get --entity indigo --type meeting --id abc`
+ *      → exit 0, body text present in stdout.
+ *   3. `hq sources list --type meeting` (no --entity, no config)
+ *      → exit 1, stderr mentions --entity.
+ *   4. `hq sources list --entity indigo --type pigeon`
+ *      → exit 1, stderr lists valid channels.
+ *
+ * HQ_ACCESS_TOKEN is set per-test so resolveAccessToken() short-circuits
+ * away from the interactive Cognito flow.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  _setSourcesS3Factory,
+  _resetSourcesS3Factory,
+} from "@indigoai-us/hq-cloud";
+import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
+import { mockVaultService } from "../helpers/vault-service-mock.js";
+import { runCli } from "../helpers/cli-runner.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/**
+ * Markdown source matching sources-pipeline output shape.
+ * NOTE: stored at `sources/meeting/abc.md` (singular `meeting/`) because
+ * listSources prefixes with `sources/${channel}/` and channel is the
+ * singular SOURCE_CHANNELS member.
+ */
+const MEETING_MD = `---
+source_id: abc
+source_type: meeting
+channel: meeting
+title: Q1 Planning Meeting
+---
+
+[Stefan 00:00:05]: Body text goes here for the e2e test.
+[Corey 00:00:12]: Acknowledged.
+`;
+
+// Sentinel string used to assert body presence in `hq sources get` output.
+const BODY_SENTINEL = "Body text goes here for the e2e test.";
+
+// ---------------------------------------------------------------------------
+// Per-test setup — vault + S3 mocks + isolated --hq-root
+// ---------------------------------------------------------------------------
+
+let restoreFetch: (() => void) | undefined;
+let tmpHqRoot: string;
+let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
+
+beforeEach(() => {
+  // Sidestep Cognito interactive flow.
+  savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
+  process.env.HQ_ACCESS_TOKEN = "test-access-token";
+
+  // Empty .hq tree so `readActiveCompanySlug` returns undefined unless a
+  // test writes config.json into it.
+  tmpHqRoot = mkdtempSync(join(tmpdir(), "hq-sources-test-"));
+
+  // Default S3 stub returns the one meeting source.
+  const s3 = mockS3WithEntries({
+    entries: [
+      {
+        key: "sources/meeting/abc.md",
+        content: MEETING_MD,
+        lastModified: new Date("2026-03-15T14:00:00Z"),
+      },
+    ],
+  });
+  _setSourcesS3Factory(() => s3);
+
+  // Default vault-service mock with one entity 'indigo'.
+  restoreFetch = mockVaultService({
+    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+  });
+});
+
+afterEach(() => {
+  _resetSourcesS3Factory();
+  restoreFetch?.();
+  restoreFetch = undefined;
+  rmSync(tmpHqRoot, { recursive: true, force: true });
+
+  if (savedEnv.HQ_ACCESS_TOKEN === undefined) {
+    delete process.env.HQ_ACCESS_TOKEN;
+  } else {
+    process.env.HQ_ACCESS_TOKEN = savedEnv.HQ_ACCESS_TOKEN;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tests — PRD e2e cases
+// ---------------------------------------------------------------------------
+
+describe("hq sources (e2e)", () => {
+  it("list --entity indigo --type meeting --format json — exit 0 + JSON with sourceId='abc'", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "meeting",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode, `stderr=${result.stderr}`).toBe(0);
+    expect(result.stderr).toBe("");
+
+    const parsed = JSON.parse(result.stdout) as {
+      entries: Array<{ sourceId: string; channel: string; key: string }>;
+      nextToken?: string;
+    };
+    expect(parsed.entries).toHaveLength(1);
+    expect(parsed.entries[0].sourceId).toBe("abc");
+    expect(parsed.entries[0].channel).toBe("meeting");
+    expect(parsed.entries[0].key).toBe("sources/meeting/abc.md");
+  });
+
+  it("get --entity indigo --type meeting --id abc — exit 0 + stdout contains body text", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "get",
+      "--entity",
+      "indigo",
+      "--type",
+      "meeting",
+      "--id",
+      "abc",
+      "--format",
+      "markdown",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout).toContain(BODY_SENTINEL);
+  });
+
+  it("list --type meeting (no --entity, no config) — exit 1 + stderr mentions --entity", async () => {
+    // tmpHqRoot has no .hq/config.json, so readActiveCompanySlug returns undefined.
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--type",
+      "meeting",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toMatch(/--entity/);
+    // Also surfaces the discovery affordance.
+    expect(result.stderr).toMatch(/hq sources entities/);
+  });
+
+  it("list --entity indigo --type pigeon — exit 1 + stderr lists valid channels", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "pigeon",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    // Every canonical channel must appear in the error message.
+    expect(result.stderr).toContain("meeting");
+    expect(result.stderr).toContain("email");
+    expect(result.stderr).toContain("slack");
+    expect(result.stderr).toContain("linear");
+    expect(result.stderr).toContain("notion");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bonus coverage — channels + wiring
+// ---------------------------------------------------------------------------
+
+describe("hq sources channels", () => {
+  it("prints SOURCE_CHANNELS sorted, one per line, exit 0", async () => {
+    const result = await runCli(["hq", "sources", "channels"]);
+    expect(result.exitCode).toBe(0);
+    const lines = result.stdout.trim().split("\n");
+    // Sorted alphabetically: email, linear, meeting, notion, slack
+    expect(lines).toEqual(["email", "linear", "meeting", "notion", "slack"]);
+  });
+});
+
+describe("hq --help wiring", () => {
+  it("mentions the sources subcommand", async () => {
+    const result = await runCli(["hq", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("sources");
+  });
+});

package/test/fixtures/signals/action_item/sample.md

@@ -0,0 +1,16 @@
+---
+signal_id: sig_action_001
+signal_type: action_item
+source_ref: abc-meeting-001
+citations:
+  - "Stefan to review the sources pipeline implementation by end of week"
+  - "Corey to prepare roadmap slides for the next planning session"
+entity_refs:
+  - stefan@indigoai.us
+  - corey@indigoai.us
+created_at: "2026-03-15T15:00:00Z"
+---
+
+Stefan will review the sources pipeline implementation and provide feedback by Friday 2026-03-20.
+
+Corey will prepare updated roadmap slides covering the CLI read surface and signal type validation for the follow-up planning session.

package/test/fixtures/signals/summary/sample.md

@@ -0,0 +1,12 @@
+---
+signal_id: sig_summary_001
+signal_type: summary
+source_ref: abc-meeting-001
+citations: []
+entity_refs:
+  - stefan@indigoai.us
+  - corey@indigoai.us
+created_at: "2026-03-15T15:00:00Z"
+---
+
+The Q1 planning meeting covered roadmap priorities for the sources pipeline and CLI tooling. Key decisions included implementing the `hq sources` and `hq signals` commands in hq-cli, enforcing a closed signal-type enum to prevent agents from inventing new types, and using STS-scoped credentials via vault-service for tenant isolation. The team agreed to ship a read-only CLI surface first before tackling S3 Vectors search in Phase 2.

package/test/fixtures/sources/meetings/sample.md

@@ -0,0 +1,25 @@
+---
+source_id: abc-meeting-001
+source_type: meeting
+channel: meeting
+title: Q1 Planning Meeting
+date: "2026-03-15"
+participants:
+  - name: Stefan Johnson
+    email: stefan@indigoai.us
+  - name: Corey Smith
+    email: corey@indigoai.us
+duration_seconds: 3600
+entity_ref: cmp_indigo_001
+created_at: "2026-03-15T14:00:00Z"
+---
+
+[Stefan Johnson 00:00:05]: Good morning everyone. Let's get started with the Q1 planning session.
+
+[Corey Smith 00:00:12]: Morning! I have the roadmap slides ready to share.
+
+[Stefan Johnson 00:00:18]: Perfect. First item on the agenda is the sources pipeline work. We need to add a read surface to the CLI so agents and users can browse sources and signals without writing AWS code.
+
+[Corey Smith 00:00:35]: Makes sense. The S3 layout is already defined by the pipeline — sources/{channel}/{sourceId}.md. We just need the listing and fetch commands.
+
+[Stefan Johnson 00:00:48]: Exactly. And we should enforce signal type validation at the CLI layer too. No invented signal types from agents.

package/test/helpers/cli-runner.ts

@@ -0,0 +1,150 @@
+/**
+ * cli-runner.ts — in-process Commander test harness.
+ *
+ * Builds a minimal Commander program and runs it with the given argv,
+ * capturing stdout/stderr without forking a child process.
+ *
+ * The program starts with only the core hq metadata (name, description,
+ * version). As new top-level command registrars are added to the CLI
+ * (US-006: sources, US-007: signals, etc.), import and register them here
+ * so tests that need the full command tree can use the same runner.
+ *
+ * NOTE: Some existing commands (pkg-install, pack-install) use semver deep
+ * subpath imports (semver/functions/satisfies.js) that are not resolvable in
+ * the pnpm test context. Those commands are excluded from the test program;
+ * add them here only if/when the semver resolution is fixed in devDeps.
+ *
+ * Usage:
+ *   const { exitCode, stdout, stderr } = await runCli(['hq', '--help']);
+ */
+
+import { Command } from "commander";
+import { registerLoginCommand } from "../../src/commands/login.js";
+import { registerLogoutCommand } from "../../src/commands/logout.js";
+import { registerWhoamiCommand } from "../../src/commands/whoami.js";
+import { registerSecretsCommand } from "../../src/commands/secrets.js";
+import { registerGroupsCommand } from "../../src/commands/groups.js";
+import { registerSourcesCommand } from "../../src/commands/sources.js";
+import { registerSignalsCommand } from "../../src/commands/signals.js";
+
+export interface CliRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Builds a test-only Commander program using exitOverride() so Commander
+ * throws CommanderError instead of calling process.exit().
+ */
+function buildProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("hq")
+    .description("HQ management CLI — modules, packages, and cloud sync")
+    .version("0.0.0-test")
+    .exitOverride();
+
+  // Auth commands (no semver deep imports)
+  registerLoginCommand(program);
+  registerLogoutCommand(program);
+  registerWhoamiCommand(program);
+
+  // Secrets / groups (no semver deep imports)
+  registerSecretsCommand(program);
+  registerGroupsCommand(program);
+
+  // Sources read surface (US-006)
+  registerSourcesCommand(program);
+
+  // Signals read surface (US-007)
+  registerSignalsCommand(program);
+
+  return program;
+}
+
+/**
+ * Runs the hq CLI in-process with the given argv.
+ *
+ * stdout/stderr are intercepted for the duration of the call and restored
+ * afterward. Not safe to call concurrently (share process streams).
+ */
+export async function runCli(argv: string[]): Promise<CliRunResult> {
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  let exitCode = 0;
+
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  const origStderrWrite = process.stderr.write.bind(process.stderr);
+  const origExit = process.exit.bind(process);
+
+  const captureWrite =
+    (chunks: string[]) =>
+    (
+      chunk: string | Uint8Array,
+      encodingOrCb?: unknown,
+      cb?: unknown,
+    ): boolean => {
+      chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"));
+      if (typeof encodingOrCb === "function") (encodingOrCb as () => void)();
+      else if (typeof cb === "function") (cb as () => void)();
+      return true;
+    };
+
+  (process.stdout as { write: unknown }).write = captureWrite(stdoutChunks);
+  (process.stderr as { write: unknown }).write = captureWrite(stderrChunks);
+
+  // Stub process.exit so action-handler exit(code) becomes a thrown error
+  // caught by parseAsync(). Otherwise it would tear down the vitest worker.
+  class ProcessExitError extends Error {
+    code: number;
+    constructor(code: number) {
+      super(`process.exit(${code})`);
+      this.name = "ProcessExitError";
+      this.code = code;
+    }
+  }
+  (process as { exit: unknown }).exit = ((code?: number) => {
+    throw new ProcessExitError(code ?? 0);
+  }) as typeof process.exit;
+
+  try {
+    const program = buildProgram();
+    // Commander's default strips 2 elements (node + script).
+    // Our argv convention is ['hq', ...userArgs], so strip the program name
+    // and use { from: 'user' } so Commander treats the rest as user args.
+    const userArgs = argv[0] === "hq" ? argv.slice(1) : argv;
+    await program.parseAsync(userArgs, { from: "user" });
+    exitCode = 0;
+  } catch (err: unknown) {
+    if (err instanceof ProcessExitError) {
+      // hq command threw via stubbed process.exit (withErrorHandling pattern).
+      // stderr was already written by the action handler.
+      exitCode = err.code;
+    } else if (err && typeof err === "object" && "code" in err) {
+      // Commander error from exitOverride()
+      const ce = err as { code: string; exitCode?: number };
+      if (ce.code === "commander.helpDisplayed" || ce.code === "commander.version") {
+        exitCode = 0;
+      } else {
+        exitCode = ce.exitCode ?? 1;
+      }
+    } else if (err instanceof Error) {
+      stderrChunks.push(err.message + "\n");
+      exitCode = 1;
+    } else {
+      exitCode = 1;
+    }
+  } finally {
+    process.stdout.write = origStdoutWrite;
+    process.stderr.write = origStderrWrite;
+    (process as { exit: unknown }).exit = origExit;
+  }
+
+  return {
+    exitCode,
+    stdout: stdoutChunks.join(""),
+    stderr: stderrChunks.join(""),
+  };
+}

package/test/helpers/s3-list-mock.ts

@@ -0,0 +1,79 @@
+/**
+ * s3-list-mock.ts — in-memory stub for @aws-sdk/client-s3 S3Client.
+ *
+ * Used by sources/signals tests that need ListObjectsV2 and GetObject behaviour
+ * without real AWS credentials or network I/O.
+ */
+
+import type { S3Client } from "@aws-sdk/client-s3";
+// NOTE: We intentionally do NOT use `instanceof ListObjectsV2Command` for
+// dispatch. When this stub is consumed by code in a sibling package
+// (@indigoai-us/hq-cloud's compiled dist), that code's @aws-sdk/client-s3
+// resolution can produce a distinct constructor instance from the one we
+// import here, breaking instanceof. Dispatching on `command.constructor.name`
+// is identity-free and works across package boundaries.
+
+export interface MockEntry {
+  /** S3 object key (e.g. "sources/meetings/abc.md") */
+  key: string;
+  /** Full file content as UTF-8 string */
+  content: string;
+  /** Optional override; defaults to 2026-01-01T00:00:00Z */
+  lastModified?: Date;
+}
+
+export interface MockS3Options {
+  entries: MockEntry[];
+}
+
+/**
+ * Returns a stub S3Client whose `send` method handles:
+ *   - ListObjectsV2Command — filters entries by Prefix, no pagination
+ *   - GetObjectCommand     — returns a streaming Body for the matching entry
+ *
+ * Throws `NoSuchKey` (matching AWS SDK error shape) for GetObject misses.
+ */
+export function mockS3WithEntries(opts: MockS3Options): S3Client {
+  const { entries } = opts;
+  const defaultDate = new Date("2026-01-01T00:00:00Z");
+
+  async function send(command: unknown): Promise<unknown> {
+    const cmdName = (command as { constructor?: { name?: string } }).constructor?.name ?? "";
+
+    if (cmdName === "ListObjectsV2Command") {
+      const { Prefix } = (command as { input: { Bucket: string; Prefix?: string } }).input;
+      const prefix = Prefix ?? "";
+      const filtered = entries.filter((e) => e.key.startsWith(prefix));
+      return {
+        Contents: filtered.map((e) => ({
+          Key: e.key,
+          Size: Buffer.byteLength(e.content, "utf-8"),
+          LastModified: e.lastModified ?? defaultDate,
+          ETag: `"mock-etag"`,
+        })),
+        IsTruncated: false,
+        NextContinuationToken: undefined,
+        $metadata: {},
+      };
+    }
+
+    if (cmdName === "GetObjectCommand") {
+      const { Key } = (command as { input: { Bucket: string; Key: string } }).input;
+      const entry = entries.find((e) => e.key === Key);
+      if (!entry) {
+        const err = new Error(`The specified key does not exist: ${Key}`);
+        (err as NodeJS.ErrnoException).name = "NoSuchKey";
+        throw err;
+      }
+      const content = entry.content;
+      async function* bodyStream(): AsyncIterable<Uint8Array> {
+        yield Buffer.from(content, "utf-8");
+      }
+      return { Body: bodyStream(), $metadata: {} };
+    }
+
+    throw new Error(`mockS3WithEntries: unhandled command type "${cmdName || "unknown"}"`);
+  }
+
+  return { send } as unknown as S3Client;
+}

package/test/helpers/vault-service-mock.ts

@@ -0,0 +1,160 @@
+/**
+ * vault-service-mock.ts — fetch stub for vault-service HTTP endpoints.
+ *
+ * Intercepts globalThis.fetch and handles the subset of vault-service routes
+ * needed by entity-resolver and STS tests. Returns the original fetch restore
+ * function so callers can clean up in afterEach/finally.
+ *
+ * Handled endpoints (URL path suffixes):
+ *   GET  .../membership/me                  returns { memberships: [...] }
+ *   GET  .../entity/by-slug/{type}/{slug}   returns { entity: {...} }
+ *   POST .../entities/{uid}/sts             returns { credentials, expiresAt, bucketName, region }
+ */
+
+import type { Membership, EntityInfo } from "@indigoai-us/hq-cloud";
+
+export interface MockEntity {
+  /** Entity UID (e.g. "cmp_indigo_001") */
+  uid: string;
+  /** Human-readable stable slug (e.g. "indigo", "personal") */
+  slug: string;
+  /** S3 bucket name for this entity */
+  bucketName: string;
+  /** AWS region; defaults to "us-east-1" */
+  region?: string;
+  /** Entity role in this membership; defaults to "owner" */
+  role?: "owner" | "admin" | "member" | "guest";
+}
+
+export interface MockStsCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+export interface MockVaultOptions {
+  entities: MockEntity[];
+  /** STS credentials returned for every POST /entities/{uid}/sts; defaults to test creds */
+  stsCredentials?: MockStsCredentials;
+}
+
+const DEFAULT_STS: MockStsCredentials = {
+  accessKeyId: "ASIAMOCK000000000001",
+  secretAccessKey: "mockSecretAccessKey",
+  sessionToken: "mockSessionToken",
+};
+
+/**
+ * Installs a fetch stub for vault-service endpoints.
+ *
+ * @returns A restore function — call it in afterEach to un-install the stub.
+ */
+export function mockVaultService(opts: MockVaultOptions): () => void {
+  const { entities, stsCredentials = DEFAULT_STS } = opts;
+  const originalFetch = globalThis.fetch as typeof fetch | undefined;
+
+  globalThis.fetch = async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : (input as Request).url;
+    const method =
+      (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+
+    // GET /membership/me
+    if (method === "GET" && /\/membership\/me(\?.*)?$/.test(url)) {
+      const memberships: Partial<Membership>[] = entities.map((e) => ({
+        membershipKey: `mbr_${e.uid}`,
+        personUid: "prs_test_person_001",
+        companyUid: e.uid,
+        role: e.role ?? "owner",
+        status: "active",
+        invitedBy: "system",
+        invitedAt: "2026-01-01T00:00:00Z",
+        createdAt: "2026-01-01T00:00:00Z",
+        updatedAt: "2026-01-01T00:00:00Z",
+      }));
+      return json({ memberships });
+    }
+
+    // GET /entity/by-slug/{type}/{slug}
+    const bySlugMatch = /\/entity\/by-slug\/[^/]+\/([^/?]+)/.exec(url);
+    if (method === "GET" && bySlugMatch) {
+      const slug = decodeURIComponent(bySlugMatch[1]);
+      const entity = entities.find((e) => e.slug === slug);
+      if (!entity) {
+        return json({ error: "Not found" }, 404);
+      }
+      const info: Partial<EntityInfo> = {
+        uid: entity.uid,
+        slug: entity.slug,
+        type: "company",
+        name: entity.slug,
+        bucketName: entity.bucketName,
+        status: "active",
+      };
+      return json({ entity: info });
+    }
+
+    // GET /entity/{uid} (direct UID lookup — used by entity-resolver)
+    const entityUidMatch = /\/entity\/([^/?]+)$/.exec(url);
+    if (method === "GET" && entityUidMatch) {
+      const uid = decodeURIComponent(entityUidMatch[1]);
+      const entity = entities.find((e) => e.uid === uid);
+      if (!entity) {
+        return json({ error: `Entity '${uid}' not found` }, 404);
+      }
+      const info: Partial<EntityInfo> = {
+        uid: entity.uid,
+        slug: entity.slug,
+        type: "company",
+        name: entity.slug,
+        bucketName: entity.bucketName,
+        status: "active",
+      };
+      return json({ entity: info });
+    }
+
+    // POST /entities/{uid}/sts
+    const entityStsMatch = /\/entities\/([^/]+)\/sts/.exec(url);
+    if (method === "POST" && entityStsMatch) {
+      const uid = decodeURIComponent(entityStsMatch[1]);
+      const entity = entities.find((e) => e.uid === uid);
+      if (!entity) {
+        return json({ error: `Entity '${uid}' not found` }, 404);
+      }
+      return json({
+        credentials: stsCredentials,
+        expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
+        bucketName: entity.bucketName,
+        region: entity.region ?? "us-east-1",
+      });
+    }
+
+    // Unhandled — pass through if original fetch exists, else 500
+    if (originalFetch) {
+      return originalFetch(input, init);
+    }
+    return json({ error: `mockVaultService: unhandled request ${method} ${url}` }, 500);
+  };
+
+  return () => {
+    if (originalFetch) {
+      globalThis.fetch = originalFetch;
+    } else {
+      delete (globalThis as Record<string, unknown>).fetch;
+    }
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}