@gfdelarue/testkit 0.3.0

package/dist/engines/definitions.d.ts

@@ -0,0 +1,15 @@
+import type { RunnerProfileDescriptor } from "./api/index.js";
+import type { EngineId } from "../domain/identifiers.js";
+import type { InternalEngineRegistrationById } from "./installation-catalog.js";
+export type EndpointReadinessOwner = "adapter" | "orchestrator-http";
+export interface BuiltInRunnerProfile<Id extends EngineId = EngineId> extends RunnerProfileDescriptor<Id> {
+    readonly endpointReadinessOwner: EndpointReadinessOwner;
+}
+type BuiltInDefinitions = {
+    readonly [Id in EngineId]: InternalEngineRegistrationById[Id] & {
+        readonly profiles: readonly BuiltInRunnerProfile<Id>[];
+    };
+};
+export declare const BUILT_IN_ENGINE_DEFINITIONS: BuiltInDefinitions;
+export declare const BUILT_IN_RUNNER_PROFILES: readonly BuiltInRunnerProfile[];
+export {};

package/dist/engines/definitions.js

@@ -0,0 +1 @@
+import{resolveK6Installation as i}from"./installations/k6.js";import{resolveNodeVitestInstallation as a}from"./installations/node-vitest.js";import{resolvePlaywrightInstallation as n}from"./installations/playwright.js";export const BUILT_IN_ENGINE_DEFINITIONS=Object.freeze({k6:Object.freeze({id:"k6",profiles:Object.freeze([t({capabilities:{applicationRuntime:"required",databaseRuntime:"optional",endpointAccess:"published-http",executionHost:"orchestrator",runtimeIsolation:"orchestrated",taskBatching:"isolated"},engineId:"k6",id:"k6-http",supportedTestTypes:["int","e2e","load"],endpointReadinessOwner:"orchestrator-http"}),t({capabilities:{applicationRuntime:"none",databaseRuntime:"required",endpointAccess:"none",executionHost:"orchestrator",runtimeIsolation:"orchestrated",taskBatching:"isolated"},engineId:"k6",id:"k6-dal",supportedTestTypes:["dal"],endpointReadinessOwner:"adapter"})]),resolveInstallation:i,async loadExecutor(){return(await import("./k6/adapter/index.js")).executeK6Engine}}),"node-vitest":Object.freeze({id:"node-vitest",profiles:Object.freeze([t({capabilities:{applicationRuntime:"required",databaseRuntime:"optional",endpointAccess:"published-http",executionHost:"orchestrator",runtimeIsolation:"orchestrated",taskBatching:"isolated"},engineId:"node-vitest",id:"node-vitest-data",supportedTestTypes:["data"],endpointReadinessOwner:"adapter"}),t({capabilities:{applicationRuntime:"required",databaseRuntime:"optional",endpointAccess:"published-http",executionHost:"orchestrator",runtimeIsolation:"orchestrated",taskBatching:"isolated"},engineId:"node-vitest",id:"node-vitest-contract",supportedTestTypes:["contract"],endpointReadinessOwner:"adapter"})]),resolveInstallation:a,async loadExecutor(){return(await import("./node-vitest/adapter/index.js")).executeNodeVitestEngine}}),playwright:Object.freeze({id:"playwright",profiles:Object.freeze([t({capabilities:{applicationRuntime:"required",databaseRuntime:"optional",endpointAccess:"published-http",executionHost:"orchestrator",runtimeIsolation:"orchestrated",taskBatching:"compatible"},engineId:"playwright",id:"playwright-ui",supportedTestTypes:["ui"],endpointReadinessOwner:"orchestrator-http"})]),resolveInstallation:n,async loadExecutor(){return(await import("./playwright/adapter/index.js")).executePlaywrightEngine}})}),BUILT_IN_RUNNER_PROFILES=Object.freeze(Object.values(BUILT_IN_ENGINE_DEFINITIONS).flatMap(e=>e.profiles));function t(e){return Object.freeze(e.capabilities),Object.freeze(e.supportedTestTypes),Object.freeze(e)}

package/dist/engines/factory.d.ts

@@ -0,0 +1,6 @@
+import { type InternalEngineInstallationCatalog } from "./installation-catalog.js";
+import { EngineManager } from "./manager.js";
+export interface EngineManagerFactoryOptions {
+    readonly catalog?: InternalEngineInstallationCatalog;
+}
+export declare function createEngineManager(productDirectory: string, options?: Readonly<EngineManagerFactoryOptions>): EngineManager;

package/dist/engines/factory.js

@@ -0,0 +1 @@
+import e from"node:fs";import i from"node:path";import{BUILT_IN_ENGINE_INSTALLATION_CATALOG as c}from"./installation-catalog.js";import{EngineManager as s}from"./manager.js";export function createEngineManager(t,r={}){return new s({catalog:r.catalog??c,productRoot:a(t)})}function a(t){if(!i.isAbsolute(t))throw new Error("Testkit product directory must be absolute");const r=i.resolve(t);let o;try{o=e.statSync(r)}catch(n){throw new Error(`Testkit product directory does not exist: ${r}`,{cause:n})}if(!o.isDirectory())throw new Error(`Testkit product directory is not a directory: ${r}`);return e.realpathSync.native(r)}

package/dist/engines/installation-catalog.d.ts

@@ -0,0 +1,27 @@
+import { type EngineExecutionRequest, type EngineExecutionResult, type EngineInvocationScope } from "./api/index.js";
+import { type EngineId } from "../domain/identifiers.js";
+import type { K6Installation } from "./installations/k6.js";
+import type { NodeVitestInstallation } from "./installations/node-vitest.js";
+import type { PlaywrightInstallation } from "./installations/playwright.js";
+import type { EngineResolutionContext } from "./installations/types.js";
+export interface EngineInstallationById {
+    readonly k6: K6Installation;
+    readonly "node-vitest": NodeVitestInstallation;
+    readonly playwright: PlaywrightInstallation;
+}
+export type EngineInstallationFor<Id extends EngineId> = EngineInstallationById[Id];
+export type EngineExecutorFor<Id extends EngineId> = (request: Readonly<EngineExecutionRequest<Id>>, installation: Readonly<EngineInstallationFor<Id>>, scope: EngineInvocationScope) => Promise<EngineExecutionResult>;
+export interface InternalEngineRegistration<Id extends EngineId> {
+    readonly id: Id;
+    loadExecutor(): Promise<EngineExecutorFor<Id>>;
+    resolveInstallation(context: Readonly<EngineResolutionContext>): Promise<EngineInstallationFor<Id>>;
+}
+export type InternalEngineRegistrationById = {
+    readonly [Id in EngineId]: InternalEngineRegistration<Id>;
+};
+export interface InternalEngineInstallationCatalog {
+    readonly registrations: InternalEngineRegistrationById;
+    resolve<Id extends EngineId>(engineId: Id): InternalEngineRegistration<Id>;
+}
+export declare const BUILT_IN_ENGINE_INSTALLATION_CATALOG: InternalEngineInstallationCatalog;
+export declare function createInternalEngineInstallationCatalog(registrations: Readonly<InternalEngineRegistrationById>): InternalEngineInstallationCatalog;

package/dist/engines/installation-catalog.js

@@ -0,0 +1 @@
+import"./api/index.js";import"../domain/identifiers.js";import{BUILT_IN_ENGINE_DEFINITIONS as o}from"./definitions.js";export const BUILT_IN_ENGINE_INSTALLATION_CATALOG=createInternalEngineInstallationCatalog(o);export function createInternalEngineInstallationCatalog(e){const t=Object.freeze({k6:Object.freeze(e.k6),"node-vitest":Object.freeze(e["node-vitest"]),playwright:Object.freeze(e.playwright)});return Object.freeze({registrations:t,resolve(r){return t[r]}})}

package/dist/engines/installations/k6.d.ts

@@ -0,0 +1,98 @@
+import { type PlatformTarget } from "../../process/host/platform.js";
+import { runManagedHostProcess } from "../../process/index.js";
+import { RootPackageResolver, type ResolvedPackage } from "./package-resolution.js";
+import type { EngineResolutionContext } from "./types.js";
+export declare const EXPECTED_K6_VERSION = "1.7.1";
+export declare const K6_VERSION_PROBE_TIMEOUT_MS = 30000;
+export declare const K6_TARGET_PACKAGE_REQUIREMENTS: readonly [Readonly<{
+    executablePath: "bin/k6";
+    packageName: "@gfdelarue/testkit-engine-k6-darwin-arm64";
+    publicEntrypoint: "@gfdelarue/testkit-engine-k6-darwin-arm64/binary";
+    target: Readonly<{
+        arch: "arm64";
+        platform: "darwin";
+    }>;
+}>, Readonly<{
+    executablePath: "bin/k6";
+    packageName: "@gfdelarue/testkit-engine-k6-darwin-x64";
+    publicEntrypoint: "@gfdelarue/testkit-engine-k6-darwin-x64/binary";
+    target: Readonly<{
+        arch: "x64";
+        platform: "darwin";
+    }>;
+}>, Readonly<{
+    executablePath: "bin/k6";
+    packageName: "@gfdelarue/testkit-engine-k6-linux-arm64";
+    publicEntrypoint: "@gfdelarue/testkit-engine-k6-linux-arm64/binary";
+    target: Readonly<{
+        arch: "arm64";
+        platform: "linux";
+    }>;
+}>, Readonly<{
+    executablePath: "bin/k6";
+    packageName: "@gfdelarue/testkit-engine-k6-linux-x64";
+    publicEntrypoint: "@gfdelarue/testkit-engine-k6-linux-x64/binary";
+    target: Readonly<{
+        arch: "x64";
+        platform: "linux";
+    }>;
+}>, Readonly<{
+    executablePath: "bin/k6.exe";
+    packageName: "@gfdelarue/testkit-engine-k6-win32-x64";
+    publicEntrypoint: "@gfdelarue/testkit-engine-k6-win32-x64/binary";
+    target: Readonly<{
+        arch: "x64";
+        platform: "win32";
+    }>;
+}>];
+export type K6TargetPackageName = (typeof K6_TARGET_PACKAGE_REQUIREMENTS)[number]["packageName"];
+export interface K6TargetPackageInstallation {
+    readonly name: K6TargetPackageName;
+    readonly root: string;
+    readonly target: PlatformTarget;
+    readonly version: string;
+}
+export interface K6Installation {
+    readonly authoringEntrypoints: {
+        readonly authoring: string;
+        readonly config: string;
+        readonly root: string;
+        readonly rootPackageJson: string;
+    };
+    readonly engineId: "k6";
+    readonly engineVersion: string;
+    readonly executable: string;
+    readonly target: PlatformTarget;
+    readonly targetPackage: K6TargetPackageInstallation;
+}
+type K6VersionProbeResult = Awaited<ReturnType<typeof runManagedHostProcess>>;
+export declare class K6OptionalPackageMissingError extends Error {
+    readonly code = "TESTKIT_K6_OPTIONAL_PACKAGE_MISSING";
+    readonly packageName: K6TargetPackageName;
+    readonly target: PlatformTarget;
+    readonly version: string;
+    constructor(requirement: Readonly<K6TargetPackageRequirement>, version: string, options: ErrorOptions);
+}
+export declare class K6EngineVersionMismatchError extends Error {
+    readonly code = "TESTKIT_K6_ENGINE_VERSION_MISMATCH";
+    readonly expectedVersion: string;
+    readonly observedVersion: string;
+    readonly packageName: K6TargetPackageName;
+    readonly packageVersion: string;
+    constructor(selected: Readonly<ResolvedPackage>, requirement: Readonly<K6TargetPackageRequirement>, observedVersion: string);
+}
+export declare class K6VersionProbeError extends Error {
+    readonly code = "TESTKIT_K6_VERSION_PROBE_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+interface K6TargetPackageRequirement {
+    readonly executablePath: "bin/k6" | "bin/k6.exe";
+    readonly packageName: K6TargetPackageNameLiteral;
+    readonly publicEntrypoint: `${K6TargetPackageNameLiteral}/binary`;
+    readonly target: PlatformTarget;
+}
+type K6TargetPackageNameLiteral = "@gfdelarue/testkit-engine-k6-darwin-arm64" | "@gfdelarue/testkit-engine-k6-darwin-x64" | "@gfdelarue/testkit-engine-k6-linux-arm64" | "@gfdelarue/testkit-engine-k6-linux-x64" | "@gfdelarue/testkit-engine-k6-win32-x64";
+export declare function resolveK6Installation(context: Readonly<EngineResolutionContext>): Promise<K6Installation>;
+export declare function requireK6TargetPackageRequirement(target?: Readonly<PlatformTarget>): (typeof K6_TARGET_PACKAGE_REQUIREMENTS)[number];
+export declare function requireK6VersionProbeResult(selected: Readonly<ResolvedPackage>, target: Readonly<PlatformTarget>, signal: AbortSignal, result: Readonly<K6VersionProbeResult>, resolver: RootPackageResolver): string;
+export {};

package/dist/engines/installations/k6.js

@@ -0,0 +1 @@
+import p from"node:fs";import l from"node:path";import{currentPlatformTarget as h,platformTargetKey as b,UnsupportedPlatformTargetError as x}from"../../process/host/platform.js";import{isPathWithin as k}from"../../process/files/paths.js";import{managedHostProcessInfrastructureError as E,runManagedHostProcess as w}from"../../process/index.js";import{MissingDirectPackageError as y,RootPackageResolver as P}from"./package-resolution.js";export const EXPECTED_K6_VERSION="1.7.1",K6_VERSION_PROBE_TIMEOUT_MS=3e4,K6_TARGET_PACKAGE_REQUIREMENTS=Object.freeze([Object.freeze({executablePath:"bin/k6",packageName:"@gfdelarue/testkit-engine-k6-darwin-arm64",publicEntrypoint:"@gfdelarue/testkit-engine-k6-darwin-arm64/binary",target:Object.freeze({arch:"arm64",platform:"darwin"})}),Object.freeze({executablePath:"bin/k6",packageName:"@gfdelarue/testkit-engine-k6-darwin-x64",publicEntrypoint:"@gfdelarue/testkit-engine-k6-darwin-x64/binary",target:Object.freeze({arch:"x64",platform:"darwin"})}),Object.freeze({executablePath:"bin/k6",packageName:"@gfdelarue/testkit-engine-k6-linux-arm64",publicEntrypoint:"@gfdelarue/testkit-engine-k6-linux-arm64/binary",target:Object.freeze({arch:"arm64",platform:"linux"})}),Object.freeze({executablePath:"bin/k6",packageName:"@gfdelarue/testkit-engine-k6-linux-x64",publicEntrypoint:"@gfdelarue/testkit-engine-k6-linux-x64/binary",target:Object.freeze({arch:"x64",platform:"linux"})}),Object.freeze({executablePath:"bin/k6.exe",packageName:"@gfdelarue/testkit-engine-k6-win32-x64",publicEntrypoint:"@gfdelarue/testkit-engine-k6-win32-x64/binary",target:Object.freeze({arch:"x64",platform:"win32"})})]);export class K6OptionalPackageMissingError extends Error{code="TESTKIT_K6_OPTIONAL_PACKAGE_MISSING";packageName;target;version;constructor(t,a,r){const n=Object.freeze({...t.target});super(`Testkit k6 on ${n.platform}/${n.arch} requires optional package ${t.packageName}@${a}, but it is not installed. Run a clean npm install from the consumer lockfile without omitting optional dependencies. Testkit does not use PATH or a system k6 fallback.`,r),this.name="K6OptionalPackageMissingError",this.packageName=t.packageName,this.target=n,this.version=a}}export class K6EngineVersionMismatchError extends Error{code="TESTKIT_K6_ENGINE_VERSION_MISMATCH";expectedVersion;observedVersion;packageName;packageVersion;constructor(t,a,r){super(`Testkit requires k6 v${EXPECTED_K6_VERSION}, but ${a.packageName}@${t.version} reported k6 v${r} from its version probe. Install the ${a.packageName} version that ships k6 v${EXPECTED_K6_VERSION}.`),this.name="K6EngineVersionMismatchError",this.expectedVersion=EXPECTED_K6_VERSION,this.observedVersion=r,this.packageName=a.packageName,this.packageVersion=t.version}}export class K6VersionProbeError extends Error{code="TESTKIT_K6_VERSION_PROBE_FAILED";constructor(t,a){super(t,a),this.name="K6VersionProbeError"}}const v=/^k6(?:\.exe)? v((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?)\s+\([^\r\n)]*\b(darwin|linux|windows)\/(amd64|arm64)\)(?:\s|$)/u;export async function resolveK6Installation(e){e.signal.throwIfAborted();const t=new P,a=requireK6TargetPackageRequirement();let r;try{r=t.resolveRequireFromRoot({dependencyGroup:"optionalDependencies",packageName:a.packageName,publicEntrypoint:a.publicEntrypoint})}catch(s){throw s instanceof y?new K6OptionalPackageMissingError(a,s.version,{cause:s}):s}const n=O(r,a,t),i=T(t),o=await $(r,n,a.target,e,t),c=Object.freeze({...a.target});return Object.freeze({authoringEntrypoints:i,engineId:"k6",engineVersion:o,executable:n,target:c,targetPackage:Object.freeze({name:a.packageName,root:r.root,target:c,version:r.version})})}function T(e){return Object.freeze({authoring:e.resolveRootPublicEntrypoint("@gfdelarue/testkit/k6"),config:e.resolveRootPublicEntrypoint("@gfdelarue/testkit/config"),root:e.resolveRootPublicEntrypoint("@gfdelarue/testkit"),rootPackageJson:e.packageJsonPath})}export function requireK6TargetPackageRequirement(e=h()){const t=b(e),a=K6_TARGET_PACKAGE_REQUIREMENTS.find(r=>b(r.target)===t);if(a===void 0)throw new x(e.platform,e.arch,"managed k6");return a}function O(e,t,a){try{const r=_(e.manifestPath);if(r.name!==t.packageName||r.version!==e.version)throw new TypeError(`manifest must remain exactly ${t.packageName}@${e.version}`);d(r.os,t.target.platform,"os"),d(r.cpu,t.target.arch,"cpu");const n=l.resolve(e.root,t.executablePath);if(!k(e.root,n))throw new TypeError(`expected executable ${t.executablePath} escapes its package root`);const i=p.lstatSync(n);if(!i.isFile()||i.isSymbolicLink())throw new TypeError(`expected executable ${t.executablePath} must be a regular non-symlink file`);const o=p.realpathSync(n);if(!k(e.root,o))throw new TypeError(`expected executable ${t.executablePath} resolves outside its package root`);if(o!==e.entrypoint)throw new TypeError(`public binary export must resolve exactly to ${t.executablePath}`);if(l.basename(o)!==l.basename(t.executablePath))throw new TypeError(`public binary export must use filename ${l.basename(t.executablePath)}`);if(t.target.platform!=="win32"&&(i.mode&73)===0)throw new TypeError(`expected executable ${t.executablePath} must have a POSIX executable permission bit`);return t.target.platform!=="win32"&&p.accessSync(o,p.constants.X_OK),o}catch(r){throw a.brokenInstallation(e,`its ${t.target.platform}/${t.target.arch} k6 binary contract is invalid: ${R(r)}`,r)}}async function $(e,t,a,r,n){let i;try{i=await w({args:["version"],cwd:r.productRoot,displayLabel:"Testkit k6 version probe",env:process.env,executable:t,signal:r.signal,timeoutMs:K6_VERSION_PROBE_TIMEOUT_MS})}catch(o){throw m(r.signal,o),n.brokenInstallation(e,"its mandatory k6 version probe could not run",o)}return requireK6VersionProbeResult(e,a,r.signal,i,n)}export function requireK6VersionProbeResult(e,t,a,r,n){const i=E("Testkit k6 version probe",r);m(a,S(r)?i:null);const o=K(r)??i??I(r);if(o!==null)throw n.brokenInstallation(e,"its mandatory k6 version probe failed",o);const c=r.stdout.trim().split(/\r?\n/u,1)[0]??"",s=v.exec(c);if(s===null)throw n.brokenInstallation(e,"its mandatory k6 version probe returned an invalid version",new K6VersionProbeError(`Expected bounded output beginning with "k6 v<version>"; received ${JSON.stringify(c)}`));const u=`${s[2]}/${s[3]}`,f=N(t);if(u!==f)throw n.brokenInstallation(e,`its mandatory k6 version probe reported incompatible target ${u}; expected ${f}`,new K6VersionProbeError(`k6 version target ${u} does not match ${f}`));const g=s[1];if(g!==EXPECTED_K6_VERSION)throw new K6EngineVersionMismatchError(e,requireK6TargetPackageRequirement(t),g);return g}function N(e){const t=e.platform==="win32"?"windows":e.platform,a=e.arch==="x64"?"amd64":e.arch;return`${t}/${a}`}function I(e){return e.exitCode!==0?new K6VersionProbeError(e.exitCode===null?`k6 version terminated by ${e.exitSignal??"an unknown signal"}`:`k6 version exited with code ${e.exitCode.toString()}`):null}function S(e){return e.terminationError!==null||e.error!==null||e.timedOut||e.outputLimitExceeded}function K(e){return e.error!==null&&e.terminationError===null&&!e.timedOut&&!e.cancelled&&!e.outputLimitExceeded?e.error:null}function m(e,t){if(e.aborted)throw t==null&&e.throwIfAborted(),t===e.reason?t:new AggregateError([e.reason,t],"k6 version probe was cancelled and process cleanup also failed",{cause:e.reason})}function d(e,t,a){if(!Array.isArray(e)||e.length!==1||e[0]!==t)throw new TypeError(`manifest ${a} must be exactly [${JSON.stringify(t)}]; received ${JSON.stringify(e)}`)}function _(e){const t=JSON.parse(p.readFileSync(e,"utf8"));if(typeof t!="object"||t===null||Array.isArray(t))throw new TypeError("package manifest must contain a JSON object");return t}function R(e){return e instanceof Error?e.message:String(e)}

package/dist/engines/installations/node-vitest.d.ts

@@ -0,0 +1,47 @@
+import { RootPackageResolver, type ResolvedPackageEntrypoint } from "./package-resolution.js";
+import type { DirectPackageInstallation, EngineResolutionContext } from "./types.js";
+export declare const NODE_VITEST_PACKAGE_REQUIREMENTS: readonly [Readonly<{
+    authoringResolution: "package-exports";
+    packageName: "vitest";
+    publicEntrypoints: readonly ["vitest"];
+}>, Readonly<{
+    authoringResolution: "package-exports";
+    packageName: "vite";
+    publicEntrypoints: readonly ["vite"];
+}>, Readonly<{
+    authoringResolution: "exact-entrypoint";
+    packageName: "typescript";
+    publicEntrypoints: readonly ["typescript"];
+}>, Readonly<{
+    authoringResolution: "exact-entrypoint";
+    packageName: "esbuild";
+    publicEntrypoints: readonly ["esbuild"];
+}>];
+export declare const NODE_VITEST_PRIVATE_PACKAGE_PREFIXES: readonly ["@vitest/"];
+interface VitestPackageInstallation extends DirectPackageInstallation<"vitest"> {
+    readonly cli: string;
+}
+export interface NodeVitestAuthoringEntrypoints {
+    readonly config: string;
+    readonly contract: string;
+    readonly data: string;
+    readonly root: string;
+    readonly rootPackageJson: string;
+}
+export interface NodeVitestInstallation {
+    readonly authoringEntrypoints: NodeVitestAuthoringEntrypoints;
+    readonly engineId: "node-vitest";
+    readonly packages: {
+        readonly esbuild: DirectPackageInstallation<"esbuild">;
+        readonly typescript: DirectPackageInstallation<"typescript">;
+        readonly vite: DirectPackageInstallation<"vite">;
+        readonly vitest: VitestPackageInstallation;
+    };
+}
+interface NodeVitestResolutionDependencies {
+    readonly importEntrypoint: (selectedPackage: Readonly<ResolvedPackageEntrypoint>) => Promise<unknown>;
+    readonly packageResolver: RootPackageResolver;
+}
+export declare function resolveNodeVitestInstallation(context: Readonly<EngineResolutionContext>, dependencies?: Readonly<NodeVitestResolutionDependencies>): Promise<NodeVitestInstallation>;
+export declare function preflightNodeVitestInstallation(installation: Readonly<NodeVitestInstallation>, context: Readonly<EngineResolutionContext>, importEntrypoint?: (selectedPackage: Readonly<ResolvedPackageEntrypoint>) => Promise<unknown>): Promise<void>;
+export {};

package/dist/engines/installations/node-vitest.js

@@ -0,0 +1 @@
+import p from"node:fs";import u from"node:path";import{isPathWithin as y}from"../../process/files/paths.js";import{BrokenPackageInstallationError as l,RootPackageResolver as g,importResolvedPackageEntrypoint as f}from"./package-resolution.js";export const NODE_VITEST_PACKAGE_REQUIREMENTS=Object.freeze([Object.freeze({authoringResolution:"package-exports",packageName:"vitest",publicEntrypoints:Object.freeze(["vitest"])}),Object.freeze({authoringResolution:"package-exports",packageName:"vite",publicEntrypoints:Object.freeze(["vite"])}),Object.freeze({authoringResolution:"exact-entrypoint",packageName:"typescript",publicEntrypoints:Object.freeze(["typescript"])}),Object.freeze({authoringResolution:"exact-entrypoint",packageName:"esbuild",publicEntrypoints:Object.freeze(["esbuild"])})]),NODE_VITEST_PRIVATE_PACKAGE_PREFIXES=Object.freeze(["@vitest/"]);const E=Object.freeze({importEntrypoint:f,packageResolver:new g});export async function resolveNodeVitestInstallation(t,e=E){t.signal.throwIfAborted();const o=new Map;for(const r of NODE_VITEST_PACKAGE_REQUIREMENTS)o.set(r.packageName,e.packageResolver.resolveImportFromRoot({dependencyGroup:"dependencies",packageName:r.packageName,publicEntrypoint:r.publicEntrypoints[0]}));const i=s(o,"vitest"),n=Object.freeze({authoringEntrypoints:d(e.packageResolver),engineId:"node-vitest",packages:Object.freeze({esbuild:c(s(o,"esbuild")),typescript:c(s(o,"typescript")),vite:c(s(o,"vite")),vitest:Object.freeze({...c(i),cli:v(i,e.packageResolver)})})});return await preflightNodeVitestInstallation(n,t,e.importEntrypoint),n}function d(t){return Object.freeze({config:t.resolveRootPublicEntrypoint("@gfdelarue/testkit/config"),contract:t.resolveRootPublicEntrypoint("@gfdelarue/testkit/node-vitest/contract"),data:t.resolveRootPublicEntrypoint("@gfdelarue/testkit/node-vitest/data"),root:t.resolveRootPublicEntrypoint("@gfdelarue/testkit"),rootPackageJson:t.packageJsonPath})}export async function preflightNodeVitestInstallation(t,e,o=f){for(const i of NODE_VITEST_PACKAGE_REQUIREMENTS){e.signal.throwIfAborted();const n=t.packages[i.packageName];try{const r=await o(n);await h(i.packageName,r)}catch(r){throw e.signal.throwIfAborted(),new l(n.name,n.version,`its public ${i.packageName} capability failed; reinstall without omitting optional dependencies`,{cause:k(r)})}}}function s(t,e){const o=t.get(e);if(o===void 0||o.name!==e)throw new TypeError(`Node/Vitest package resolution did not select ${e}`);return o}function c(t){return Object.freeze({entrypoint:t.entrypoint,name:t.name,root:t.root,version:t.version})}function v(t,e){try{const i=m(t.manifestPath).bin,n=typeof i=="object"&&i!==null&&!Array.isArray(i)?i.vitest:i;if(typeof n!="string"||u.isAbsolute(n))throw new TypeError("package bin.vitest must be a relative path");const r=p.realpathSync(u.resolve(t.root,n));if(!y(t.root,r)||!p.statSync(r).isFile())throw new TypeError("package bin.vitest must resolve to a contained regular file");return r}catch(o){throw e.brokenInstallation(t,"its public Vitest CLI is invalid",o)}}function m(t){const e=JSON.parse(p.readFileSync(t,"utf8"));if(typeof e!="object"||e===null||Array.isArray(e))throw new TypeError("package manifest must contain a JSON object");return e}async function h(t,e){const o=b(e,`${t} public module`);switch(t){case"vitest":a(o,"expect",t),a(o,"test",t);return;case"vite":return;case"typescript":{const i=b(o.ScriptTarget,"typescript ScriptTarget");a(o,"createSourceFile",t)("preflight.ts","export {};",i.Latest);return}case"esbuild":a(o,"stop",t),await a(o,"build",t)({stdin:{contents:"export {};",loader:"js"},write:!1})}}function b(t,e){if(typeof t!="object"||t===null)throw new TypeError(`${e} must be an object`);return t}function a(t,e,o){const i=t[e];if(typeof i!="function")throw new TypeError(`${o} public module must export function ${e}`);return i}function k(t){return t instanceof l&&t.cause!==void 0?t.cause:t}

package/dist/engines/installations/package-resolution.d.ts

@@ -0,0 +1,51 @@
+export declare const TESTKIT_PACKAGE_NAME = "@gfdelarue/testkit";
+export type RootDependencyGroup = "dependencies" | "optionalDependencies";
+export interface PackageResolutionRequest {
+    readonly dependencyGroup: RootDependencyGroup;
+    readonly packageName: string;
+    readonly publicEntrypoint: string;
+}
+export interface ResolvedPackage {
+    readonly entrypoint: string;
+    readonly manifestPath: string;
+    readonly name: string;
+    readonly root: string;
+    readonly version: string;
+}
+export type ResolvedPackageEntrypoint = Pick<ResolvedPackage, "entrypoint" | "name" | "version">;
+export interface RootPackageResolverOptions {
+    readonly packageJsonPath?: string;
+    readonly resolveImportFromRoot?: (specifier: string) => string;
+}
+export declare class RootPackageDeclarationError extends Error {
+    readonly code = "TESTKIT_ROOT_PACKAGE_DECLARATION_INVALID";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class MissingDirectPackageError extends Error {
+    readonly code = "TESTKIT_DIRECT_PACKAGE_MISSING";
+    readonly packageName: string;
+    readonly version: string;
+    constructor(packageName: string, version: string, publicEntrypoint: string, optionalDependency: boolean, options: ErrorOptions);
+}
+export declare class BrokenPackageInstallationError extends Error {
+    readonly code = "TESTKIT_PACKAGE_INSTALLATION_BROKEN";
+    readonly packageName: string;
+    readonly version: string;
+    constructor(packageName: string, version: string, problem: string, options?: ErrorOptions);
+}
+export declare class RootPackageResolver {
+    readonly packageJsonPath: string;
+    readonly packageRoot: string;
+    private readonly manifest;
+    private readonly requireFromRoot;
+    private readonly resolveRootImport;
+    constructor(options?: Readonly<RootPackageResolverOptions>);
+    resolveImportFromRoot(request: Readonly<PackageResolutionRequest>): ResolvedPackage;
+    resolveRequireFromRoot(request: Readonly<PackageResolutionRequest>): ResolvedPackage;
+    resolveRequireFromPackage(parent: Readonly<ResolvedPackage>, request: Readonly<PackageResolutionRequest>): ResolvedPackage;
+    resolveRequirePublicEntrypoint(selectedPackage: Readonly<ResolvedPackage>, publicEntrypoint: string): string;
+    resolveRootPublicEntrypoint(publicEntrypoint: string): string;
+    brokenInstallation(selectedPackage: Readonly<ResolvedPackage>, problem: string, cause: unknown): BrokenPackageInstallationError;
+    private declaredVersion;
+}
+export declare function importResolvedPackageEntrypoint(selectedPackage: Readonly<ResolvedPackageEntrypoint>): Promise<unknown>;

package/dist/engines/installations/package-resolution.js

@@ -0,0 +1 @@
+import u from"node:fs";import{createRequire as h}from"node:module";import l from"node:path";import{fileURLToPath as $,pathToFileURL as b}from"node:url";import{isPathWithin as m}from"../../process/files/paths.js";export const TESTKIT_PACKAGE_NAME="@gfdelarue/testkit";const S=$(new URL("../../../package.json",import.meta.url)),k=/^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;export class RootPackageDeclarationError extends Error{code="TESTKIT_ROOT_PACKAGE_DECLARATION_INVALID";constructor(t,e){super(t,e),this.name="RootPackageDeclarationError"}}export class MissingDirectPackageError extends Error{code="TESTKIT_DIRECT_PACKAGE_MISSING";packageName;version;constructor(t,e,n,r,i){super(`Testkit direct dependency ${t}@${e} could not resolve its public entrypoint ${JSON.stringify(n)} from ${TESTKIT_PACKAGE_NAME}. Run a clean npm install from the consumer lockfile${r?" without omitting optional dependencies":""}.`,i),this.name="MissingDirectPackageError",this.packageName=t,this.version=e}}export class BrokenPackageInstallationError extends Error{code="TESTKIT_PACKAGE_INSTALLATION_BROKEN";packageName;version;constructor(t,e,n,r){super(`Testkit dependency ${t}@${e} is installed but broken: ${n}. Run a clean npm install from the consumer lockfile.`,r),this.name="BrokenPackageInstallationError",this.packageName=t,this.version=e}}export class RootPackageResolver{packageJsonPath;packageRoot;manifest;requireFromRoot;resolveRootImport;constructor(t={}){const e=l.resolve(t.packageJsonPath??S);this.packageJsonPath=p(e,`${TESTKIT_PACKAGE_NAME} package manifest`,(n,r)=>new RootPackageDeclarationError(n,d(r))),this.packageRoot=l.dirname(this.packageJsonPath),this.manifest=T(this.packageJsonPath),this.requireFromRoot=h(this.packageJsonPath),this.resolveRootImport=t.resolveImportFromRoot??F}resolveImportFromRoot(t){const e=this.declaredVersion(t);return g({label:TESTKIT_PACKAGE_NAME,manifestRequire:this.requireFromRoot,resolveEntrypoint:n=>D(this.resolveRootImport(n)),rootSelection:!0},t,e)}resolveRequireFromRoot(t){const e=this.declaredVersion(t);return g({label:TESTKIT_PACKAGE_NAME,manifestRequire:this.requireFromRoot,resolveEntrypoint:this.requireFromRoot.resolve,rootSelection:!0},t,e)}resolveRequireFromPackage(t,e){const n=this.declaredVersion(e),r=v(t),i=h(r.manifestPath);return g({label:`${r.name}@${r.version}`,manifestRequire:i,resolveEntrypoint:i.resolve,rootSelection:!1},e,n)}resolveRequirePublicEntrypoint(t,e){const n=v(t);R(n.name,e);let r;try{r=h(n.manifestPath).resolve(e)}catch(i){throw s(n.name,n.version,`public entrypoint ${JSON.stringify(e)} could not be resolved`,i)}return _(r,n.root,n.name,n.version,e)}resolveRootPublicEntrypoint(t){R(TESTKIT_PACKAGE_NAME,t);let e;try{e=this.requireFromRoot.resolve(t)}catch(r){throw new RootPackageDeclarationError(`${TESTKIT_PACKAGE_NAME} public entrypoint ${JSON.stringify(t)} could not be resolved from its package anchor`,{cause:r})}const n=p(e,`${TESTKIT_PACKAGE_NAME} public entrypoint ${JSON.stringify(t)}`,(r,i)=>new RootPackageDeclarationError(r,d(i)));if(!m(this.packageRoot,n))throw new RootPackageDeclarationError(`${TESTKIT_PACKAGE_NAME} public entrypoint ${JSON.stringify(t)} resolves outside its package root`);return n}brokenInstallation(t,e,n){const r=v(t);return s(r.name,r.version,e,n)}declaredVersion(t){R(t.packageName,t.publicEntrypoint);const e=this.manifest[t.dependencyGroup]?.[t.packageName];if(typeof e!="string"||!k.test(e))throw new RootPackageDeclarationError(`${TESTKIT_PACKAGE_NAME} ${t.dependencyGroup}.${t.packageName} must be an exact version; received ${JSON.stringify(e)}`);return e}}export async function importResolvedPackageEntrypoint(o){const t=P(o);try{return await import(b(t.entrypoint).href)}catch(e){throw s(t.name,t.version,`importing its resolved public entrypoint ${JSON.stringify(t.entrypoint)} failed`,e)}}function g(o,t,e){let n;try{n=o.resolveEntrypoint(t.publicEntrypoint)}catch(a){throw o.rootSelection&&I(a,t.packageName,t.publicEntrypoint)?new MissingDirectPackageError(t.packageName,e,t.publicEntrypoint,t.dependencyGroup==="optionalDependencies",{cause:a}):s(t.packageName,e,o.rootSelection?`its public entrypoint ${JSON.stringify(t.publicEntrypoint)} could not be resolved from the root package anchor`:`its public entrypoint ${JSON.stringify(t.publicEntrypoint)} could not be resolved from the selected ${o.label} package chain`,a)}let r;try{r=p(n,`${t.packageName} public entrypoint ${JSON.stringify(t.publicEntrypoint)}`,(a,y)=>s(t.packageName,e,a,y))}catch(a){throw a instanceof BrokenPackageInstallationError?a:s(t.packageName,e,`its public entrypoint ${JSON.stringify(t.publicEntrypoint)} is invalid`,a)}const i=N(o.manifestRequire,r,t.packageName,e),c=l.dirname(i);if(!m(c,r))throw s(t.packageName,e,`public entrypoint ${JSON.stringify(t.publicEntrypoint)} resolves outside its owning package root`);const f=J(i,t.packageName,e);return Object.freeze({entrypoint:r,manifestPath:i,name:f.name,root:c,version:f.version})}function N(o,t,e,n){try{const i=p(o.resolve(`${e}/package.json`),`${e} package manifest`,(f,a)=>s(e,n,f,a)),c=l.dirname(i);if(!m(c,t))throw s(e,n,"the selected public entrypoint resolves outside the exported package manifest root");return i}catch(i){if(i instanceof BrokenPackageInstallationError)throw i;if(!U(i,e))throw s(e,n,"exported package manifest resolution failed",i)}let r=l.dirname(t);for(;r!==l.parse(r).root;){const i=l.join(r,"package.json");if(A(i,e,n)){const c=p(i,`${e} package manifest`,(a,y)=>s(e,n,a,y)),f=w(c,e,n);if(f.name!==e)throw s(e,n,`manifest discovery reached incompatible package boundary ${JSON.stringify(f.name)} before ${JSON.stringify(e)}`);return c}r=l.dirname(r)}throw s(e,n,"no owning package manifest was found for the selected public entrypoint")}function T(o){const t=O(o,`${TESTKIT_PACKAGE_NAME} package manifest`,(e,n)=>new RootPackageDeclarationError(e,d(n)));if(t.name!==TESTKIT_PACKAGE_NAME)throw new RootPackageDeclarationError(`Root package manifest must name ${JSON.stringify(TESTKIT_PACKAGE_NAME)}; received ${JSON.stringify(t.name)}`);if(typeof t.version!="string")throw new RootPackageDeclarationError(`Root package manifest version must be a string; received ${JSON.stringify(t.version)}`);return E(t,"dependencies"),E(t,"optionalDependencies"),t}function J(o,t,e){const n=w(o,t,e);if(n.name!==t||n.version!==e)throw s(t,e,`manifest must be exactly ${t}@${e}; received ${n.name}@${n.version}`);return n}function w(o,t,e){const n=O(o,`${t} package manifest`,(r,i)=>s(t,e,r,i));if(typeof n.name!="string"||typeof n.version!="string")throw s(t,e,`manifest name and version must be strings; received ${String(n.name)}@${String(n.version)}`);return{name:n.name,version:n.version}}function O(o,t,e){let n;try{n=JSON.parse(u.readFileSync(o,"utf8"))}catch(r){throw e(`${t} could not be read as JSON`,r)}if(typeof n!="object"||n===null||Array.isArray(n))throw e(`${t} must contain a JSON object`);return n}function E(o,t){const e=o[t];if(e!==void 0&&(typeof e!="object"||e===null||Array.isArray(e)))throw new RootPackageDeclarationError(`Root package manifest ${t} must be a JSON object`)}function v(o){if(typeof o.name!="string"||typeof o.version!="string"||typeof o.root!="string"||typeof o.manifestPath!="string"||typeof o.entrypoint!="string")throw new TypeError("Resolved package must contain string identity paths");return o}function P(o){if(typeof o.name!="string"||typeof o.version!="string"||typeof o.entrypoint!="string")throw new TypeError("Resolved package entrypoint must contain string identity fields");return o}function R(o,t){if(o.length===0||t!==o&&!t.startsWith(`${o}/`))throw new RootPackageDeclarationError(`Public entrypoint ${JSON.stringify(t)} must belong to package ${JSON.stringify(o)}`)}function _(o,t,e,n,r){const i=p(o,`${e} public entrypoint ${JSON.stringify(r)}`,(c,f)=>s(e,n,c,f));if(!m(t,i))throw s(e,n,`public entrypoint ${JSON.stringify(r)} resolves outside its owning package root`);return i}function p(o,t,e){let n,r;try{n=u.realpathSync(o),r=u.statSync(n)}catch(i){throw e(`${t} could not be resolved as a real file`,i)}if(!r.isFile())throw e(`${t} must be a regular file`);return n}function A(o,t,e){try{return u.lstatSync(o),!0}catch(n){if(M(n))return!1;throw s(t,e,"owning package manifest discovery failed",n)}}function I(o,t,e){if(typeof o!="object"||o===null)return!1;const n=o;return(n.code==="MODULE_NOT_FOUND"||n.code==="ERR_MODULE_NOT_FOUND")&&typeof n.message=="string"&&(n.message.startsWith(`Cannot find module '${e}'`)||n.message.startsWith(`Cannot find package '${t}'`))}function D(o){let t;try{t=new URL(o)}catch(e){throw new TypeError(`Root import resolution must return an absolute URL; received ${JSON.stringify(o)}`,{cause:e})}if(t.protocol!=="file:")throw new TypeError(`Root package entrypoint must resolve to a file URL; received ${JSON.stringify(o)}`);return $(t)}function F(o){return import.meta.resolve(o)}function M(o){if(typeof o!="object"||o===null)return!1;const t=o.code;return t==="ENOENT"||t==="ENOTDIR"}function U(o,t){if(typeof o!="object"||o===null)return!1;const e=o;return e.code==="ERR_PACKAGE_PATH_NOT_EXPORTED"?!0:(e.code==="MODULE_NOT_FOUND"||e.code==="ERR_MODULE_NOT_FOUND")&&typeof e.message=="string"&&(e.message.startsWith(`Cannot find module '${t}/package.json'`)||e.message.startsWith(`Cannot find package '${t}'`))}function s(o,t,e,n){return new BrokenPackageInstallationError(o,t,e,d(n))}function d(o){return o===void 0?void 0:{cause:o}}

package/dist/engines/installations/playwright-resolution-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engines/installations/playwright-resolution-child.js

@@ -0,0 +1,2 @@
+import{pathToFileURL as y}from"node:url";p();async function p(){try{const t=f(process.argv[2]);l(t.registry.canonicalValue);const e=await import(y(t.family.playwrightTest.entrypoint).href),r=m(e),n=h(r.chromium,"chromium"),s=n.executablePath;if(typeof s!="function")throw new TypeError("Authoritative @playwright/test module must expose chromium.executablePath()");const c=Reflect.apply(s,n,[]);if(typeof c!="string")throw new TypeError("chromium.executablePath() must return a string");u({browserExecutable:c,family:t.family,ok:!0,registry:t.registry})}catch(t){const e=d(t);u({error:{...e.code===void 0?{}:{code:e.code},message:e.message,name:e.name},ok:!1}),process.exitCode=1}}function f(t){if(t===void 0)throw new TypeError("Playwright resolution child requires one input");let e;try{e=JSON.parse(Buffer.from(t,"base64url").toString("utf8"))}catch(r){throw new TypeError("Playwright resolution child input is invalid",{cause:r})}if(!o(e)||!g(e.family)||!o(e.registry)||typeof e.registry.canonicalValue!="string"||typeof e.registry.mode!="string")throw new TypeError("Playwright resolution child input is invalid");return e}function l(t){if(process.env.PLAYWRIGHT_BROWSERS_PATH!==t)throw new Error("Playwright resolution child did not receive the canonical browser registry")}function m(t){const e=a(t,"@playwright/test module namespace"),r=e.default??e["module.exports"]??e;return a(r,"@playwright/test public module")}function g(t){return o(t)&&typeof t.cli=="string"&&i(t.playwrightTest,"@playwright/test")&&i(t.playwright,"playwright")&&i(t.playwrightCore,"playwright-core")}function i(t,e){return o(t)&&t.name===e&&typeof t.version=="string"&&typeof t.root=="string"&&typeof t.entrypoint=="string"}function h(t,e){if(!o(t))throw new TypeError(`${e} must be an object`);return t}function a(t,e){if((typeof t!="object"||t===null)&&typeof t!="function")throw new TypeError(`${e} must be an object or function`);return t}function o(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function d(t){if(!(t instanceof Error))return{message:String(t),name:"Error"};const e=Reflect.get(t,"code");return{...typeof e=="string"?{code:e}:{},message:t.message,name:t.name}}function u(t){process.stdout.write(`${JSON.stringify(t)}
+`)}

package/dist/engines/installations/playwright.d.ts

@@ -0,0 +1,85 @@
+import { type ManagedProcessResult } from "../../process/index.js";
+import { type LinuxLibc, type PlatformTarget } from "../../process/host/platform.js";
+import { RootPackageResolver } from "./package-resolution.js";
+import type { DirectPackageInstallation, EngineResolutionContext } from "./types.js";
+export declare const PLAYWRIGHT_PACKAGE_FAMILY_REQUIREMENTS: readonly [Readonly<{
+    packageName: "@playwright/test";
+    publicEntrypoints: readonly ["@playwright/test", "@playwright/test/cli"];
+}>, Readonly<{
+    packageName: "playwright";
+    publicEntrypoints: readonly ["playwright"];
+}>, Readonly<{
+    packageName: "playwright-core";
+    publicEntrypoints: readonly ["playwright-core"];
+}>];
+export interface PlaywrightPackageFamily {
+    readonly cli: string;
+    readonly playwright: DirectPackageInstallation<"playwright">;
+    readonly playwrightCore: DirectPackageInstallation<"playwright-core">;
+    readonly playwrightTest: DirectPackageInstallation<"@playwright/test">;
+}
+export type PlaywrightRegistryMode = "configured-absolute" | "configured-relative" | "default" | "hermetic";
+export interface PlaywrightRegistrySelection {
+    readonly canonicalValue: string;
+    readonly mode: PlaywrightRegistryMode;
+}
+export interface PlaywrightInstallation {
+    readonly authoringEntrypoints: {
+        readonly authoring: string;
+        readonly root: string;
+        readonly rootPackageJson: string;
+    };
+    readonly browserExecutable: string;
+    readonly engineId: "playwright";
+    readonly family: PlaywrightPackageFamily;
+    readonly registry: PlaywrightRegistrySelection;
+}
+export interface PlaywrightResolutionOptions {
+    readonly ambientEnvironment?: Readonly<NodeJS.ProcessEnv>;
+    readonly configuredRegistry?: string;
+}
+export interface PlaywrightHost {
+    readonly linuxLibc: LinuxLibc | null;
+    readonly target: PlatformTarget;
+}
+interface PlaywrightChildRequest {
+    readonly family: PlaywrightPackageFamily;
+    readonly registry: PlaywrightRegistrySelection;
+}
+interface PlaywrightChildSuccess extends PlaywrightChildRequest {
+    readonly browserExecutable: string;
+    readonly ok: true;
+}
+export declare class PlaywrightInstallationError extends Error {
+    readonly code = "TESTKIT_PLAYWRIGHT_INSTALLATION_INVALID";
+    constructor(problem: string, options?: ErrorOptions);
+}
+export declare class UnsupportedPlaywrightPlatformError extends Error {
+    readonly code = "TESTKIT_PLAYWRIGHT_PLATFORM_UNSUPPORTED";
+    constructor(target: Readonly<PlatformTarget>, linuxLibc: LinuxLibc | null);
+}
+export declare function resolvePlaywrightPackageFamily(resolver?: RootPackageResolver): PlaywrightPackageFamily;
+export declare function resolvePlaywrightRegistry(options: {
+    readonly ambientEnvironment: Readonly<NodeJS.ProcessEnv>;
+    readonly configuredValue?: string;
+    readonly homeDirectory?: string;
+    readonly platform: PlatformTarget["platform"];
+    readonly productRoot: string;
+}): PlaywrightRegistrySelection;
+export declare function playwrightRegistryEnvironment(ambientEnvironment: Readonly<NodeJS.ProcessEnv>, registry: Readonly<PlaywrightRegistrySelection>): Readonly<Record<string, string>>;
+export declare function resolvePlaywrightInstallation(context: Readonly<EngineResolutionContext>, options?: Readonly<PlaywrightResolutionOptions>): Promise<PlaywrightInstallation>;
+export declare function throwIfPlaywrightProcessAborted(signal: AbortSignal, result: Readonly<ManagedProcessResult>, processFailure: Error | null): void;
+type ParsedChildOutput = PlaywrightChildSuccess | Readonly<{
+    error: Readonly<{
+        code?: string;
+        message: string;
+        name: string;
+    }>;
+    ok: false;
+}>;
+export declare function requireBoundedPlaywrightChildOutput(stdout: string): void;
+export declare function parsePlaywrightChildOutput(stdout: string): ParsedChildOutput;
+export declare function requireMatchingPlaywrightChildRequest(output: Readonly<PlaywrightChildSuccess>, request: Readonly<PlaywrightChildRequest>): void;
+export declare function requireBrowserExecutable(value: string, target: Readonly<PlatformTarget>): string;
+export declare function requireSupportedPlaywrightHost(host: Readonly<PlaywrightHost>): void;
+export {};

package/dist/engines/installations/playwright.js

@@ -0,0 +1 @@
+import c from"node:fs";import w from"node:os";import f from"node:path";import{fileURLToPath as h}from"node:url";import{runManagedProcess as R}from"../../process/index.js";import{currentLinuxLibc as x,currentPlatformTarget as O,platformTargetKey as g,SUPPORTED_PLATFORM_TARGETS as T}from"../../process/host/platform.js";import{RootPackageResolver as m}from"./package-resolution.js";export const PLAYWRIGHT_PACKAGE_FAMILY_REQUIREMENTS=Object.freeze([Object.freeze({packageName:"@playwright/test",publicEntrypoints:Object.freeze(["@playwright/test","@playwright/test/cli"])}),Object.freeze({packageName:"playwright",publicEntrypoints:Object.freeze(["playwright"])}),Object.freeze({packageName:"playwright-core",publicEntrypoints:Object.freeze(["playwright-core"])})]);const _=64*1024,S=6e4,b="PLAYWRIGHT_BROWSERS_PATH",I=new Set(["npm_config_playwright_browsers_path","npm_package_config_playwright_browsers_path"]);export class PlaywrightInstallationError extends Error{code="TESTKIT_PLAYWRIGHT_INSTALLATION_INVALID";constructor(r,t){super(`Playwright installation is invalid: ${r}. Run testkit setup playwright --force.`,t),this.name="PlaywrightInstallationError"}}export class UnsupportedPlaywrightPlatformError extends Error{code="TESTKIT_PLAYWRIGHT_PLATFORM_UNSUPPORTED";constructor(r,t){super(`Playwright does not support ${g(r)}${r.platform==="linux"?` with ${t??"unknown"} libc`:""}`),this.name="UnsupportedPlaywrightPlatformError"}}export function resolvePlaywrightPackageFamily(e=new m){const[r,t,o]=PLAYWRIGHT_PACKAGE_FAMILY_REQUIREMENTS,i=e.resolveRequireFromRoot(u(r)),n=e.resolveImportFromRoot(u(r));A(e,i,n);const a=e.resolveRequireFromPackage(i,u(t)),s=e.resolveRequireFromPackage(a,u(o)),P=e.resolveRequirePublicEntrypoint(i,r.publicEntrypoints[1]);return Object.freeze({cli:P,playwright:p(a,"playwright"),playwrightCore:p(s,"playwright-core"),playwrightTest:p(n,"@playwright/test")})}function A(e,r,t){if(!(r.name===t.name&&r.version===t.version&&r.root===t.root))throw e.brokenInstallation(r,"the import and require public entrypoints select different physical package roots",void 0)}export function resolvePlaywrightRegistry(e){const r=e.platform==="win32"?f.win32:f.posix;if(!r.isAbsolute(e.productRoot))throw new TypeError("Playwright product root must be absolute");const t=e.configuredValue;if(t==="0")return Object.freeze({canonicalValue:"0",mode:"hermetic"});if(t!==void 0&&t.length>0){const o=r.isAbsolute(t);return Object.freeze({canonicalValue:o?r.normalize(t):r.resolve(e.productRoot,t),mode:o?"configured-absolute":"configured-relative"})}return Object.freeze({canonicalValue:r.resolve(e.productRoot,r.join(v(e.platform,e.ambientEnvironment,e.homeDirectory??w.homedir(),r),"ms-playwright")),mode:"default"})}export function playwrightRegistryEnvironment(e,r){const t={};for(const[o,i]of Object.entries(e))typeof i=="string"&&!I.has(o.toLowerCase())&&o.toUpperCase()!==b&&(t[o]=i);return t[b]=r.canonicalValue,Object.freeze(t)}export async function resolvePlaywrightInstallation(e,r={}){e.signal.throwIfAborted();const t={linuxLibc:x(),target:O()};requireSupportedPlaywrightHost(t);const o=new m,i=r.ambientEnvironment??process.env,n=resolvePlaywrightPackageFamily(o),a=resolvePlaywrightRegistry({ambientEnvironment:i,configuredValue:r.configuredRegistry??i.PLAYWRIGHT_BROWSERS_PATH,homeDirectory:w.homedir(),platform:t.target.platform,productRoot:e.productRoot}),s=await L(e,{family:n,registry:a},i);return Object.freeze({authoringEntrypoints:Object.freeze({authoring:o.resolveRootPublicEntrypoint("@gfdelarue/testkit/playwright"),root:o.resolveRootPublicEntrypoint("@gfdelarue/testkit"),rootPackageJson:o.resolveRootPublicEntrypoint("@gfdelarue/testkit/package.json")}),browserExecutable:requireBrowserExecutable(s.browserExecutable,t.target),engineId:"playwright",family:n,registry:a})}async function L(e,r,t){const o=Buffer.from(JSON.stringify(r),"utf8").toString("base64url"),i=await R({args:[j(),o],cwd:e.productRoot,displayLabel:"Playwright installation resolver",env:playwrightRegistryEnvironment(t,r.registry),executable:process.execPath,signal:e.signal,timeoutMs:S}),n=C(i);throwIfPlaywrightProcessAborted(e.signal,i,n),requireBoundedPlaywrightChildOutput(i.stdout);let a;try{a=parsePlaywrightChildOutput(i.stdout)}catch(s){throw n!==null?new PlaywrightInstallationError(`isolated resolver failed: ${n.message}`,{cause:n}):s}if(n!==null)throw new PlaywrightInstallationError(`isolated resolver failed: ${n.message}`,{cause:n});if(!a.ok){if(i.exitCode!==1||i.exitSignal!==null){const s=E(i);throw new PlaywrightInstallationError(`isolated resolver failed: ${s.message}`,{cause:s})}throw new PlaywrightInstallationError(`isolated resolver failed: ${a.error.message}`,{cause:N(a.error)})}if(i.exitCode!==0||i.exitSignal!==null){const s=E(i);throw new PlaywrightInstallationError(`isolated resolver failed: ${s.message}`,{cause:s})}return requireMatchingPlaywrightChildRequest(a,r),a}export function throwIfPlaywrightProcessAborted(e,r,t){if(e.aborted){if(!k(r)||t===null){e.throwIfAborted();return}throw t===e.reason?t:new AggregateError([e.reason,t],"Playwright process was cancelled and process cleanup also failed",{cause:e.reason})}}function k(e){return e.terminationError!==null||e.error!==null||e.timedOut||e.outputLimitExceeded}export function requireBoundedPlaywrightChildOutput(e){if(Buffer.byteLength(e,"utf8")>_)throw new PlaywrightInstallationError("isolated resolver returned oversized output")}export function parsePlaywrightChildOutput(e){let r;try{r=JSON.parse(e)}catch(t){throw new PlaywrightInstallationError("isolated resolver did not return bounded JSON",{cause:t})}if(!l(r)||typeof r.ok!="boolean")throw new PlaywrightInstallationError("isolated resolver returned an invalid response");if(!r.ok){if(!l(r.error)||typeof r.error.name!="string"||typeof r.error.message!="string"||r.error.code!==void 0&&typeof r.error.code!="string")throw new PlaywrightInstallationError("isolated resolver returned an invalid error");return{error:{...r.error.code===void 0?{}:{code:r.error.code},message:r.error.message,name:r.error.name},ok:!1}}if(typeof r.browserExecutable!="string"||!z(r.family)||!$(r.registry))throw new PlaywrightInstallationError("isolated resolver returned an invalid installation");return{browserExecutable:r.browserExecutable,family:r.family,ok:!0,registry:r.registry}}export function requireMatchingPlaywrightChildRequest(e,r){if(JSON.stringify(e.family)!==JSON.stringify(r.family))throw new PlaywrightInstallationError("isolated resolver selected a different physical package family");if(e.registry.canonicalValue!==r.registry.canonicalValue||e.registry.mode!==r.registry.mode)throw new PlaywrightInstallationError("isolated resolver selected a different browser registry")}export function requireBrowserExecutable(e,r){if(!f.isAbsolute(e))throw new PlaywrightInstallationError(`public chromium.executablePath() returned a non-absolute path ${JSON.stringify(e)}`);let t;try{t=c.statSync(e)}catch(o){throw new PlaywrightInstallationError(`public chromium.executablePath() returned missing path ${JSON.stringify(e)}`,{cause:o})}if(!t.isFile())throw new PlaywrightInstallationError(`public chromium.executablePath() must identify a regular file; received ${JSON.stringify(e)}`);if(r.platform!=="win32")try{c.accessSync(e,c.constants.X_OK)}catch(o){throw new PlaywrightInstallationError(`public chromium.executablePath() is not executable: ${JSON.stringify(e)}`,{cause:o})}return e}export function requireSupportedPlaywrightHost(e){const r=g(e.target);if(!T.some(t=>g(t)===r)||e.target.platform==="linux"&&e.linuxLibc!=="glibc")throw new UnsupportedPlaywrightPlatformError(e.target,e.linuxLibc)}function v(e,r,t,o){return e==="linux"?r.XDG_CACHE_HOME||o.join(d(t),".cache"):e==="darwin"?o.join(d(t),"Library","Caches"):r.LOCALAPPDATA||o.join(d(t),"AppData","Local")}function d(e){if(e.length===0)throw new TypeError("Playwright default registry requires a home directory");return e}function u(e){return{dependencyGroup:"dependencies",packageName:e.packageName,publicEntrypoint:e.publicEntrypoints[0]}}function p(e,r){if(e.name!==r)throw new TypeError(`Playwright package family expected ${r}, received ${e.name}`);return Object.freeze({entrypoint:e.entrypoint,name:r,root:e.root,version:e.version})}function j(){const e=h(new URL("./playwright-resolution-child.js",import.meta.url));return c.existsSync(e)?e:h(new URL("../../../dist/engines/installations/playwright-resolution-child.js",import.meta.url))}function C(e){return e.terminationError!==null?e.terminationError:e.error!==null?e.error:e.timedOut?new Error("isolated resolver timed out"):e.cancelled?new Error("isolated resolver was cancelled"):e.outputLimitExceeded?new Error("isolated resolver output exceeded the bound"):null}function E(e){return new Error(`isolated resolver exited with ${e.exitCode===null?String(e.exitSignal):e.exitCode.toString()}`)}function N(e){const r=new Error(e.message);return r.name=e.name,e.code!==void 0&&Object.defineProperty(r,"code",{enumerable:!0,value:e.code}),r}function z(e){return l(e)&&typeof e.cli=="string"&&y(e.playwrightTest,"@playwright/test")&&y(e.playwright,"playwright")&&y(e.playwrightCore,"playwright-core")}function y(e,r){return l(e)&&e.name===r&&typeof e.version=="string"&&typeof e.root=="string"&&typeof e.entrypoint=="string"}function $(e){return l(e)&&typeof e.canonicalValue=="string"&&(e.mode==="configured-absolute"||e.mode==="configured-relative"||e.mode==="default"||e.mode==="hermetic")}function l(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}

package/dist/engines/installations/types.d.ts

@@ -0,0 +1,10 @@
+export interface EngineResolutionContext {
+    readonly productRoot: string;
+    readonly signal: AbortSignal;
+}
+export interface DirectPackageInstallation<Name extends string = string> {
+    readonly entrypoint: string;
+    readonly name: Name;
+    readonly root: string;
+    readonly version: string;
+}

package/dist/engines/installations/types.js

@@ -0,0 +1 @@
+export{};

package/dist/engines/k6/adapter/bundle.d.ts

@@ -0,0 +1,25 @@
+import type { EngineCancellationSignal, EngineJsonObject } from "../../api/index.js";
+import { type BuildFailure } from "esbuild";
+export declare class K6ConsumerCompilationError extends Error {
+    constructor(error: BuildFailure);
+}
+export interface K6BundleRequest {
+    readonly configuration?: EngineJsonObject;
+    readonly entrypoints: Readonly<{
+        authoring: string;
+        config: string;
+        root: string;
+        rootPackageJson: string;
+    }>;
+    readonly nativeSummaryDirectory: string;
+    readonly outputFile: string;
+    readonly rootDirectory: string;
+    readonly signal: EngineCancellationSignal;
+    readonly sourceFile: string;
+}
+/**
+ * Builds a self-contained Sobek/k6 module. Testkit public imports resolve only
+ * to the selected root package entrypoints; native k6/xk6 modules remain
+ * external for Sobek to provide.
+ */
+export declare function bundleK6Suite({ configuration, entrypoints, outputFile, nativeSummaryDirectory, rootDirectory, signal, sourceFile, }: Readonly<K6BundleRequest>): Promise<void>;

package/dist/engines/k6/adapter/bundle.js

@@ -0,0 +1,112 @@
+import n from"node:fs/promises";import k from"node:path";import{context as T}from"esbuild";import{parseK6RepositoryConfiguration as R}from"../../contracts/k6-repository-configuration.js";const v=/^@gfdelarue\/testkit(?:\/|$)/,I=/^@gfdelarue\/testkit-engine-/,C=/^(?:@playwright\/|@vitest\/|playwright(?:-core)?(?:\/|$)|vitest(?:\/|$))/;export class K6ConsumerCompilationError extends Error{constructor(t){super(t.message,{cause:t}),this.name="K6ConsumerCompilationError"}}export async function bundleK6Suite({configuration:e,entrypoints:t,outputFile:r,nativeSummaryDirectory:o,rootDirectory:s,signal:i,sourceFile:w}){g(i);const S=await A(t),l=R(e);await n.mkdir(k.dirname(r),{recursive:!0});const m=`${r}.entry.mjs`,a=l===null?null:`${r}.configuration.mjs`;try{const y=[n.writeFile(m,N(w,a,o),"utf8")];a!==null&&l!==null&&y.push(n.writeFile(a,x(l),"utf8")),await Promise.all(y);const E={absWorkingDir:s,bundle:!0,charset:"utf8",define:{"process.env":"__ENV"},entryPoints:[m],external:["k6","k6/*","xk6-sql","xk6-sql/*"],format:"esm",legalComments:"none",logLevel:"silent",outfile:r,platform:"neutral",plugins:[P(S)],sourcemap:"inline",target:"es2020",treeShaking:!0,write:!1},f=await T(E),h=()=>{f.cancel().catch(()=>{})};i.addEventListener("abort",h,{once:!0});try{g(i);let c;try{c=await f.rebuild()}catch(d){throw b(d)?new K6ConsumerCompilationError(d):d}g(i);const _=c.outputFiles?.at(0);if(c.outputFiles?.length!==1||_===void 0)throw new Error("k6 bundler did not produce exactly one output file");await n.writeFile(r,_.contents)}finally{i.removeEventListener("abort",h),await f.dispose()}}finally{await Promise.all([n.rm(m,{force:!0}),...a===null?[]:[n.rm(a,{force:!0})]])}}function b(e){return e instanceof Error&&Array.isArray(Reflect.get(e,"errors"))&&Array.isArray(Reflect.get(e,"warnings"))}function g(e){if(e.aborted)throw new Error("k6 bundle preparation was cancelled")}function P(e){return{name:"testkit-managed-public-entrypoints",setup(t){t.onResolve({filter:/^@gfdelarue\/testkit\/config$/},()=>({path:e.config})),t.onResolve({filter:/^@gfdelarue\/testkit\/k6$/},()=>({path:e.authoring})),t.onResolve({filter:/^@gfdelarue\/testkit$/},()=>({path:e.root})),t.onResolve({filter:/^@gfdelarue\/testkit\/package\.json$/},()=>({path:e.rootPackageJson})),t.onResolve({filter:v},r=>p(r.path,"unsupported Testkit package subpath")),t.onResolve({filter:I},r=>p(r.path,"internal engine package")),t.onResolve({filter:C},r=>p(r.path,"another engine's package"))}}}function p(e,t){return{errors:[{text:`k6 consumer modules may not import ${t} "${e}"`}]}}async function A(e){const[t,r,o,s]=await Promise.all([u(e.authoring,"authoring"),u(e.config,"config"),u(e.root,"root"),u(e.rootPackageJson,"rootPackageJson")]);return Object.freeze({authoring:t,config:r,root:o,rootPackageJson:s})}async function u(e,t){if(!k.isAbsolute(e))throw new Error(`Resolved k6 installation must provide an absolute ${t} entrypoint`);const r=await n.realpath(e);if(!(await n.stat(r)).isFile())throw new Error(`Resolved k6 installation ${t} entrypoint must be a regular file`);return r}function N(e,t,r){const o=JSON.stringify(e);return`
+${t===null?"":`import ${JSON.stringify(t)};`}
+import { sha256 as __testkitSha256 } from "k6/crypto";
+import * as __testkitConsumerModule from ${o};
+const __testkitDefault = __testkitConsumerModule.default;
+export { __testkitDefault as default };
+export * from ${o};
+// All k6 lifecycle functions, options, and named scenario executors remain
+// native re-exports. Testkit suite helpers must be exported in native k6 module
+// shape by their authoring file. The optional default binding remains undefined
+// when a native named-scenarios-only module has no default export.
+// handleSummary is delegated below so consumer files can only be written under
+// the executor-owned invocation workspace and then promoted as bounded evidence.
+
+export async function handleSummary(data) {
+  const consumerHandleSummary = __testkitConsumerModule.handleSummary;
+  if (typeof consumerHandleSummary !== "function") return {};
+  const outputs = await consumerHandleSummary(data);
+  if (outputs === null || typeof outputs !== "object" || Array.isArray(outputs)) {
+    throw new Error(
+      "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary must return an object",
+    );
+  }
+  const redirected = {};
+  const manifest = [];
+  let fileCount = 0;
+  let totalBytes = 0;
+  for (const [name, value] of Object.entries(outputs)) {
+    const sizeBytes = __testkitSummaryOutputBytes(value, name);
+    totalBytes += sizeBytes;
+    if (totalBytes > 16 * 1024 * 1024) {
+      throw new Error(
+        "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary output exceeds the 16777216 byte aggregate limit",
+      );
+    }
+    if (name === "stdout" || name === "stderr") {
+      redirected[name] = value;
+      continue;
+    }
+    __testkitRequireSafeSummaryName(name);
+    fileCount += 1;
+    if (fileCount > 128) {
+      throw new Error(
+        "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary returned more than 128 file outputs",
+      );
+    }
+    const storedName = __testkitSha256(name, "hex") + ".output";
+    redirected[${JSON.stringify(r)} + "/" + storedName] = value;
+    manifest.push({
+      name,
+      sha256: __testkitSha256(value, "hex"),
+      sizeBytes,
+      storedName,
+    });
+  }
+  if (manifest.length > 0) {
+    redirected[${JSON.stringify(r)} + "/manifest.json"] =
+      JSON.stringify({ entries: manifest, version: 1 });
+  }
+  return redirected;
+}
+
+function __testkitRequireSafeSummaryName(name) {
+  if (
+    typeof name !== "string" ||
+    name.length === 0 ||
+    name.length > 240 ||
+    name.includes("\\0") ||
+    name.startsWith("/") ||
+    name.startsWith("\\\\") ||
+    /^[a-z]:/iu.test(name)
+  ) {
+    throw new Error(
+      "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary output name must be a safe relative path",
+    );
+  }
+  const segments = name.split(/[\\\\/]/u);
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(
+      "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary output name contains traversal",
+    );
+  }
+}
+
+function __testkitSummaryOutputBytes(value, name) {
+  let sizeBytes;
+  if (typeof value === "string") {
+    sizeBytes = 0;
+    for (const character of value) {
+      const codePoint = character.codePointAt(0);
+      sizeBytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
+    }
+  } else if (value instanceof ArrayBuffer) {
+    sizeBytes = value.byteLength;
+  } else {
+    throw new Error(
+      "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary output " + name + " must be a string or ArrayBuffer",
+    );
+  }
+  if (sizeBytes > 8 * 1024 * 1024) {
+    throw new Error(
+      "TESTKIT_K6_SUMMARY_OUTPUT_INVALID: handleSummary output " + name + " exceeds the 8388608 byte limit",
+    );
+  }
+  return sizeBytes;
+}
+`}function x(e){return`
+import { registerRepoConfig as __testkitRegisterPublicConfig } from "@gfdelarue/testkit/config";
+import { __testkitRegisterK6RepositoryConfiguration as __testkitRegisterRuntimeConfig } from "@gfdelarue/testkit/k6";
+const __testkitRepositoryConfiguration = ${JSON.stringify(e)};
+__testkitRegisterPublicConfig(__testkitRegisterRuntimeConfig(__testkitRepositoryConfiguration));
+`}

package/dist/engines/k6/adapter/evidence.d.ts

@@ -0,0 +1,15 @@
+import { type EvidenceFileAccess } from "../../adapters/evidence-files.js";
+import type { EngineEvidence, EngineJsonObject } from "../../api/index.js";
+export interface K6EvidenceRequest {
+    readonly artifactDirectory: string;
+    readonly stderr: string;
+    readonly stdout: string;
+    readonly summaryFile: string;
+}
+export declare const K6_SUMMARY_MAX_BYTES: number;
+export interface K6EvidenceResult {
+    readonly evidence: EngineEvidence;
+    readonly summary: EngineJsonObject | null;
+    readonly summaryError: Error | null;
+}
+export declare function collectK6Evidence({ artifactDirectory, stderr, stdout, summaryFile }: Readonly<K6EvidenceRequest>, fileAccess?: EvidenceFileAccess): Promise<K6EvidenceResult>;