pi-lean-dimension 0.5.0 → 0.6.0

package/node_modules/pi-lean-host/__tests__/transport.test.ts

@@ -16,7 +16,7 @@
  * regression guard for that exact boundary.
  */
 
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import {
 	waitForRetry,
 	redactSecretParams,
@@ -150,6 +150,32 @@ describe("fetchUrl content-encoding handling", () => {
 	});
 });
 
+// ═══════════════════════════════════════════════════════════════
+// Body-size ceiling — a response body past MAX_BODY_BYTES aborts the
+// collect loop with BodyTooLargeError, which fetchUrl's retry logic
+// classifies as non-transient (exactly one request, no retry).
+// ═══════════════════════════════════════════════════════════════
+
+describe("fetchUrl body-size ceiling", () => {
+	it("throws BodyTooLargeError on an oversized body without retrying", async () => {
+		let requests = 0;
+		const server = createServer((_req, res) => {
+			requests++;
+			res.writeHead(200, { "content-type": "application/json" });
+			res.end(Buffer.alloc(10 * 1024 * 1024 + 1));
+		});
+		const port = await listenAsync(server);
+		try {
+			await expect(
+				fetchUrl(`http://127.0.0.1:${port}/huge`, { fresh: true }),
+			).rejects.toMatchObject({ name: "BodyTooLargeError" });
+			expect(requests).toBe(1);
+		} finally {
+			server.close();
+		}
+	});
+});
+
 // ═══════════════════════════════════════════════════════════════════
 // Grant-based caching — a body is served from cache only when the
 // server granted freshness: a time grant (Cache-Control: max-age) or a
@@ -207,6 +233,15 @@ async function startCacheServer(
 	};
 }
 
+/** Cache-suite teardown: restore the real clock and close the server in
+ *  one step, so a test can't reset one and forget the other. */
+function stopCacheServer(
+	srv: Awaited<ReturnType<typeof startCacheServer>>,
+): Promise<void> {
+	_setClockForTest(() => Date.now());
+	return srv.close();
+}
+
 /** Fixed test epoch so all clock math is deterministic. */
 const T0 = 1_700_000_000_000;
 
@@ -236,8 +271,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(false);
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -271,8 +305,7 @@ describe("grant-based caching", () => {
 			expect(JSON.parse(r3.body)).toEqual({ n: 3, changed: true });
 			expect(srv.ifNoneMatches[2]).toBe('"v1"');
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -292,8 +325,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(false);
 			expect(srv.requestCount()).toBe(3);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -314,8 +346,7 @@ describe("grant-based caching", () => {
 			expect(srv.ifNoneMatches[1]).toBeUndefined();
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -344,8 +375,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(true);
 			expect(srv.requestCount()).toBe(3);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -370,8 +400,7 @@ describe("grant-based caching", () => {
 				expect(srv.requestCount()).toBe(2);
 				expect(srv.ifNoneMatches[1]).toBeUndefined();
 			} finally {
-				_setClockForTest(() => Date.now());
-				await srv.close();
+				await stopCacheServer(srv);
 			}
 		},
 	);
@@ -395,8 +424,7 @@ describe("grant-based caching", () => {
 			expect(srv.requestCount()).toBe(2);
 			expect(srv.ifNoneMatches[1]).toBe('"ncx"');
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -424,8 +452,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(true);
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -455,8 +482,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(true);
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -502,8 +528,7 @@ describe("grant-based caching", () => {
 			expect(srv.requestCount()).toBe(5); // conditional GET, not a header hit
 			expect(srv.ifNoneMatches[4]).toBe('"nc304"');
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -530,8 +555,7 @@ describe("grant-based caching", () => {
 			expect(srv.requestCount()).toBe(3);
 			expect(srv.ifNoneMatches[2]).toBeUndefined();
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -583,8 +607,7 @@ describe("grant-based caching", () => {
 			expect(targetInms[1]).toBe('"race"'); // second: conditional GET
 			expect(srv.requestCount()).toBe(103);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -612,8 +635,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(true);
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -636,8 +658,7 @@ describe("grant-based caching", () => {
 			expect(r3.cached).toBe(false);
 			expect(srv.requestCount()).toBe(3);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
 		}
 	});
 
@@ -667,8 +688,134 @@ describe("grant-based caching", () => {
 			expect(r2.body).not.toContain("public");
 			expect(srv.requestCount()).toBe(2);
 		} finally {
-			_setClockForTest(() => Date.now());
-			await srv.close();
+			await stopCacheServer(srv);
+		}
+	});
+});
+
+// ═══════════════════════════════════════════════════════════════
+// fetchUrl — fallbackCharset + guardRedirects (moved from helpers.test.ts)
+// ═══════════════════════════════════════════════════════════════
+
+interface CharsetTestCtx {
+	serverUrl: string;
+	stop: () => Promise<void>;
+	requestCounts: Map<string, number>;
+}
+
+/** Serves the latin-1 / charset-declaration / redirect-metadata routes. */
+async function startCharsetServer(): Promise<CharsetTestCtx> {
+	const requestCounts = new Map<string, number>();
+	const server = createServer((req, res) => {
+		const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+		requestCounts.set(pathname, (requestCounts.get(pathname) ?? 0) + 1);
+
+		if (pathname === "/api/latin1-no-charset") {
+			// ISO-8859-1 bytes for áéíóú, served with NO charset parameter —
+			// the transport must fall back to the caller's fallbackCharset.
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(Buffer.from([0xe1, 0xe9, 0xed, 0xf3, 0xfa]));
+			return;
+		}
+
+		if (pathname === "/api/utf8-with-charset") {
+			// Real UTF-8 bytes for áéíóú, served WITH charset=utf-8 — the
+			// header charset must win even if a fallbackCharset is supplied.
+			res.writeHead(200, {
+				"Content-Type": "application/json; charset=utf-8",
+			});
+			res.end(Buffer.from("áéíóú", "utf-8"));
+			return;
+		}
+
+		// 302 redirect to the cloud metadata endpoint (guardRedirects). The
+		// initial URL is on 127.0.0.1 — fetchUrl does NOT ssrf-check the
+		// initial URL (paginate owns that), only redirect targets.
+		if (pathname === "/redirect-to-metadata") {
+			res.writeHead(302, {
+				Location: "http://169.254.169.254/latest/meta-data/",
+			});
+			res.end();
+			return;
 		}
+
+		res.writeHead(404);
+		res.end();
+	});
+	const port = await listenAsync(server);
+	return {
+		serverUrl: `http://127.0.0.1:${port}`,
+		requestCounts,
+		stop: () =>
+			new Promise<void>((resolve, reject) =>
+				server.close((err) => (err ? reject(err) : resolve())),
+			),
+	};
+}
+
+describe("fetchUrl — fallbackCharset", () => {
+	let ctx: CharsetTestCtx;
+
+	beforeAll(async () => {
+		ctx = await startCharsetServer();
+	});
+	afterAll(async () => {
+		await ctx.stop();
+	});
+
+	it("falls back to fallbackCharset when the response omits a charset", async () => {
+		// Server serves ISO-8859-1 bytes with no charset parameter.
+		const { body } = await fetchUrl(`${ctx.serverUrl}/api/latin1-no-charset`, {
+			fallbackCharset: "iso-8859-1",
+			fresh: true,
+		});
+		expect(body).toBe("áéíóú");
+	});
+
+	it("uses utf-8 by default when no fallbackCharset is supplied", async () => {
+		const { body } = await fetchUrl(`${ctx.serverUrl}/api/latin1-no-charset`, {
+			fresh: true,
+		});
+		expect(body).not.toBe("áéíóú");
+		expect(body).toBe("�����");
+	});
+
+	it("header charset wins over fallbackCharset", async () => {
+		// Server declares charset=utf-8; supplying a latin-1 fallback must
+		// NOT override it — the header charset always wins.
+		const { body } = await fetchUrl(`${ctx.serverUrl}/api/utf8-with-charset`, {
+			fallbackCharset: "iso-8859-1",
+			fresh: true,
+		});
+		expect(body).toBe("áéíóú");
+	});
+});
+
+describe("fetchUrl — guardRedirects (M3)", () => {
+	let ctx: CharsetTestCtx;
+
+	beforeAll(async () => {
+		ctx = await startCharsetServer();
+	});
+
+	afterAll(async () => {
+		await ctx.stop();
+	});
+
+	it("blocks a 302 redirect to the cloud metadata endpoint", async () => {
+		// fetchUrl does NOT ssrf-check the initial URL (paginate owns that),
+		// so hitting the 127.0.0.1 test server is fine. The redirect target
+		// (169.254.169.254) must be blocked before it is fetched.
+		const before = ctx.requestCounts.get("/redirect-to-metadata") ?? 0;
+		await expect(
+			fetchUrl(`${ctx.serverUrl}/redirect-to-metadata`, {
+				guardRedirects: true,
+			}),
+		).rejects.toThrow(/Redirect to blocked host/i);
+
+		// The redirect endpoint was hit exactly once (the SSRF block is not
+		// transient, so fetchUrl must not retry).
+		const after = ctx.requestCounts.get("/redirect-to-metadata") ?? 0;
+		expect(after - before).toBe(1);
 	});
 });

package/node_modules/pi-lean-host/__tests__/verify-command.test.ts

@@ -43,6 +43,7 @@ import { setOAuthDir, writeToken } from "../core/oauth-store.js";
 import { handleVerifySubcommand } from "../core/verify-command.js";
 import { TODAY } from "../core/parse-api-guide.js";
 import { resetDisabledHelpers } from "../core/local-helpers.js";
+import { mockCtx, notifyText } from "./test-utils.js";
 
 // ═══════════════════════════════════════════════════════════════════
 // Fixtures
@@ -234,14 +235,6 @@ function readGuideIn(dirName: string): string {
 	return readFileSync(join(tmpGuidesDir, dirName, "guide.md"), "utf-8");
 }
 
-function mockCtx(overrides: Record<string, unknown> = {}): any {
-	return { ui: { notify: vi.fn() }, hasUI: true, ...overrides };
-}
-
-function notifyText(ctx: any): string {
-	return ctx.ui.notify.mock.calls.map((c: unknown[]) => c[0]).join("\n");
-}
-
 function requestedUrls(): string[] {
 	return vi.mocked(fetchUrl).mock.calls.map((c) => String(c[0]));
 }

package/node_modules/pi-lean-host/__tests__/verify-stamp.test.ts

@@ -28,6 +28,7 @@ import { fetchUrl } from "../core/transport.js";
 import { setUserGuidesDir, invalidateCache } from "../core/guide-store.js";
 import { handleVerifySubcommand } from "../core/verify-command.js";
 import { TODAY } from "../core/parse-api-guide.js";
+import { mockCtx } from "./test-utils.js";
 
 let tmpGuidesDir: string;
 
@@ -81,10 +82,6 @@ function readGuide(): string {
 	return readFileSync(join(tmpGuidesDir, "verify", "guide.md"), "utf-8");
 }
 
-function mockCtx(): any {
-	return { ui: { notify: vi.fn() }, hasUI: true };
-}
-
 describe("/api verify stamp routine", () => {
 	it("--force stamps verified: today without any HTTP", async () => {
 		setupGuide(recipe("verified: 2026-07-17"));

package/node_modules/pi-lean-host/api-guides/boe/local-helper.test.ts

@@ -8,13 +8,7 @@
  */
 
 import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ApiGuide } from "../../core/api-guide-types.js";
@@ -29,25 +23,20 @@ vi.mock("../../core/transport.js", async () => ({
 
 import { restGet } from "../../core/helpers.js";
 import { callHelper } from "../../core/local-helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides } from "../../__tests__/test-utils.js";
 
 const XML_BODY = `<diarios><diario id="1"><titulo>Test diary</titulo></diario></diarios>`;
 
 let tmpBase: string;
 
 async function setupRecipe(): Promise<{ guide: ApiGuide }> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "boe");
-	mkdirSync(domainDir, { recursive: true });
-	for (const file of ["guide.md", "helper.ts"] as const) {
-		const source = readFileSync(new URL(`./${file}`, import.meta.url), "utf-8");
-		writeFileSync(join(domainDir, file), source, "utf-8");
-	}
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return { guide: loaded.guides["boe"]! };
+	const { guides } = stageGuides(
+		tmpBase,
+		new URL("../", import.meta.url),
+		["boe"],
+		["guide.md", "helper.ts"],
+	);
+	return { guide: guides["boe"]! };
 }
 
 beforeAll(() => {

package/node_modules/pi-lean-host/api-guides/dnb/error-envelope.test.ts

@@ -13,13 +13,7 @@
  */
 
 import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { HelperError } from "../../core/helpers.js";
@@ -34,8 +28,7 @@ vi.mock("../../core/transport.js", async () => ({
 }));
 
 import { paginate } from "../../core/helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides } from "../../__tests__/test-utils.js";
 
 const XML_HEADERS = { "content-type": "text/xml;charset=UTF-8" };
 const JSON_HEADERS = { "content-type": "application/json" };
@@ -72,15 +65,10 @@ async function mock200(
 }
 
 async function loadDnbGuide(): Promise<ApiGuide> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "dnb");
-	mkdirSync(domainDir, { recursive: true });
-	const source = readFileSync(new URL("./guide.md", import.meta.url), "utf-8");
-	writeFileSync(join(domainDir, "guide.md"), source, "utf-8");
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return loaded.guides["dnb"]!;
+	const { guides } = stageGuides(tmpBase, new URL("../", import.meta.url), [
+		"dnb",
+	]);
+	return guides["dnb"]!;
 }
 
 // Inline-guide builder for the World Bank mirror.

package/node_modules/pi-lean-host/api-guides/dnb/resumption-token.test.ts

@@ -8,13 +8,7 @@
  */
 
 import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ApiGuide } from "../../core/api-guide-types.js";
@@ -28,8 +22,7 @@ vi.mock("../../core/transport.js", async () => ({
 }));
 
 import { paginate } from "../../core/helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides } from "../../__tests__/test-utils.js";
 
 const PAGE1_XML = `<OAI-PMH><ListRecords><record><metadata><title>One</title></metadata></record><record><metadata><title>Two</title></metadata></record><resumptionToken completeListSize="3">token-abc</resumptionToken></ListRecords></OAI-PMH>`;
 
@@ -39,15 +32,10 @@ const PAGE2_XML = `<OAI-PMH><ListRecords><record><metadata><title>Three</title><
 let tmpBase: string;
 
 async function setupRecipe(): Promise<{ guide: ApiGuide }> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "dnb");
-	mkdirSync(domainDir, { recursive: true });
-	const source = readFileSync(new URL("./guide.md", import.meta.url), "utf-8");
-	writeFileSync(join(domainDir, "guide.md"), source, "utf-8");
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return { guide: loaded.guides["dnb"]! };
+	const { guides } = stageGuides(tmpBase, new URL("../", import.meta.url), [
+		"dnb",
+	]);
+	return { guide: guides["dnb"]! };
 }
 
 beforeAll(() => {

package/node_modules/pi-lean-host/api-guides/frost-sensorthings/dotted-key.test.ts

@@ -20,13 +20,7 @@ import {
 	afterAll,
 	beforeEach,
 } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ApiGuide } from "../../core/api-guide-types.js";
@@ -40,8 +34,7 @@ vi.mock("../../core/transport.js", async () => ({
 }));
 
 import { paginate } from "../../core/helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides } from "../../__tests__/test-utils.js";
 import { fetchUrl } from "../../core/transport.js";
 
 // Drain any under-consumed Once-queue so a leaky test can't shift its
@@ -124,15 +117,10 @@ const PAGE2 = JSON.stringify({
 let tmpBase: string;
 
 async function setupRecipe(): Promise<{ guide: ApiGuide }> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "frost-sensorthings");
-	mkdirSync(domainDir, { recursive: true });
-	const source = readFileSync(new URL("./guide.md", import.meta.url), "utf-8");
-	writeFileSync(join(domainDir, "guide.md"), source, "utf-8");
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return { guide: loaded.guides["frost-sensorthings"]! };
+	const { guides } = stageGuides(tmpBase, new URL("../", import.meta.url), [
+		"frost-sensorthings",
+	]);
+	return { guide: guides["frost-sensorthings"]! };
 }
 
 beforeAll(() => {

package/node_modules/pi-lean-host/api-guides/github/static-key.test.ts

@@ -15,16 +15,10 @@
  */
 
 import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { ApiGuide, Operation } from "../../core/api-guide-types.js";
+import type { ApiGuide } from "../../core/api-guide-types.js";
 
 // Mock the transport layer BEFORE any imports that use it.
 vi.mock("../../core/transport.js", async () => ({
@@ -35,27 +29,15 @@ vi.mock("../../core/transport.js", async () => ({
 }));
 
 import { restGet, paginate } from "../../core/helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides, findOp } from "../../__tests__/test-utils.js";
 
 let tmpBase: string;
 
 async function setupRecipe(): Promise<{ guide: ApiGuide }> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "github");
-	mkdirSync(domainDir, { recursive: true });
-	const source = readFileSync(new URL("./guide.md", import.meta.url), "utf-8");
-	writeFileSync(join(domainDir, "guide.md"), source, "utf-8");
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return { guide: loaded.guides["github"]! };
-}
-
-function findOp(guide: ApiGuide, name: string): Operation {
-	const op = guide.operations.find((o) => o.name === name);
-	if (!op) throw new Error(`op ${name} not found`);
-	return op;
+	const { guides } = stageGuides(tmpBase, new URL("../", import.meta.url), [
+		"github",
+	]);
+	return { guide: guides["github"]! };
 }
 
 beforeAll(() => {

package/node_modules/pi-lean-host/api-guides/inaturalist/derived-id.test.ts

@@ -20,13 +20,7 @@ import {
 	afterAll,
 	beforeEach,
 } from "vitest";
-import {
-	mkdtempSync,
-	mkdirSync,
-	writeFileSync,
-	rmSync,
-	readFileSync,
-} from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ApiGuide } from "../../core/api-guide-types.js";
@@ -41,8 +35,7 @@ vi.mock("../../core/transport.js", async () => ({
 
 import { fetchUrl } from "../../core/transport.js";
 import { paginate } from "../../core/helpers.js";
-import { loadApiGuidesFromDir } from "../../core/guide-catalog.js";
-import { setUserGuidesDir, invalidateCache } from "../../core/guide-store.js";
+import { stageGuides } from "../../__tests__/test-utils.js";
 
 // Drain any under-consumed Once-queue so a leaky test can't shift its
 // leftover pages into the next test (mockReset also clears calls).
@@ -100,15 +93,10 @@ const PAGE3 = JSON.stringify({
 let tmpBase: string;
 
 async function setupRecipe(): Promise<{ guide: ApiGuide }> {
-	const guidesDir = mkdtempSync(join(tmpBase, "guides-"));
-	const domainDir = join(guidesDir, "inaturalist");
-	mkdirSync(domainDir, { recursive: true });
-	const source = readFileSync(new URL("./guide.md", import.meta.url), "utf-8");
-	writeFileSync(join(domainDir, "guide.md"), source, "utf-8");
-	setUserGuidesDir(guidesDir);
-	invalidateCache();
-	const loaded = loadApiGuidesFromDir(guidesDir);
-	return { guide: loaded.guides["inaturalist"]! };
+	const { guides } = stageGuides(tmpBase, new URL("../", import.meta.url), [
+		"inaturalist",
+	]);
+	return { guide: guides["inaturalist"]! };
 }
 
 beforeAll(() => {