@untestutils/core 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s00d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/artifact-store.d.mts

@@ -0,0 +1,19 @@
+import { SCHEMA_VERSION } from "./types.mjs";
+export interface BuildMeta {
+	schemaVersion: typeof SCHEMA_VERSION;
+	hash: string;
+	identity: string;
+	createdAt: number;
+}
+export declare class ArtifactStore {
+	private readonly artifactsRoot;
+	constructor(artifactsRoot: string);
+	buildDir(identity: string): string;
+	hashFile(identity: string): string;
+	readyFile(identity: string): string;
+	metaFile(identity: string): string;
+	ensureDir(identity: string): Promise<string>;
+	isWarm(identity: string, hash: string): Promise<boolean>;
+	commit(identity: string, hash: string): Promise<void>;
+	invalidate(identity: string): Promise<void>;
+}

package/dist/artifact-store.d.ts

@@ -0,0 +1,20 @@
+import { SCHEMA_VERSION } from './types';
+export interface BuildMeta {
+    schemaVersion: typeof SCHEMA_VERSION;
+    hash: string;
+    identity: string;
+    createdAt: number;
+}
+export declare class ArtifactStore {
+    private readonly artifactsRoot;
+    constructor(artifactsRoot: string);
+    buildDir(identity: string): string;
+    hashFile(identity: string): string;
+    readyFile(identity: string): string;
+    metaFile(identity: string): string;
+    ensureDir(identity: string): Promise<string>;
+    isWarm(identity: string, hash: string): Promise<boolean>;
+    commit(identity: string, hash: string): Promise<void>;
+    invalidate(identity: string): Promise<void>;
+}
+//# sourceMappingURL=artifact-store.d.ts.map

package/dist/artifact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-store.d.ts","sourceRoot":"","sources":["../src/artifact-store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKzC,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAElD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIlC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI5B,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOxD,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlD"}

package/dist/artifact-store.mjs

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "pathe";
+import { SCHEMA_VERSION } from "./types.mjs";
+import { isReady, markReady, removePath } from "./lock.mjs";
+import { debug } from "./debug.mjs";
+import { refuseArtifactsInsidePackage } from "./paths.mjs";
+export class ArtifactStore {
+	artifactsRoot;
+	constructor(artifactsRoot) {
+		this.artifactsRoot = artifactsRoot;
+	}
+	buildDir(identity) {
+		return join(this.artifactsRoot, "builds", identity);
+	}
+	hashFile(identity) {
+		return join(this.buildDir(identity), ".build-hash");
+	}
+	readyFile(identity) {
+		return join(this.buildDir(identity), ".ready");
+	}
+	metaFile(identity) {
+		return join(this.buildDir(identity), ".meta.json");
+	}
+	async ensureDir(identity) {
+		const dir = this.buildDir(identity);
+		refuseArtifactsInsidePackage(dir);
+		await mkdir(dir, { recursive: true });
+		return dir;
+	}
+	async isWarm(identity, hash) {
+		if (!await isReady(this.readyFile(identity))) return false;
+		if (!existsSync(this.hashFile(identity))) return false;
+		const stored = (await readFile(this.hashFile(identity), "utf8")).trim();
+		return stored === hash;
+	}
+	async commit(identity, hash) {
+		const meta = {
+			schemaVersion: SCHEMA_VERSION,
+			hash,
+			identity,
+			createdAt: Date.now()
+		};
+		await writeFile(this.hashFile(identity), hash, "utf8");
+		await writeFile(this.metaFile(identity), JSON.stringify(meta, null, 2), "utf8");
+		await markReady(this.readyFile(identity));
+		debug("artifact", `committed ${identity}`);
+	}
+	async invalidate(identity) {
+		await removePath(this.buildDir(identity));
+	}
+}

package/dist/debug.d.mts

@@ -0,0 +1,5 @@
+export declare function isDebug(): boolean;
+export declare function debug(scope: string, message: string, extra?: unknown): void;
+/** Non-lifecycle messages — stdout so Vitest does not label as [error]. */
+export declare function log(scope: string, message: string): void;
+export declare function envFlag(name: string, defaultValue?: boolean): boolean;

package/dist/debug.d.ts

@@ -0,0 +1,6 @@
+export declare function isDebug(): boolean;
+export declare function debug(scope: string, message: string, extra?: unknown): void;
+/** Non-lifecycle messages — stdout so Vitest does not label as [error]. */
+export declare function log(scope: string, message: string): void;
+export declare function envFlag(name: string, defaultValue?: boolean): boolean;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAEA,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAQ3E;AAED,2EAA2E;AAC3E,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAInE"}

package/dist/debug.mjs

@@ -0,0 +1,22 @@
+const PREFIX = "[untestutils";
+export function isDebug() {
+	return process.env.UNTESTUTILS_DEBUG === "1" || process.env.UNTESTUTILS_DEBUG === "true";
+}
+export function debug(scope, message, extra) {
+	if (!isDebug()) return;
+	
+	if (extra !== undefined) {
+		console.error(`${PREFIX}:${scope}] ${message}`, extra);
+	} else {
+		console.error(`${PREFIX}:${scope}] ${message}`);
+	}
+}
+
+export function log(scope, message) {
+	console.log(`${PREFIX}:${scope}] ${message}`);
+}
+export function envFlag(name, defaultValue = false) {
+	const v = process.env[name];
+	if (v === undefined) return defaultValue;
+	return v === "1" || v === "true";
+}

package/dist/drivers/cli-framework.d.mts

@@ -0,0 +1,57 @@
+import { type Recipe, type PrepareCtx, type StartCtx, type SharePolicy } from "../index.mjs";
+export interface ResolveBinOptions {
+	roots: string[];
+	packageJsonIds?: string[];
+	binRelative?: string[];
+	directIds?: string[];
+	label: string;
+}
+/**
+* Resolve a CLI entry from the app under test (or cwd).
+*/
+export declare function resolveBin(opts: ResolveBinOptions): string;
+export type SpawnSpec = {
+	command: string;
+	args: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+};
+export interface CliFrameworkRecipeOptions {
+	id: string;
+	root: string;
+	label: string;
+	share?: SharePolicy;
+	env?: Record<string, string>;
+	hashInputs?: string[];
+	readyPath?: string;
+	readyTimeoutMs?: number;
+	prepare?: (ctx: PrepareCtx & {
+		root: string;
+	}) => Promise<SpawnSpec | void> | SpawnSpec | void;
+	start: (ctx: StartCtx & {
+		root: string;
+	}) => SpawnSpec | Promise<SpawnSpec>;
+	verifyAfterPrepare?: (ctx: PrepareCtx & {
+		root: string;
+	}) => Promise<void>;
+}
+export type FrameworkBaseOptions = {
+	id?: string;
+	root: string;
+	env?: Record<string, string>;
+	hashInputs?: string[];
+	readyPath?: string;
+	readyTimeoutMs?: number;
+};
+export declare function frameworkRoots(root: string): string[];
+/**
+* Fail early with a clear message when a fixture root (or its package.json) is missing.
+* Call from prepare/start — not at Recipe factory time (hashInputs may use placeholder roots).
+*/
+export declare function assertAppRoot(root: string, label: string, opts?: {
+	requirePackageJson?: boolean;
+}): string;
+/**
+* Shared Recipe shell for framework CLI drivers (vite/next/astro/…).
+*/
+export declare function cliFrameworkRecipe(opts: CliFrameworkRecipeOptions): Recipe;

package/dist/drivers/cli-framework.d.ts

@@ -0,0 +1,64 @@
+import { runCommand, type Recipe, type PrepareCtx, type StartCtx, type SharePolicy } from '..';
+export interface ResolveBinOptions {
+    roots: string[];
+    packageJsonIds?: string[];
+    binRelative?: string[];
+    directIds?: string[];
+    label: string;
+}
+/**
+ * Resolve a CLI entry from the app under test (or cwd).
+ */
+export declare function resolveBin(opts: ResolveBinOptions): string;
+export type SpawnSpec = {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+};
+export interface CliFrameworkRecipeOptions {
+    id: string;
+    root: string;
+    label: string;
+    share?: SharePolicy;
+    env?: Record<string, string>;
+    hashInputs?: string[];
+    readyPath?: string;
+    readyTimeoutMs?: number;
+    prepare?: (ctx: PrepareCtx & {
+        root: string;
+    }) => Promise<SpawnSpec | void> | SpawnSpec | void;
+    start: (ctx: StartCtx & {
+        root: string;
+    }) => SpawnSpec | Promise<SpawnSpec>;
+    verifyAfterPrepare?: (ctx: PrepareCtx & {
+        root: string;
+    }) => Promise<void>;
+}
+export type FrameworkBaseOptions = {
+    id?: string;
+    root: string;
+    env?: Record<string, string>;
+    hashInputs?: string[];
+    readyPath?: string;
+    readyTimeoutMs?: number;
+};
+export declare function frameworkRoots(root: string): string[];
+/**
+ * Fail early with a clear message when a fixture root (or its package.json) is missing.
+ * Call from prepare/start — not at Recipe factory time (hashInputs may use placeholder roots).
+ */
+export declare function assertAppRoot(root: string, label: string, opts?: {
+    requirePackageJson?: boolean;
+}): string;
+/**
+ * Shared Recipe shell for framework CLI drivers (vite/next/astro/…).
+ */
+export declare function cliFrameworkRecipe(opts: CliFrameworkRecipeOptions): Recipe;
+/** @internal */
+export declare const _cliInternals: {
+    resolveBin: typeof resolveBin;
+    runCommand: typeof runCommand;
+    assertAppRoot: typeof assertAppRoot;
+};
+//# sourceMappingURL=cli-framework.d.ts.map

package/dist/drivers/cli-framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-framework.d.ts","sourceRoot":"","sources":["../../src/drivers/cli-framework.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,UAAU,EACV,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,IAAI,CAAC;AAEZ,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAmC1D;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/F,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5E,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAErD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,MAAM,CAuE1E;AAED,gBAAgB;AAChB,eAAO,MAAM,aAAa;;;;CAA4C,CAAC"}

package/dist/drivers/cli-framework.mjs

@@ -0,0 +1,138 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "pathe";
+import { defineRecipe, loopbackUrl, waitForHttpReady, spawnManaged, runCommand } from "../index.mjs";
+
+export function resolveBin(opts) {
+	const seen = new Set();
+	for (const root of opts.roots) {
+		const key = resolve(root);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const pkgPath = join(key, "package.json");
+		if (!existsSync(pkgPath)) continue;
+		let req;
+		try {
+			req = createRequire(pkgPath);
+		} catch {
+			continue;
+		}
+		for (const id of opts.directIds ?? []) {
+			try {
+				return req.resolve(id);
+			} catch {}
+		}
+		for (const pkgId of opts.packageJsonIds ?? []) {
+			try {
+				const pkgJson = req.resolve(pkgId);
+				const pkgRoot = dirname(pkgJson);
+				for (const rel of opts.binRelative ?? []) {
+					const bin = join(pkgRoot, rel);
+					if (existsSync(bin)) return bin;
+				}
+			} catch {}
+		}
+	}
+	throw new Error(`[untestutils/${opts.label}] cannot resolve CLI from ${opts.roots.join(", ")}`);
+}
+export function frameworkRoots(root) {
+	return [root, process.cwd()];
+}
+
+export function assertAppRoot(root, label, opts = {}) {
+	const resolved = resolve(root);
+	if (!existsSync(resolved)) {
+		throw new Error(`[untestutils/${label}] root not found: ${resolved}`);
+	}
+	if (opts.requirePackageJson !== false) {
+		const pkg = join(resolved, "package.json");
+		if (!existsSync(pkg)) {
+			throw new Error(`[untestutils/${label}] package.json not found in root: ${resolved}`);
+		}
+	}
+	return resolved;
+}
+
+export function cliFrameworkRecipe(opts) {
+	const root = resolve(opts.root);
+	const ensureRoot = () => assertAppRoot(root, opts.label);
+	const recipe = defineRecipe({
+		id: opts.id,
+		share: opts.share ?? (opts.prepare ? "always" : "never"),
+		hashInputs: async () => {
+			const inputs = [...opts.hashInputs ?? [root]];
+			if (opts.env && Object.keys(opts.env).length) {
+				inputs.push(`env:${JSON.stringify(opts.env)}`);
+			}
+			return inputs;
+		},
+		ready: async () => {},
+		prepare: opts.prepare ? async (ctx) => {
+			ensureRoot();
+			const enriched = {
+				...ctx,
+				root
+			};
+			const spec = await opts.prepare(enriched);
+			if (spec) {
+				const result = await runCommand(spec.command, spec.args, {
+					cwd: spec.cwd ?? root,
+					env: {
+						...process.env,
+						...opts.env,
+						...spec.env,
+						OUT_DIR: ctx.outDir
+					},
+					timeoutMs: opts.readyTimeoutMs ?? 3e5
+				});
+				if (result.exitCode !== 0) {
+					throw new Error(`[untestutils/${opts.label}] prepare failed (${result.exitCode}):\n${result.stderr.slice(-2e3)}\n${result.stdout.slice(-1e3)}`);
+				}
+			}
+			if (opts.verifyAfterPrepare) await opts.verifyAfterPrepare(enriched);
+		} : undefined,
+		start: async (ctx) => {
+			ensureRoot();
+			const spec = await opts.start({
+				...ctx,
+				root
+			});
+			const managed = spawnManaged(spec.command, spec.args, {
+				cwd: spec.cwd ?? root,
+				env: {
+					...process.env,
+					...opts.env,
+					...spec.env,
+					PORT: String(ctx.port),
+					HOST: ctx.host
+				},
+				captureLogs: true
+			});
+			const url = loopbackUrl(ctx.port, "/", ctx.host);
+			try {
+				await waitForHttpReady(url, {
+					path: opts.readyPath ?? "/",
+					timeoutMs: opts.readyTimeoutMs ?? 12e4
+				});
+			} catch (e) {
+				await managed.stop();
+				throw new Error(`[untestutils/${opts.label}] ready failed:\n${e}\n--- logs ---\n${managed.logs().slice(-4e3)}`);
+			}
+			return {
+				kind: "url+dir",
+				url,
+				dir: ctx.outDir,
+				stop: managed.stop,
+				pid: managed.pid
+			};
+		}
+	});
+	recipe.root = root;
+	return recipe;
+}
+
+export const _cliInternals = {
+	resolveBin,
+	runCommand,
+	assertAppRoot
+};

package/dist/drivers/command.d.mts

@@ -0,0 +1,15 @@
+import { type Recipe } from "../index.mjs";
+export interface CommandOptions {
+	id: string;
+	cwd?: string;
+	prepare?: string;
+	/** Shell command; `$PORT`, `$HOST`, and `$OUT_DIR` are substituted */
+	start?: string;
+	readyPath?: string;
+	readyTimeoutMs?: number;
+	hashInputs?: string[];
+	share?: Recipe["share"];
+	env?: Record<string, string>;
+}
+export declare function command(opts: CommandOptions): Recipe;
+export default command;

package/dist/drivers/command.d.ts

@@ -0,0 +1,16 @@
+import { type Recipe } from '..';
+export interface CommandOptions {
+    id: string;
+    cwd?: string;
+    prepare?: string;
+    /** Shell command; `$PORT`, `$HOST`, and `$OUT_DIR` are substituted */
+    start?: string;
+    readyPath?: string;
+    readyTimeoutMs?: number;
+    hashInputs?: string[];
+    share?: Recipe['share'];
+    env?: Record<string, string>;
+}
+export declare function command(opts: CommandOptions): Recipe;
+export default command;
+//# sourceMappingURL=command.d.ts.map

package/dist/drivers/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/drivers/command.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,IAAI,CAAC;AAEZ,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA6DpD;AAED,eAAe,OAAO,CAAC"}

package/dist/drivers/command.mjs

@@ -0,0 +1,70 @@
+import { resolve } from "pathe";
+import { defineRecipe, loopbackUrl, waitForHttpReady, spawnManaged } from "../index.mjs";
+export function command(opts) {
+	const cwd = opts.cwd ? resolve(opts.cwd) : undefined;
+	const recipe = defineRecipe({
+		id: opts.id,
+		share: opts.share ?? (opts.start ? "always" : "prepare-only"),
+		hashInputs: async () => {
+			if (opts.hashInputs?.length) return opts.hashInputs.map((p) => resolve(cwd ?? process.cwd(), p));
+			return cwd ? [cwd] : [];
+		},
+		ready: opts.start ? async () => {} : undefined,
+		prepare: opts.prepare ? async ({ run, outDir }) => {
+			const result = await run.command(opts.prepare, {
+				cwd,
+				env: {
+					...process.env,
+					...opts.env,
+					OUT_DIR: outDir
+				}
+			});
+			if (result.exitCode !== 0) {
+				throw new Error(`[untestutils/command] prepare failed (${result.exitCode}):\n${result.stderr.slice(-2e3)}`);
+			}
+		} : undefined,
+		start: async ({ port, host, outDir }) => {
+			if (!opts.start) {
+				return {
+					kind: "dir",
+					dir: outDir
+				};
+			}
+			const rendered = opts.start.replaceAll("$PORT", String(port)).replaceAll("$HOST", host).replaceAll("$OUT_DIR", outDir);
+			const parts = rendered.trim().split(/\s+/);
+			const cmd = parts[0];
+			const args = parts.slice(1);
+			const managed = spawnManaged(cmd, args, {
+				cwd,
+				env: {
+					...process.env,
+					...opts.env,
+					PORT: String(port),
+					HOST: host,
+					OUT_DIR: outDir
+				},
+				captureLogs: true
+			});
+			const url = loopbackUrl(port, "/", host);
+			try {
+				await waitForHttpReady(url, {
+					path: opts.readyPath ?? "/",
+					timeoutMs: opts.readyTimeoutMs
+				});
+			} catch (e) {
+				await managed.stop();
+				throw new Error(`${e}\n--- logs ---\n${managed.logs().slice(-4e3)}`);
+			}
+			return {
+				kind: "url+dir",
+				url,
+				dir: outDir,
+				stop: managed.stop,
+				pid: managed.pid
+			};
+		}
+	});
+	if (cwd) recipe.root = cwd;
+	return recipe;
+}
+export default command;

package/dist/drivers/define-driver.d.mts

@@ -0,0 +1,4 @@
+import type { Recipe } from "../index.mjs";
+/** Framework/app adapter → Recipe. Core never imports frameworks. */
+export type Driver<Opts = unknown> = (opts: Opts) => Recipe;
+export declare function defineDriver<Opts>(impl: Driver<Opts>): Driver<Opts>;

package/dist/drivers/define-driver.d.ts

@@ -0,0 +1,5 @@
+import type { Recipe } from '..';
+/** Framework/app adapter → Recipe. Core never imports frameworks. */
+export type Driver<Opts = unknown> = (opts: Opts) => Recipe;
+export declare function defineDriver<Opts>(impl: Driver<Opts>): Driver<Opts>;
+//# sourceMappingURL=define-driver.d.ts.map

package/dist/drivers/define-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-driver.d.ts","sourceRoot":"","sources":["../../src/drivers/define-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAEjC,qEAAqE;AACrE,MAAM,MAAM,MAAM,CAAC,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;AAE5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAEnE"}

package/dist/drivers/define-driver.mjs

@@ -0,0 +1,3 @@
+export function defineDriver(impl) {
+	return impl;
+}

package/dist/drivers/host.d.mts

@@ -0,0 +1,18 @@
+import { type Recipe } from "../index.mjs";
+import { type Driver } from "./define-driver.mjs";
+export interface HostOptions {
+	id: string;
+	/** Absolute or env-resolved URL of an already-deployed app (staging/prod). */
+	url: string;
+	readyPath?: string;
+	readyTimeoutMs?: number;
+	/** Skip HTTP ready check (default false). */
+	skipReady?: boolean;
+	share?: Recipe["share"];
+}
+/**
+* Attach to an already-running remote/staging/prod URL — no local prepare/start.
+* Use for post-deploy smoke with Playwright/Vitest.
+*/
+export declare const host: Driver<HostOptions>;
+export default host;

package/dist/drivers/host.d.ts

@@ -0,0 +1,19 @@
+import { type Recipe } from '..';
+import { type Driver } from './define-driver';
+export interface HostOptions {
+    id: string;
+    /** Absolute or env-resolved URL of an already-deployed app (staging/prod). */
+    url: string;
+    readyPath?: string;
+    readyTimeoutMs?: number;
+    /** Skip HTTP ready check (default false). */
+    skipReady?: boolean;
+    share?: Recipe['share'];
+}
+/**
+ * Attach to an already-running remote/staging/prod URL — no local prepare/start.
+ * Use for post-deploy smoke with Playwright/Vitest.
+ */
+export declare const host: Driver<HostOptions>;
+export default host;
+//# sourceMappingURL=host.d.ts.map

package/dist/drivers/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/drivers/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoD,KAAK,MAAM,EAAE,MAAM,IAAI,CAAC;AACnF,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,WAAW,CA0BnC,CAAC;AAEH,eAAe,IAAI,CAAC"}

package/dist/drivers/host.mjs

@@ -0,0 +1,31 @@
+import { defineRecipe, normalizeBaseUrl, waitForHttpReady } from "../index.mjs";
+import { defineDriver } from "./define-driver.mjs";
+
+export const host = defineDriver((opts) => {
+	if (!opts.url?.trim()) {
+		throw new Error("[untestutils/host] url is required");
+	}
+	const url = normalizeBaseUrl(opts.url);
+	return defineRecipe({
+		id: opts.id,
+		share: opts.share ?? "always",
+		
+		ready: async () => {},
+		start: async () => {
+			if (!opts.skipReady) {
+				await waitForHttpReady(url, {
+					path: opts.readyPath ?? "/",
+					timeoutMs: opts.readyTimeoutMs
+				});
+			}
+			return {
+				kind: "url",
+				url,
+				stop: async () => {
+					
+				}
+			};
+		}
+	});
+});
+export default host;

package/dist/drivers/index.d.mts

@@ -0,0 +1,12 @@
+export type { Driver } from "./define-driver.mjs";
+export { defineDriver } from "./define-driver.mjs";
+export { command } from "./command.mjs";
+export type { CommandOptions } from "./command.mjs";
+export { staticDir } from "./static-dir.mjs";
+export type { StaticDirOptions } from "./static-dir.mjs";
+export { nodeEntry } from "./node-entry.mjs";
+export type { NodeEntryOptions } from "./node-entry.mjs";
+export { host } from "./host.mjs";
+export type { HostOptions } from "./host.mjs";
+export { resolveBin, assertAppRoot, cliFrameworkRecipe, frameworkRoots, _cliInternals } from "./cli-framework.mjs";
+export type { ResolveBinOptions, SpawnSpec, CliFrameworkRecipeOptions, FrameworkBaseOptions } from "./cli-framework.mjs";

package/dist/drivers/index.d.ts

@@ -0,0 +1,13 @@
+export type { Driver } from './define-driver';
+export { defineDriver } from './define-driver';
+export { command } from './command';
+export type { CommandOptions } from './command';
+export { staticDir } from './static-dir';
+export type { StaticDirOptions } from './static-dir';
+export { nodeEntry } from './node-entry';
+export type { NodeEntryOptions } from './node-entry';
+export { host } from './host';
+export type { HostOptions } from './host';
+export { resolveBin, assertAppRoot, cliFrameworkRecipe, frameworkRoots, _cliInternals, } from './cli-framework';
+export type { ResolveBinOptions, SpawnSpec, CliFrameworkRecipeOptions, FrameworkBaseOptions, } from './cli-framework';
+//# sourceMappingURL=index.d.ts.map

package/dist/drivers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}