@untestutils/core 0.5.0

package/dist/progress.mjs

@@ -0,0 +1,205 @@
+import { envFlag, isDebug } from "./debug.mjs";
+const ID_WIDTH = 22;
+
+export function isCi() {
+	if (envFlag("CI", false)) return true;
+	const keys = [
+		"GITHUB_ACTIONS",
+		"GITLAB_CI",
+		"CIRCLECI",
+		"BUILDKITE",
+		"TF_BUILD",
+		"TEAMCITY_VERSION",
+		"JENKINS_URL"
+	];
+	return keys.some((k) => {
+		const v = process.env[k];
+		return v !== undefined && v !== "" && v !== "0" && v !== "false";
+	});
+}
+
+export function isProgressEnabled() {
+	if (envFlag("UNTESTUTILS_QUIET", false)) return false;
+	const explicit = process.env.UNTESTUTILS_PROGRESS;
+	if (explicit === "0" || explicit === "false") return false;
+	if (explicit === "1" || explicit === "true") return true;
+	if (isCi()) return false;
+	return true;
+}
+
+export function isQuiet() {
+	return !isProgressEnabled();
+}
+function useFancy() {
+	if (!isProgressEnabled()) return false;
+	if (isCi()) return false;
+	return process.stdout.isTTY === true;
+}
+
+export const progressIo = {
+	lines: [],
+	capture: false,
+	bannerShown: false,
+	wave: null,
+	write(line) {
+		process.stdout.write(`${line}\n`);
+	},
+	writeErr(line) {
+		process.stderr.write(`${line}\n`);
+	},
+	reset() {
+		this.lines = [];
+		this.capture = false;
+		this.bannerShown = false;
+		this.wave = null;
+	}
+};
+function padId(s) {
+	if (s.length > ID_WIDTH) return `${s.slice(0, ID_WIDTH - 1)}…`;
+	return s.padEnd(ID_WIDTH);
+}
+function emit(line) {
+	if (!isProgressEnabled()) return;
+	if (progressIo.capture) {
+		progressIo.lines.push(line);
+		return;
+	}
+	progressIo.write(line);
+}
+function ensureBanner() {
+	if (progressIo.bannerShown || !isProgressEnabled()) return;
+	progressIo.bannerShown = true;
+	emit(useFancy() ? "◆ untestutils  ·  mass e2e on live targets" : "[untestutils] mass e2e on live targets");
+}
+function formatDuration(ms) {
+	if (ms < 1e3) return `${ms}ms`;
+	if (ms < 1e4) return `${(ms / 1e3).toFixed(1)}s`;
+	return `${Math.round(ms / 1e3)}s`;
+}
+function errMessage(err) {
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+function check(ok = true) {
+	if (!useFancy()) return ok ? "+" : "x";
+	return ok ? "✔" : "✖";
+}
+function arrow() {
+	return useFancy() ? "▸" : ">";
+}
+
+export const progress = {
+	
+	waveStart(ids) {
+		ensureBanner();
+		const total = ids.length;
+		progressIo.wave = {
+			total,
+			ready: 0,
+			building: new Set(),
+			active: true,
+			startedAt: Date.now(),
+			massRunShown: false
+		};
+		emit("");
+		emit(`${arrow()} prepare once` + (useFancy() ? "  — every worker reuses the same builds" : `  (${total} recipes, shared across workers)`));
+		if (total) {
+			emit(`  ${total} recipes in the wave`);
+		}
+	},
+	
+	prewarm(ids) {
+		progress.waveStart(ids);
+	},
+	prepareStart(id) {
+		ensureBanner();
+		if (progressIo.wave?.active) {
+			progressIo.wave.building.add(id);
+			emit(`  ${padId(id)}  building…`);
+			return;
+		}
+		emit(`  ${useFancy() ? "●" : "*"} ${padId(id)}  building…`);
+	},
+	prepareDone(id, ms) {
+		ensureBanner();
+		if (progressIo.wave?.active) {
+			progressIo.wave.building.delete(id);
+			progressIo.wave.ready += 1;
+			emit(`  ${check()} ${padId(id)}  built · ${formatDuration(ms)}`);
+			return;
+		}
+		emit(`  ${check()} ${padId(id)}  built · ${formatDuration(ms)}`);
+	},
+	prepareCache(id) {
+		ensureBanner();
+		if (progressIo.wave?.active) {
+			progressIo.wave.building.delete(id);
+			progressIo.wave.ready += 1;
+			emit(`  ${check()} ${padId(id)}  cached`);
+			return;
+		}
+		emit(`  ${check()} ${padId(id)}  cached`);
+	},
+	
+	waveReady() {
+		const wave = progressIo.wave;
+		if (!wave?.active) return;
+		wave.active = false;
+		const ready = wave.ready || wave.total;
+		const total = wave.total || ready;
+		emit(`  ${check()} ${ready}/${total} warm` + (useFancy() ? "  ·  shared host registry" : "  · shared hosts"));
+	},
+	
+	massRun() {
+		ensureBanner();
+		if (progressIo.wave?.massRunShown) return;
+		if (progressIo.wave) progressIo.wave.massRunShown = true;
+		emit("");
+		emit(`${arrow()} mass run` + (useFancy() ? "  live URLs · real cookies/SEO/$fetch · no per-file rebuild" : "  live URLs · shared prepare"));
+	},
+	start(id, url) {
+		ensureBanner();
+		
+		if (progressIo.wave?.active) return;
+		
+		if (progressIo.wave && !progressIo.wave.massRunShown) {
+			progress.massRun();
+		}
+		emit(`  ${useFancy() ? "→" : ">"} ${padId(id)}  ${url}`);
+	},
+	teardown() {
+		ensureBanner();
+		const wave = progressIo.wave;
+		emit("");
+		if (wave && wave.total > 0) {
+			const elapsed = formatDuration(Date.now() - wave.startedAt);
+			emit(`  ${wave.ready || wave.total} recipes prepared once` + (useFancy() ? `  ·  session ${elapsed}` : `  · ${elapsed}`));
+		}
+		emit(useFancy() ? "  prepare once  →  many workers  →  real URLs & data" : "  teardown  stop");
+		emit(`  ${useFancy() ? "■" : "="} teardown`);
+	},
+	
+	fail(id, err) {
+		const line = `  ${check(false)} ${padId(id)}  ${errMessage(err)}`;
+		if (progressIo.capture) {
+			progressIo.lines.push(line);
+			return;
+		}
+		progressIo.writeErr(line);
+		if (err instanceof Error && err.stack && isDebug()) {
+			progressIo.writeErr(err.stack);
+		}
+	}
+};
+
+export async function withQuietLogger(fn) {
+	if (isDebug() || !isProgressEnabled()) return fn();
+	const { consola, LogLevels } = await import("consola");
+	const prev = consola.level;
+	consola.level = LogLevels.error;
+	try {
+		return await fn();
+	} finally {
+		consola.level = prev;
+	}
+}

package/dist/ready.d.mts

@@ -0,0 +1,11 @@
+import type { Running } from "./types.mjs";
+export interface ReadyOptions {
+	timeoutMs?: number;
+	path?: string;
+	acceptStatuses?: number[];
+	rejectBodyIncludes?: string[];
+	/** Skip TCP probe (default: skip for non-loopback hosts). */
+	skipTcp?: boolean;
+}
+export declare function waitForHttpReady(url: string, opts?: ReadyOptions): Promise<void>;
+export declare function defaultReady(running: Running, opts?: ReadyOptions): Promise<void>;

package/dist/ready.d.ts

@@ -0,0 +1,12 @@
+import type { Running } from './types';
+export interface ReadyOptions {
+    timeoutMs?: number;
+    path?: string;
+    acceptStatuses?: number[];
+    rejectBodyIncludes?: string[];
+    /** Skip TCP probe (default: skip for non-loopback hosts). */
+    skipTcp?: boolean;
+}
+export declare function waitForHttpReady(url: string, opts?: ReadyOptions): Promise<void>;
+export declare function defaultReady(running: Running, opts?: ReadyOptions): Promise<void>;
+//# sourceMappingURL=ready.d.ts.map

package/dist/ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../src/ready.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgF1F;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}

package/dist/ready.mjs

@@ -0,0 +1,142 @@
+import { ofetch } from "ofetch";
+import { debug } from "./debug.mjs";
+import { LOOPBACK_HOST } from "./paths.mjs";
+import { waitForPort } from "./ports.mjs";
+export async function waitForHttpReady(url, opts = {}) {
+	const timeoutMs = opts.timeoutMs ?? 6e4;
+	const path = opts.path ?? "/";
+	const accept = new Set(opts.acceptStatuses ?? [
+		200,
+		301,
+		302,
+		304,
+		307,
+		308
+	]);
+	const rejectBody = opts.rejectBodyIncludes ?? ["__NUXT_LOADING__"];
+	const target = new URL(path, url).toString();
+	const deadline = Date.now() + timeoutMs;
+	let lastStatus = 0;
+	let lastBody = "";
+	let lastError = "";
+	let phase = "http";
+	const endpoint = parseHostPort(target);
+	const skipTcp = opts.skipTcp ?? (endpoint ? !isLoopbackHost(endpoint.host) : true);
+	if (endpoint && !skipTcp) {
+		phase = "tcp";
+		const tcpBudget = Math.max(0, deadline - Date.now());
+		if (tcpBudget <= 0) {
+			throw readinessError(target, timeoutMs, {
+				phase,
+				lastStatus,
+				lastBody,
+				lastError: "timeout before tcp probe"
+			});
+		}
+		try {
+			await waitForPort(endpoint.port, endpoint.host, tcpBudget);
+			debug("ready", `tcp open ${endpoint.host}:${endpoint.port}`);
+		} catch (e) {
+			lastError = errMessage(e);
+			throw readinessError(target, timeoutMs, {
+				phase: "tcp",
+				lastStatus: 0,
+				lastBody: "",
+				lastError,
+				hint: `Nothing accepted TCP on ${endpoint.host}:${endpoint.port}. Check the server binds that host (set HOST / --host, or UNTESTUTILS_BIND_HOST).`
+			});
+		}
+	}
+	phase = "http";
+	while (Date.now() < deadline) {
+		try {
+			const res = await ofetch.raw(target, {
+				method: "GET",
+				redirect: "manual",
+				ignoreResponseError: true,
+				responseType: "text",
+				timeout: 5e3
+			});
+			lastStatus = res.status;
+			lastBody = typeof res._data === "string" ? res._data.slice(0, 500) : "";
+			lastError = "";
+			if (res.status === 503) {
+				await sleep(200);
+				continue;
+			}
+			if (rejectBody.some((s) => lastBody.includes(s))) {
+				await sleep(200);
+				continue;
+			}
+			if (accept.has(res.status)) {
+				debug("ready", `ok ${target} status=${res.status}`);
+				return;
+			}
+			lastError = `unexpected status ${res.status} (accept ${[...accept].join(",")})`;
+		} catch (e) {
+			lastError = errMessage(e);
+		}
+		await sleep(200);
+	}
+	throw readinessError(target, timeoutMs, {
+		phase,
+		lastStatus,
+		lastBody,
+		lastError,
+		hint: httpReadyHint(endpoint, skipTcp)
+	});
+}
+export async function defaultReady(running, opts) {
+	if (running.kind === "dir") return;
+	const url = running.kind === "url" || running.kind === "url+dir" ? running.url : undefined;
+	if (!url) return;
+	await waitForHttpReady(url, opts);
+}
+function httpReadyHint(endpoint, skippedTcp) {
+	if (!endpoint) return undefined;
+	if (skippedTcp) {
+		return `Remote/non-loopback probe timed out. Raise readyTimeoutMs, set readyPath, or skipReady: true for host().`;
+	}
+	return `HTTP never became ready on ${endpoint.host}:${endpoint.port}. Confirm the process binds HOST (see UNTESTUTILS_BIND_HOST) and readyPath returns an accepted status.`;
+}
+function parseHostPort(href) {
+	try {
+		const u = new URL(href);
+		const host = u.hostname.replace(/^\[|\]$/g, "");
+		let port = u.port ? Number(u.port) : NaN;
+		if (!Number.isFinite(port) || port <= 0) {
+			if (u.protocol === "https:") port = 443;
+			else if (u.protocol === "http:") port = 80;
+			else return null;
+		}
+		if (!host) return null;
+		return {
+			host,
+			port
+		};
+	} catch {
+		return null;
+	}
+}
+function isLoopbackHost(host) {
+	const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+	return h === LOOPBACK_HOST || h === "127.0.0.1" || h === "localhost" || h === "::1";
+}
+function errMessage(e) {
+	if (e instanceof Error) return e.message;
+	return String(e);
+}
+function readinessError(target, timeoutMs, detail) {
+	const parts = [
+		`[untestutils] readiness failed for ${target} after ${timeoutMs}ms`,
+		`phase=${detail.phase}`,
+		`lastStatus=${detail.lastStatus}`
+	];
+	if (detail.lastError) parts.push(`lastError=${JSON.stringify(detail.lastError)}`);
+	if (detail.lastBody) parts.push(`body=${JSON.stringify(detail.lastBody.slice(0, 200))}`);
+	if (detail.hint) parts.push(detail.hint);
+	return new Error(parts.join(" · "));
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}

package/dist/recipes.d.mts

@@ -0,0 +1,23 @@
+import type { Recipe, RecipeRegistry } from "./types.mjs";
+/** Validate a recipe object (does not register). Prefer wrapping with defineRecipes. */
+export declare function defineRecipe(recipe: Recipe): Recipe;
+/**
+* Register recipes. Optionally pass `import.meta.url` so workers/globalSetup can
+* re-import the same file — otherwise the caller path is inferred from the stack.
+*
+* Prefer: `export const recipes = defineRecipes({ … }, import.meta.url)`
+*
+* Re-imports are idempotent (config + globalSetup/setup-file often load recipes.ts twice
+* under different module URLs). Duplicates *within* one call still throw.
+*/
+export declare function defineRecipes<T extends Record<string, Recipe>>(recipes: T, moduleUrl?: string | URL): T & RecipeRegistry;
+/**
+* Idempotent register for plugin options: skip ids already registered
+* (typical when recipes.ts already called defineRecipes and config passes the same map).
+*/
+export declare function ensureRecipes(recipes: Record<string, Recipe>): void;
+/** Absolute path to the recipes source module (for child processes). */
+export declare function getRecipesModulePath(): string | undefined;
+export declare function getRegisteredRecipe(id: string): Recipe | undefined;
+export declare function listRegisteredRecipes(): Recipe[];
+export declare function clearRegisteredRecipes(): void;

package/dist/recipes.d.ts

@@ -0,0 +1,24 @@
+import type { Recipe, RecipeRegistry } from './types';
+/** Validate a recipe object (does not register). Prefer wrapping with defineRecipes. */
+export declare function defineRecipe(recipe: Recipe): Recipe;
+/**
+ * Register recipes. Optionally pass `import.meta.url` so workers/globalSetup can
+ * re-import the same file — otherwise the caller path is inferred from the stack.
+ *
+ * Prefer: `export const recipes = defineRecipes({ … }, import.meta.url)`
+ *
+ * Re-imports are idempotent (config + globalSetup/setup-file often load recipes.ts twice
+ * under different module URLs). Duplicates *within* one call still throw.
+ */
+export declare function defineRecipes<T extends Record<string, Recipe>>(recipes: T, moduleUrl?: string | URL): T & RecipeRegistry;
+/**
+ * Idempotent register for plugin options: skip ids already registered
+ * (typical when recipes.ts already called defineRecipes and config passes the same map).
+ */
+export declare function ensureRecipes(recipes: Record<string, Recipe>): void;
+/** Absolute path to the recipes source module (for child processes). */
+export declare function getRecipesModulePath(): string | undefined;
+export declare function getRegisteredRecipe(id: string): Recipe | undefined;
+export declare function listRegisteredRecipes(): Recipe[];
+export declare function clearRegisteredRecipes(): void;
+//# sourceMappingURL=recipes.d.ts.map

package/dist/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMtD,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5D,OAAO,EAAE,CAAC,EACV,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,GACvB,CAAC,GAAG,cAAc,CAoBpB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQnE;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAEzD;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/recipes.mjs

@@ -0,0 +1,94 @@
+import { fileURLToPath } from "node:url";
+const globalRecipes = new Map();
+
+let recipesModulePath;
+
+export function defineRecipe(recipe) {
+	if (!recipe.id) {
+		throw new Error("[untestutils] defineRecipe requires recipe.id");
+	}
+	if (!recipe.start) {
+		throw new Error("[untestutils] defineRecipe requires recipe.start");
+	}
+	return recipe;
+}
+
+export function defineRecipes(recipes, moduleUrl) {
+	rememberRecipesModule(moduleUrl);
+	const ids = new Set();
+	for (const [key, recipe] of Object.entries(recipes)) {
+		const id = recipe.id ?? key;
+		if (ids.has(id)) {
+			throw new Error(`[untestutils] duplicate recipe id "${id}" in defineRecipes`);
+		}
+		ids.add(id);
+		if (globalRecipes.has(id)) {
+			
+			continue;
+		}
+		if (!recipe.id) recipe.id = key;
+		if (!recipe.start) {
+			throw new Error(`[untestutils] recipe "${id}" requires start()`);
+		}
+		globalRecipes.set(recipe.id, recipe);
+	}
+	return recipes;
+}
+
+export function ensureRecipes(recipes) {
+	const pending = {};
+	for (const [key, recipe] of Object.entries(recipes)) {
+		const id = recipe.id ?? key;
+		if (globalRecipes.has(id)) continue;
+		pending[key] = recipe;
+	}
+	if (Object.keys(pending).length) defineRecipes(pending);
+}
+
+export function getRecipesModulePath() {
+	return recipesModulePath;
+}
+export function getRegisteredRecipe(id) {
+	return globalRecipes.get(id);
+}
+export function listRegisteredRecipes() {
+	return [...globalRecipes.values()];
+}
+export function clearRegisteredRecipes() {
+	globalRecipes.clear();
+	recipesModulePath = undefined;
+}
+function rememberRecipesModule(moduleUrl) {
+	if (moduleUrl) {
+		recipesModulePath = toFsPath(moduleUrl);
+		return;
+	}
+	if (recipesModulePath) return;
+	const inferred = captureCallerPath();
+	if (inferred) recipesModulePath = inferred;
+}
+function toFsPath(moduleUrl) {
+	const href = typeof moduleUrl === "string" ? moduleUrl : moduleUrl.href;
+	return href.startsWith("file:") ? fileURLToPath(href) : href;
+}
+
+function captureCallerPath() {
+	const previous = Error.prepareStackTrace;
+	try {
+		Error.prepareStackTrace = (_err, stack) => stack;
+		const err = new Error();
+		const stack = err.stack;
+		for (let i = 2; i < stack.length; i++) {
+			const file = stack[i]?.getFileName();
+			if (!file || file.startsWith("node:")) continue;
+			if (/[/\\]recipes\.[cm]?[jt]s$/.test(file) && /[/\\](core|@untestutils)[/\\]/.test(file)) {
+				continue;
+			}
+			if (file.includes(`${"node_modules"}/@untestutils/core`)) continue;
+			return file.startsWith("file:") ? fileURLToPath(file) : file;
+		}
+	} catch {} finally {
+		Error.prepareStackTrace = previous;
+	}
+	return undefined;
+}

package/dist/run-helper.d.mts

@@ -0,0 +1,6 @@
+import type { RunHelper, RunResult } from "./types.mjs";
+export declare function createRunHelper(defaults?: {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+}): RunHelper;
+export type { RunResult };

package/dist/run-helper.d.ts

@@ -0,0 +1,7 @@
+import type { RunHelper, RunResult } from './types';
+export declare function createRunHelper(defaults?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): RunHelper;
+export type { RunResult };
+//# sourceMappingURL=run-helper.d.ts.map

package/dist/run-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-helper.d.ts","sourceRoot":"","sources":["../src/run-helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAsBrE,wBAAgB,eAAe,CAC7B,QAAQ,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,GACvD,SAAS,CA6CX;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/run-helper.mjs

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import { killProcessTree, runCommand, scrubTestEnv } from "./process.mjs";
+import { platform } from "node:os";
+function interpolate(strings, values) {
+	let out = "";
+	for (let i = 0; i < strings.length; i++) {
+		out += strings[i];
+		if (i < values.length) out += String(values[i]);
+	}
+	return out.trim();
+}
+function splitCommand(cmd) {
+	
+	const parts = cmd.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+	const cleaned = parts.map((p) => p.replace(/^['"]|['"]$/g, ""));
+	const [command, ...args] = cleaned;
+	if (!command) throw new Error("[untestutils] empty command");
+	return {
+		command,
+		args
+	};
+}
+export function createRunHelper(defaults = {}) {
+	const run = (async (strings, ...values) => {
+		const cmd = interpolate(strings, values);
+		const { command, args } = splitCommand(cmd);
+		const result = await runCommand(command, args, {
+			cwd: defaults.cwd,
+			env: {
+				...scrubTestEnv(),
+				...defaults.env
+			}
+		});
+		return result;
+	});
+	run.command = async (cmd, opts = {}) => {
+		const { command, args } = splitCommand(cmd);
+		return runCommand(command, args, {
+			cwd: opts.cwd ?? defaults.cwd,
+			env: {
+				...scrubTestEnv(),
+				...defaults.env,
+				...opts.env
+			}
+		});
+	};
+	run.detached = async (strings, ...values) => {
+		const cmd = interpolate(strings, values);
+		const { command, args } = splitCommand(cmd);
+		const env = {
+			...scrubTestEnv(),
+			...defaults.env
+		};
+		let output = "";
+		const child = spawn(command, args, {
+			cwd: defaults.cwd,
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: platform() !== "win32"
+		});
+		child.stdout?.on("data", (c) => {
+			output += c.toString();
+		});
+		child.stderr?.on("data", (c) => {
+			output += c.toString();
+		});
+		const proc = {
+			pid: child.pid,
+			stop: async () => killProcessTree(child),
+			logs: () => output
+		};
+		return proc;
+	};
+	return run;
+}

package/dist/target-registry.d.mts

@@ -0,0 +1,27 @@
+export interface TargetEntry {
+	id: string;
+	url?: string;
+	dir?: string;
+	identity: string;
+	/** Managed server pid — written by the starter worker so global teardown can kill orphans. */
+	pid?: number;
+}
+export type TargetMap = Record<string, TargetEntry>;
+export declare class TargetRegistry {
+	private readonly artifactsRoot;
+	constructor(artifactsRoot: string);
+	get filePath(): string;
+	private lockPath;
+	private withLock;
+	read(): Promise<TargetMap>;
+	write(map: TargetMap): Promise<void>;
+	set(entry: TargetEntry): Promise<TargetEntry | undefined>;
+	get(id: string): Promise<TargetEntry | undefined>;
+	applyAllToEnv(map: TargetMap): void;
+	applyEnv(entry: TargetEntry): void;
+	clear(): Promise<void>;
+	/** Atomically read + clear — used by global teardown so no pid is lost to races. */
+	drain(): Promise<TargetMap>;
+}
+export declare function envKey(id: string): string;
+export declare function envDirKey(id: string): string;

package/dist/target-registry.d.ts

@@ -0,0 +1,28 @@
+export interface TargetEntry {
+    id: string;
+    url?: string;
+    dir?: string;
+    identity: string;
+    /** Managed server pid — written by the starter worker so global teardown can kill orphans. */
+    pid?: number;
+}
+export type TargetMap = Record<string, TargetEntry>;
+export declare class TargetRegistry {
+    private readonly artifactsRoot;
+    constructor(artifactsRoot: string);
+    get filePath(): string;
+    private lockPath;
+    private withLock;
+    read(): Promise<TargetMap>;
+    write(map: TargetMap): Promise<void>;
+    set(entry: TargetEntry): Promise<TargetEntry | undefined>;
+    get(id: string): Promise<TargetEntry | undefined>;
+    applyAllToEnv(map: TargetMap): void;
+    applyEnv(entry: TargetEntry): void;
+    clear(): Promise<void>;
+    /** Atomically read + clear — used by global teardown so no pid is lost to races. */
+    drain(): Promise<TargetMap>;
+}
+export declare function envKey(id: string): string;
+export declare function envDirKey(id: string): string;
+//# sourceMappingURL=target-registry.d.ts.map

package/dist/target-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-registry.d.ts","sourceRoot":"","sources":["../src/target-registry.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAElD,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,OAAO,CAAC,QAAQ;YAIF,QAAQ;IAUhB,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC;IAS1B,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpC,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAgBzD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAiBvD,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAInC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAK5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,oFAAoF;IAC9E,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC;CAOlC;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C"}