@untestutils/core 0.5.0

package/dist/lock.mjs

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "pathe";
+import { debug } from "./debug.mjs";
+const DEFAULT_STALE_MS = 10 * 60 * 1e3;
+const HEARTBEAT_MS = 5e3;
+function isPidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+export class FileLock {
+	lockPath;
+	identity;
+	staleMs;
+	heartbeat;
+	held = false;
+	constructor(lockPath, identity, staleMs = DEFAULT_STALE_MS) {
+		this.lockPath = lockPath;
+		this.identity = identity;
+		this.staleMs = staleMs;
+	}
+	async acquire(timeoutMs = 12e4) {
+		await mkdir(dirname(this.lockPath), { recursive: true });
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			try {
+				const handle = await open(this.lockPath, "wx");
+				const info = {
+					pid: process.pid,
+					startedAt: Date.now(),
+					heartbeatAt: Date.now(),
+					identity: this.identity
+				};
+				await handle.writeFile(JSON.stringify(info), "utf8");
+				await handle.close();
+				this.held = true;
+				this.startHeartbeat();
+				debug("lock", `acquired ${this.lockPath}`);
+				return;
+			} catch (error) {
+				const code = error.code;
+				if (code !== "EEXIST") throw error;
+				
+				if (await this.tryStealStale()) continue;
+				await sleep(200);
+			}
+		}
+		throw new Error(`[untestutils] timed out waiting for lock: ${this.lockPath}`);
+	}
+	async release() {
+		this.stopHeartbeat();
+		if (!this.held) return;
+		try {
+			const raw = await readFile(this.lockPath, "utf8");
+			const info = JSON.parse(raw);
+			if (info.pid === process.pid) {
+				await unlink(this.lockPath);
+			}
+		} catch {}
+		this.held = false;
+		debug("lock", `released ${this.lockPath}`);
+	}
+	startHeartbeat() {
+		this.heartbeat = setInterval(() => {
+			void this.beat();
+		}, HEARTBEAT_MS);
+		this.heartbeat.unref?.();
+	}
+	stopHeartbeat() {
+		if (this.heartbeat) clearInterval(this.heartbeat);
+		this.heartbeat = undefined;
+	}
+	async beat() {
+		try {
+			const info = {
+				pid: process.pid,
+				startedAt: Date.now(),
+				heartbeatAt: Date.now(),
+				identity: this.identity
+			};
+			
+			try {
+				const prev = JSON.parse(await readFile(this.lockPath, "utf8"));
+				info.startedAt = prev.startedAt;
+			} catch {}
+			await writeFile(this.lockPath, JSON.stringify(info), "utf8");
+		} catch {}
+	}
+	async tryStealStale() {
+		try {
+			const raw = await readFile(this.lockPath, "utf8");
+			const info = JSON.parse(raw);
+			const staleByTime = Date.now() - (info.heartbeatAt || info.startedAt) > this.staleMs;
+			const dead = !isPidAlive(info.pid);
+			if (staleByTime || dead) {
+				debug("lock", `stealing stale lock pid=${info.pid} dead=${dead}`);
+				await unlink(this.lockPath);
+				return true;
+			}
+		} catch {
+			try {
+				const s = await stat(this.lockPath);
+				if (Date.now() - s.mtimeMs > this.staleMs) {
+					await unlink(this.lockPath);
+					return true;
+				}
+			} catch {}
+		}
+		return false;
+	}
+}
+export async function atomicWriteJson(path, data) {
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+	await writeFile(tmp, JSON.stringify(data, null, 2), "utf8");
+	await rename(tmp, path);
+}
+export async function atomicWriteText(path, content) {
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+	await writeFile(tmp, content, "utf8");
+	await rename(tmp, path);
+}
+export async function markReady(readyPath) {
+	await atomicWriteText(readyPath, String(Date.now()));
+}
+export async function isReady(readyPath) {
+	return existsSync(readyPath);
+}
+export async function removePath(path) {
+	await rm(path, {
+		recursive: true,
+		force: true
+	});
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+export function lockPathFor(artifactsRoot, identity) {
+	return join(artifactsRoot, "locks", `${identity}.lock`);
+}

package/dist/orchestrator.d.mts

@@ -0,0 +1,19 @@
+import type { Recipe, Running } from "./types.mjs";
+export interface OrchestratorOptions {
+	artifactsRoot?: string;
+	cwd?: string;
+}
+export interface PreparedTarget {
+	id: string;
+	identity: string;
+	hash: string;
+	outDir: string;
+	running: Running;
+	recipe: Recipe;
+}
+export declare function resolveRecipe(input: string | Recipe): Promise<Recipe>;
+export declare function ensurePrepared(recipeInput: string | Recipe, opts?: OrchestratorOptions): Promise<PreparedTarget>;
+export declare function stopAllTargets(artifactsRoot?: string): Promise<void>;
+/** Kill leftover registry servers from a previous crashed run (call at globalSetup start). */
+export declare function reclaimStaleTargets(artifactsRoot?: string): Promise<void>;
+export declare function createHarnessHandle(prepared: PreparedTarget): import("./types").HarnessHandle;

package/dist/orchestrator.d.ts

@@ -0,0 +1,22 @@
+import type { Recipe, Running } from './types';
+export interface OrchestratorOptions {
+    artifactsRoot?: string;
+    cwd?: string;
+}
+export interface PreparedTarget {
+    id: string;
+    identity: string;
+    hash: string;
+    outDir: string;
+    running: Running;
+    recipe: Recipe;
+}
+export declare function resolveRecipe(input: string | Recipe): Promise<Recipe>;
+export declare function ensurePrepared(recipeInput: string | Recipe, opts?: OrchestratorOptions): Promise<PreparedTarget>;
+export declare function stopAllTargets(artifactsRoot?: string): Promise<void>;
+/** Kill leftover registry servers from a previous crashed run (call at globalSetup start). */
+export declare function reclaimStaleTargets(artifactsRoot?: string): Promise<void>;
+/** @internal clear in-process maps without stopping servers (coverage of registry reuse). */
+export declare function detachLiveTargetsForTests(): void;
+export declare function createHarnessHandle(prepared: PreparedTarget): import('./types').HarnessHandle;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAe,MAAM,SAAS,CAAC;AAM5D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAiBD,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3E;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAoIzB;AAkGD,wBAAsB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC1E;AAED,8FAA8F;AAC9F,wBAAsB,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E;AAED,6FAA6F;AAC7F,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,SAAS,EAAE,aAAa,CA0B7F"}

package/dist/orchestrator.mjs

@@ -0,0 +1,343 @@
+import { mkdir, writeFile, readdir, readFile, access } from "node:fs/promises";
+import { join } from "pathe";
+import { ArtifactStore } from "./artifact-store.mjs";
+import { debug, envFlag } from "./debug.mjs";
+import { assertUniqueRecipeBinding, computeIdentity } from "./identity.mjs";
+import { FileLock, lockPathFor } from "./lock.mjs";
+import { loopbackUrl, resolveArtifactsRoot, resolveBindHost } from "./paths.mjs";
+import { getFreePort } from "./ports.mjs";
+import { progress } from "./progress.mjs";
+import { defaultReady } from "./ready.mjs";
+import { createRunHelper } from "./run-helper.mjs";
+import { TargetRegistry } from "./target-registry.mjs";
+import { getRegisteredRecipe } from "./recipes.mjs";
+import { isPidAlive, killPidTree } from "./process.mjs";
+import { ofetch } from "ofetch";
+import { constants } from "node:fs";
+const liveStops = new Map();
+const liveRunning = new Map();
+const liveMeta = new Map();
+function rememberLive(id, running, meta, stop) {
+	liveRunning.set(id, running);
+	liveMeta.set(id, meta);
+	if (stop) liveStops.set(id, stop);
+}
+export async function resolveRecipe(input) {
+	if (typeof input === "string") {
+		const r = getRegisteredRecipe(input);
+		if (!r) throw new Error(`[untestutils] unknown recipe id "${input}". Did you call defineRecipes()?`);
+		return r;
+	}
+	return input;
+}
+export async function ensurePrepared(recipeInput, opts = {}) {
+	const recipe = await resolveRecipe(recipeInput);
+	const artifactsRoot = opts.artifactsRoot ?? resolveArtifactsRoot(opts.cwd);
+	const root = recipe.root;
+	const { identity, hash, id } = await computeIdentity(recipe, artifactsRoot, root);
+	const share = envFlag("UNTESTUTILS_SHARE", true) ? recipe.share ?? "always" : "never";
+	
+	if (share !== "never") {
+		assertUniqueRecipeBinding(id, identity);
+	}
+	if (envFlag("UNTESTUTILS_SHARE", true) === false && recipe.share !== "never") {}
+	const store = new ArtifactStore(artifactsRoot);
+	const registry = new TargetRegistry(artifactsRoot);
+	
+	const live = liveRunning.get(id);
+	if (live) {
+		const bound = liveMeta.get(id);
+		return {
+			id,
+			identity: bound?.identity ?? identity,
+			hash: bound?.hash ?? hash,
+			outDir: bound?.outDir ?? store.buildDir(identity),
+			running: live,
+			recipe
+		};
+	}
+	
+	
+	if (share === "always" || share === "never") {
+		const reused = await tryReuseRegistry(registry, store, id, identity, hash, share);
+		if (reused) return {
+			...reused,
+			recipe
+		};
+	}
+	
+	const lockKey = share === "never" ? id : identity;
+	const lock = new FileLock(lockPathFor(artifactsRoot, lockKey), lockKey);
+	await lock.acquire();
+	try {
+		
+		if (share === "always" || share === "never") {
+			const reused = await tryReuseRegistry(registry, store, id, identity, hash, share);
+			if (reused) return {
+				...reused,
+				recipe
+			};
+		}
+		const outDir = await store.ensureDir(identity);
+		const run = createRunHelper({
+			cwd: root,
+			env: scrubEnv()
+		});
+		if (!await store.isWarm(identity, hash)) {
+			if (recipe.prepare) {
+				progress.prepareStart(id);
+				const started = Date.now();
+				try {
+					await recipe.prepare({
+						root,
+						outDir,
+						artifactsRoot,
+						env: scrubEnv(),
+						run
+					});
+					if (recipe.verifyArtifact) await recipe.verifyArtifact(outDir);
+					await store.commit(identity, hash);
+					progress.prepareDone(id, Date.now() - started);
+				} catch (err) {
+					progress.fail(id, err);
+					throw err;
+				}
+			} else {
+				await store.commit(identity, hash);
+			}
+		} else {
+			progress.prepareCache(id);
+			debug("prepare", `cache hit ${id}`);
+		}
+		if (share === "prepare-only") {
+			const running = {
+				kind: "dir",
+				dir: outDir
+			};
+			await registry.set({
+				id,
+				identity,
+				dir: outDir
+			});
+			rememberLive(id, running, {
+				identity,
+				hash,
+				outDir
+			});
+			return {
+				id,
+				identity,
+				hash,
+				outDir,
+				running,
+				recipe
+			};
+		}
+		const bindHost = resolveBindHost();
+		const port = await getFreePort(bindHost);
+		const startCtx = {
+			root,
+			outDir,
+			artifactsRoot,
+			port,
+			host: bindHost,
+			env: scrubEnv(),
+			run: createRunHelper({
+				cwd: root,
+				env: {
+					...scrubEnv(),
+					PORT: String(port),
+					HOST: bindHost
+				}
+			})
+		};
+		progress.start(id, loopbackUrl(port, "/", bindHost));
+		try {
+			const running = await recipe.start(startCtx);
+			if (recipe.ready) await recipe.ready(running);
+			else await defaultReady(running);
+			rememberLive(id, running, {
+				identity,
+				hash,
+				outDir
+			}, running.stop);
+			await replaceRegistryEntry(registry, {
+				id,
+				identity,
+				url: "url" in running ? running.url : undefined,
+				dir: "dir" in running ? running.dir : outDir,
+				pid: running.pid
+			});
+			await writeEnvSnapshot(outDir, {
+				id,
+				identity,
+				port,
+				hash
+			});
+			return {
+				id,
+				identity,
+				hash,
+				outDir,
+				running,
+				recipe
+			};
+		} catch (err) {
+			progress.fail(id, err);
+			throw err;
+		}
+	} finally {
+		await lock.release();
+	}
+}
+
+async function replaceRegistryEntry(registry, entry) {
+	const prev = await registry.set(entry);
+	if (prev?.pid && prev.pid !== entry.pid && isPidAlive(prev.pid)) {
+		debug("teardown", `replacing ${entry.id} — kill old pid ${prev.pid}`);
+		await killPidTree(prev.pid);
+	}
+}
+function scrubEnv() {
+	const env = { ...process.env };
+	for (const k of [
+		"VITEST",
+		"VITEST_WORKER_ID",
+		"TEST",
+		"JEST_WORKER_ID",
+		"JEST"
+	]) delete env[k];
+	return env;
+}
+async function tryReuseRegistry(registry, store, id, identity, hash, share) {
+	const existing = await registry.get(id);
+	if (!existing?.url) return undefined;
+	const warmOk = share === "never" ? true : await store.isWarm(identity, hash);
+	if (!warmOk) return undefined;
+	
+	if (existing.pid !== null && existing.pid !== undefined && !isPidAlive(existing.pid)) {
+		debug("registry", `stale pid ${existing.pid} for ${id}`);
+		return undefined;
+	}
+	if (!await isUrlAlive(existing.url)) return undefined;
+	const outDir = existing.dir ?? store.buildDir(identity);
+	const running = {
+		kind: "url+dir",
+		url: existing.url,
+		dir: outDir,
+		pid: existing.pid
+	};
+	progress.prepareCache(id);
+	progress.start(id, existing.url);
+	
+	const stop = existing.pid !== null && existing.pid !== undefined ? async () => {
+		await killPidTree(existing.pid);
+	} : undefined;
+	rememberLive(id, running, {
+		identity,
+		hash,
+		outDir
+	}, stop);
+	
+	registry.applyEnv({
+		...existing,
+		url: existing.url
+	});
+	return {
+		id,
+		identity,
+		hash,
+		outDir,
+		running
+	};
+}
+async function isUrlAlive(url) {
+	try {
+		const ctrl = new AbortController();
+		const t = setTimeout(() => ctrl.abort(), 1500);
+		const res = await fetch(url, { signal: ctrl.signal });
+		clearTimeout(t);
+		return res.status < 500;
+	} catch {
+		
+		return false;
+	}
+}
+async function writeEnvSnapshot(outDir, info) {
+	try {
+		await mkdir(outDir, { recursive: true });
+		const env = {};
+		for (const [k, v] of Object.entries(scrubEnv())) {
+			if (v !== undefined && !/secret|token|password|key/i.test(k)) env[k] = v;
+		}
+		await writeFile(join(outDir, "env.snapshot.json"), JSON.stringify({
+			...info,
+			node: process.version,
+			env
+		}, null, 2), "utf8");
+	} catch {}
+}
+export async function stopAllTargets(artifactsRoot) {
+	const stops = [...liveStops.entries()];
+	liveStops.clear();
+	liveRunning.clear();
+	liveMeta.clear();
+	await Promise.all(stops.map(async ([id, stop]) => {
+		try {
+			await stop();
+			debug("teardown", `stopped ${id}`);
+		} catch (e) {
+			debug("teardown", `failed ${id}`, e);
+		}
+	}));
+	
+	
+	const root = artifactsRoot ?? resolveArtifactsRoot();
+	const registry = new TargetRegistry(root);
+	const map = await registry.drain();
+	const pids = Object.values(map).map((e) => e.pid).filter((p) => typeof p === "number" && p > 1);
+	await Promise.all(pids.map(async (pid) => {
+		try {
+			await killPidTree(pid);
+			debug("teardown", `killed registry pid ${pid}`);
+		} catch (e) {
+			debug("teardown", `failed registry pid ${pid}`, e);
+		}
+	}));
+}
+
+export async function reclaimStaleTargets(artifactsRoot) {
+	await stopAllTargets(artifactsRoot);
+}
+
+export function detachLiveTargetsForTests() {
+	liveStops.clear();
+	liveRunning.clear();
+	liveMeta.clear();
+}
+export function createHarnessHandle(prepared) {
+	const url = "url" in prepared.running ? prepared.running.url : undefined;
+	const dir = "dir" in prepared.running ? prepared.running.dir : prepared.outDir;
+	return {
+		id: prepared.id,
+		url,
+		dir,
+		$fetch: ((request, opts) => {
+			if (!url) throw new Error(`[untestutils] recipe "${prepared.id}" has no url for $fetch`);
+			const target = request.startsWith("http") ? request : new URL(request, url).toString();
+			return ofetch(target, opts);
+		}),
+		files: {
+			read: async (rel) => readFile(join(dir, rel), "utf8"),
+			exists: async (rel) => {
+				try {
+					await access(join(dir, rel), constants.F_OK);
+					return true;
+				} catch {
+					return false;
+				}
+			},
+			list: async (rel = ".") => readdir(join(dir, rel))
+		}
+	};
+}

package/dist/paths.d.mts

@@ -0,0 +1,20 @@
+/** Default IPv4 loopback — prefer this over `localhost` (::1 trap). */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/**
+* Host used to bind local servers and allocate free ports.
+* Override with `UNTESTUTILS_BIND_HOST` (e.g. `0.0.0.0` to listen on all interfaces;
+* ready probes still hit `127.0.0.1` via {@link resolveProbeHost}).
+*/
+export declare function resolveBindHost(): string;
+/** Host used in ready-check / harness URLs — never a wildcard bind address. */
+export declare function resolveProbeHost(bindHost?: string): string;
+export declare function loopbackUrl(port: number, path?: string, host?: string): string;
+export declare function normalizeBaseUrl(url: string): string;
+export declare function resolveArtifactsRoot(cwd?: string): string;
+export declare function findRepoRoot(start?: string): string;
+export declare function assertNotInsideWorkspacePackage(artifactsRoot: string, workspaceRoots: string[]): void;
+/** Refuse writing builds into a directory that is a workspace package (has package.json + is under workspace). */
+export declare function refuseArtifactsInsidePackage(outDir: string): void;
+export declare function isWorkspacePackageDir(dir: string): boolean;
+export declare function toFilePath(urlOrPath: string | URL): string;
+export declare function expandHome(path: string): string;

package/dist/paths.d.ts

@@ -0,0 +1,21 @@
+/** Default IPv4 loopback — prefer this over `localhost` (::1 trap). */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * Host used to bind local servers and allocate free ports.
+ * Override with `UNTESTUTILS_BIND_HOST` (e.g. `0.0.0.0` to listen on all interfaces;
+ * ready probes still hit `127.0.0.1` via {@link resolveProbeHost}).
+ */
+export declare function resolveBindHost(): string;
+/** Host used in ready-check / harness URLs — never a wildcard bind address. */
+export declare function resolveProbeHost(bindHost?: string): string;
+export declare function loopbackUrl(port: number, path?: string, host?: string): string;
+export declare function normalizeBaseUrl(url: string): string;
+export declare function resolveArtifactsRoot(cwd?: string): string;
+export declare function findRepoRoot(start?: string): string;
+export declare function assertNotInsideWorkspacePackage(artifactsRoot: string, workspaceRoots: string[]): void;
+/** Refuse writing builds into a directory that is a workspace package (has package.json + is under workspace). */
+export declare function refuseArtifactsInsidePackage(outDir: string): void;
+export declare function isWorkspacePackageDir(dir: string): boolean;
+export declare function toFilePath(urlOrPath: string | URL): string;
+export declare function expandHome(path: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAKA,uEAAuE;AACvE,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAKxC;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAI7E;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAY,EAClB,IAAI,GAAE,MAA0B,GAC/B,MAAM,CAIR;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAapD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAMxE;AAED,wBAAgB,YAAY,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,CAUlE;AAED,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EAAE,GACvB,IAAI,CAsBN;AAED,kHAAkH;AAClH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAkCjE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAM1D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C"}