@untestutils/core 0.5.0

package/dist/target-registry.mjs

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "pathe";
+import { atomicWriteJson, FileLock } from "./lock.mjs";
+import { normalizeBaseUrl } from "./paths.mjs";
+import { debug } from "./debug.mjs";
+export class TargetRegistry {
+	artifactsRoot;
+	constructor(artifactsRoot) {
+		this.artifactsRoot = artifactsRoot;
+	}
+	get filePath() {
+		return join(this.artifactsRoot, "targets.json");
+	}
+	lockPath() {
+		return join(this.artifactsRoot, "locks", "targets.lock");
+	}
+	async withLock(fn) {
+		const lock = new FileLock(this.lockPath(), "targets");
+		await lock.acquire();
+		try {
+			return await fn();
+		} finally {
+			await lock.release();
+		}
+	}
+	async read() {
+		if (!existsSync(this.filePath)) return {};
+		try {
+			return JSON.parse(await readFile(this.filePath, "utf8"));
+		} catch {
+			return {};
+		}
+	}
+	async write(map) {
+		await atomicWriteJson(this.filePath, map);
+		debug("registry", `wrote ${Object.keys(map).length} targets`);
+	}
+	async set(entry) {
+		let previous;
+		await this.withLock(async () => {
+			const map = await this.read();
+			previous = map[entry.id];
+			const normalized = {
+				...entry,
+				url: entry.url ? normalizeBaseUrl(entry.url) : undefined
+			};
+			map[entry.id] = normalized;
+			await this.write(map);
+			this.applyEnv(normalized);
+		});
+		return previous;
+	}
+	async get(id) {
+		const map = await this.read();
+		const fromFile = map[id];
+		const fromEnv = process.env[envKey(id)];
+		if (fromFile) {
+			return {
+				...fromFile,
+				
+				url: fromEnv ? normalizeBaseUrl(fromEnv) : fromFile.url
+			};
+		}
+		if (fromEnv) {
+			return {
+				id,
+				url: normalizeBaseUrl(fromEnv),
+				identity: id
+			};
+		}
+		return undefined;
+	}
+	applyAllToEnv(map) {
+		for (const entry of Object.values(map)) this.applyEnv(entry);
+	}
+	applyEnv(entry) {
+		if (entry.url) process.env[envKey(entry.id)] = entry.url;
+		if (entry.dir) process.env[envDirKey(entry.id)] = entry.dir;
+	}
+	async clear() {
+		await this.withLock(async () => {
+			await atomicWriteJson(this.filePath, {});
+		});
+	}
+	
+	async drain() {
+		return this.withLock(async () => {
+			const map = await this.read();
+			await atomicWriteJson(this.filePath, {});
+			return map;
+		});
+	}
+}
+export function envKey(id) {
+	return `UNTESTUTILS_HOST_${sanitizeId(id)}`;
+}
+export function envDirKey(id) {
+	return `UNTESTUTILS_DIR_${sanitizeId(id)}`;
+}
+function sanitizeId(id) {
+	return id.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase();
+}

package/dist/types.d.mts

@@ -0,0 +1,92 @@
+/**
+* Core recipe types — framework-free.
+*/
+export type RunningKind = "url" | "dir" | "url+dir";
+export interface RunningBase {
+	stop?: () => Promise<void>;
+	/** OS pid of the managed server (for cross-worker teardown via registry). */
+	pid?: number;
+}
+export interface RunningUrl extends RunningBase {
+	kind: "url";
+	url: string;
+}
+export interface RunningDir extends RunningBase {
+	kind: "dir";
+	dir: string;
+}
+export interface RunningBoth extends RunningBase {
+	kind: "url+dir";
+	url: string;
+	dir: string;
+}
+export type Running = RunningUrl | RunningDir | RunningBoth;
+export type SharePolicy = "always" | "never" | "prepare-only";
+export interface HashCtx {
+	root?: string;
+	outDir: string;
+	artifactsRoot: string;
+}
+export interface PrepareCtx {
+	root?: string;
+	outDir: string;
+	artifactsRoot: string;
+	env: NodeJS.ProcessEnv;
+	run: RunHelper;
+}
+export interface StartCtx {
+	root?: string;
+	outDir: string;
+	artifactsRoot: string;
+	port: number;
+	host: string;
+	env: NodeJS.ProcessEnv;
+	run: RunHelper;
+}
+export interface RunResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+}
+export interface DetachedProcess {
+	pid?: number;
+	stop: () => Promise<void>;
+	logs: () => string;
+}
+export interface RunHelper {
+	(strings: TemplateStringsArray, ...values: unknown[]): Promise<RunResult>;
+	detached: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<DetachedProcess>;
+	command: (cmd: string, opts?: {
+		cwd?: string;
+		env?: NodeJS.ProcessEnv;
+	}) => Promise<RunResult>;
+}
+export interface Recipe {
+	id?: string;
+	hashInputs?: (ctx: HashCtx) => string[] | Promise<string[]>;
+	prepare?: (ctx: PrepareCtx) => Promise<void>;
+	start: (ctx: StartCtx) => Promise<Running>;
+	ready?: (running: Running) => Promise<void>;
+	verifyArtifact?: (outDir: string) => Promise<void>;
+	share?: SharePolicy;
+}
+export type RecipeFactory<Opts = unknown> = (opts: Opts) => Recipe;
+export interface RecipeRegistry {
+	readonly [id: string]: Recipe;
+}
+export interface HarnessHandle {
+	id: string;
+	url?: string;
+	dir?: string;
+	$fetch: typeof import("ofetch").$fetch;
+	files: {
+		read: (rel: string) => Promise<string>;
+		exists: (rel: string) => Promise<boolean>;
+		list: (rel?: string) => Promise<string[]>;
+	};
+	dispose?: () => Promise<void>;
+}
+export interface UseHarnessOptions {
+	browser?: boolean;
+}
+export declare const SCHEMA_VERSION: 1;

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Core recipe types — framework-free.
+ */
+export type RunningKind = 'url' | 'dir' | 'url+dir';
+export interface RunningBase {
+    stop?: () => Promise<void>;
+    /** OS pid of the managed server (for cross-worker teardown via registry). */
+    pid?: number;
+}
+export interface RunningUrl extends RunningBase {
+    kind: 'url';
+    url: string;
+}
+export interface RunningDir extends RunningBase {
+    kind: 'dir';
+    dir: string;
+}
+export interface RunningBoth extends RunningBase {
+    kind: 'url+dir';
+    url: string;
+    dir: string;
+}
+export type Running = RunningUrl | RunningDir | RunningBoth;
+export type SharePolicy = 'always' | 'never' | 'prepare-only';
+export interface HashCtx {
+    root?: string;
+    outDir: string;
+    artifactsRoot: string;
+}
+export interface PrepareCtx {
+    root?: string;
+    outDir: string;
+    artifactsRoot: string;
+    env: NodeJS.ProcessEnv;
+    run: RunHelper;
+}
+export interface StartCtx {
+    root?: string;
+    outDir: string;
+    artifactsRoot: string;
+    port: number;
+    host: string;
+    env: NodeJS.ProcessEnv;
+    run: RunHelper;
+}
+export interface RunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface DetachedProcess {
+    pid?: number;
+    stop: () => Promise<void>;
+    logs: () => string;
+}
+export interface RunHelper {
+    (strings: TemplateStringsArray, ...values: unknown[]): Promise<RunResult>;
+    detached: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<DetachedProcess>;
+    command: (cmd: string, opts?: {
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<RunResult>;
+}
+export interface Recipe {
+    id?: string;
+    hashInputs?: (ctx: HashCtx) => string[] | Promise<string[]>;
+    prepare?: (ctx: PrepareCtx) => Promise<void>;
+    start: (ctx: StartCtx) => Promise<Running>;
+    ready?: (running: Running) => Promise<void>;
+    verifyArtifact?: (outDir: string) => Promise<void>;
+    share?: SharePolicy;
+}
+export type RecipeFactory<Opts = unknown> = (opts: Opts) => Recipe;
+export interface RecipeRegistry {
+    readonly [id: string]: Recipe;
+}
+export interface HarnessHandle {
+    id: string;
+    url?: string;
+    dir?: string;
+    $fetch: typeof import('ofetch').$fetch;
+    files: {
+        read: (rel: string) => Promise<string>;
+        exists: (rel: string) => Promise<boolean>;
+        list: (rel?: string) => Promise<string[]>;
+    };
+    dispose?: () => Promise<void>;
+}
+export interface UseHarnessOptions {
+    browser?: boolean;
+}
+export declare const SCHEMA_VERSION: 1;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.mjs

@@ -0,0 +1 @@
+export const SCHEMA_VERSION = 1;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@untestutils/core",
+  "version": "0.5.0",
+  "description": "Recipe harness core — locks, registry, orchestrator, drivers",
+  "license": "MIT",
+  "homepage": "https://s00d.github.io/untestutils/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s00d/untestutils.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./drivers": {
+      "types": "./dist/drivers/index.d.ts",
+      "import": "./dist/drivers/index.mjs",
+      "default": "./dist/drivers/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "consola": "^3.4.2",
+    "ofetch": "^1.5.1",
+    "pathe": "^2.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "obuild": "^0.4.40",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "obuild && tsc -p tsconfig.build.json",
+    "publint": "publint --strict"
+  }
+}