@gfdelarue/testkit 0.3.0

package/dist/engines/adapters/execution.d.ts

@@ -0,0 +1,38 @@
+import { type EngineCancellationSignal, type EngineEvidence, type EngineExecutionInputs, type EngineExecutionRequest, type EngineExecutionResult, type EngineExecutionTask, type EngineFailureEvidence, type EngineJsonObject, type EngineTaskOutcome } from "../api/index.js";
+import { type TestOutcomeStatus } from "../../domain/test-outcomes.js";
+import type { ManagedProcessResult } from "../../process/index.js";
+export interface EngineFailureIdentity {
+    readonly codePrefix: string;
+    readonly label: string;
+}
+export interface ProcessClassification {
+    readonly failure: EngineFailureEvidence | null;
+    readonly status: TestOutcomeStatus;
+}
+interface EngineTaskPreparation {
+    readonly artifactDirectory: string;
+    readonly inputs: EngineExecutionInputs;
+    readonly task: EngineExecutionTask;
+}
+export type ReadyEngineTask<T> = EngineTaskPreparation & {
+    readonly preparationFailure: null;
+    readonly prepared: T;
+};
+export type PreparedEngineTask<T> = ReadyEngineTask<T> | (EngineTaskPreparation & {
+    readonly preparationFailure: EngineFailureEvidence;
+    readonly prepared: null;
+});
+export declare function executeEngineTasks<T>(request: Pick<EngineExecutionRequest, "invocationId" | "observer" | "signal">, tasks: readonly PreparedEngineTask<T>[], identity: EngineFailureIdentity, execute: (task: ReadyEngineTask<T>, startedAtMs: number) => Promise<EngineTaskOutcome>, native: EngineJsonObject): Promise<EngineExecutionResult>;
+export declare function taskBeforeStartOutcome(task: EngineExecutionTask, signal: EngineCancellationSignal, startedAtMs: number, identity: EngineFailureIdentity): EngineTaskOutcome | null;
+export declare function taskTimeoutFailure(timeoutMs: number, identity: EngineFailureIdentity): EngineFailureEvidence;
+export declare function managedProcessFailure(result: ManagedProcessResult, identity: EngineFailureIdentity, evidenceError?: Error | null): EngineFailureEvidence | null;
+export declare function classifyManagedProcessResult(result: ManagedProcessResult, timeoutMs: number, deadlineExceeded: boolean, identity: EngineFailureIdentity): ProcessClassification | null;
+export declare function processExitFailure(result: ManagedProcessResult, identity: EngineFailureIdentity, selectedMessage?: string | null, fallbackLabel?: string): ProcessClassification;
+export declare function firstOutputLine(output: string): string | null;
+export declare function terminalOutcome(taskId: string, status: TestOutcomeStatus, startedAtMs: number, evidence: EngineEvidence, failure: EngineFailureEvidence | null): EngineTaskOutcome;
+export declare function processOutputEvidence(result: ManagedProcessResult): EngineEvidence;
+export declare function emptyEvidence(): EngineEvidence;
+export declare function failureFromError(error: unknown, code: string): EngineFailureEvidence;
+export declare function errorDetails(error: Error): EngineJsonObject;
+export declare function toError(error: unknown): Error;
+export {};

package/dist/engines/adapters/execution.js

@@ -0,0 +1 @@
+import{isEngineTaskDeadlineExceededReason as d}from"../api/index.js";import"../../domain/test-outcomes.js";export async function executeEngineTasks(e,t,n,i,o){const r=[];for(const a of t){e.observer?.taskStarted(a.task);const s=Date.now(),c=taskBeforeStartOutcome(a.task,e.signal,s,n);c!==null?r.push(c):a.preparationFailure!==null?r.push(terminalOutcome(a.task.id,"failed",s,emptyEvidence(),a.preparationFailure)):r.push(await i(a,s))}for(const[a,s]of r.entries())e.observer?.evidenceRecorded(t[a].task.id,s.evidence),e.observer?.taskFinished(s);return{evidence:{artifacts:r.flatMap(a=>a.evidence.artifacts),logs:r.flatMap(a=>a.evidence.logs),metrics:r.flatMap(a=>a.evidence.metrics),native:o},invocationId:e.invocationId,outcomes:r}}export function taskBeforeStartOutcome(e,t,n,i){return e.deadlineMs<=n||d(t.reason)?terminalOutcome(e.id,"failed",n,emptyEvidence(),taskTimeoutFailure(e.timeoutMs,i)):t.aborted?terminalOutcome(e.id,"cancelled",n,emptyEvidence(),{code:`${i.codePrefix}_CANCELLED`,message:`${i.label} task was cancelled before its process started`}):null}export function taskTimeoutFailure(e,t){return{code:`${t.codePrefix}_TASK_TIMEOUT`,details:{timeoutMs:e},message:`${t.label} task exceeded its ${e.toString()}ms timeout`}}export function managedProcessFailure(e,t,n=null){return e.terminationError===null?null:{classification:"infra",code:`${t.codePrefix}_PROCESS_TERMINATION_INCOMPLETE`,details:{cancelled:e.cancelled,...n===null?{}:{evidenceCollectionFailure:errorDetails(n)},outputLimitExceeded:e.outputLimitExceeded,timedOut:e.timedOut},message:`${t.label} managed-process termination was incomplete: ${e.terminationError.message}`,...e.terminationError.stack===void 0?{}:{stack:e.terminationError.stack}}}export function classifyManagedProcessResult(e,t,n,i){const o=a=>({failure:a,status:"failed"}),r=managedProcessFailure(e,i);return r!==null?o(r):e.timedOut||n?o(taskTimeoutFailure(t,i)):e.cancelled?{failure:{code:`${i.codePrefix}_CANCELLED`,message:`${i.label} task was cancelled`},status:"cancelled"}:e.outputLimitExceeded?o({code:`${i.codePrefix}_OUTPUT_LIMIT`,message:`${i.label} task exceeded the bounded stdout/stderr capture limit`}):e.error!==null?o({...failureFromError(e.error,`${i.codePrefix}_PROCESS_START_FAILED`),classification:"infra"}):null}export function processExitFailure(e,t,n=null,i=t.label){return{failure:{code:`${t.codePrefix}_PROCESS_FAILED`,details:{...e.exitCode===null?{}:{exitCode:e.exitCode},...e.exitSignal===null?{}:{exitSignal:e.exitSignal}},message:n??(e.exitCode===null?`${i} process terminated by ${e.exitSignal??"an unknown signal"}`:`${i} process exited with code ${e.exitCode.toString()}`)},status:"failed"}}export function firstOutputLine(e){const t=e.split(/\r?\n/u).map(n=>n.trim()).find(Boolean);return t===void 0?null:t.slice(0,4e3)}export function terminalOutcome(e,t,n,i,o){const r=Date.now();return{durationMs:Math.max(0,r-n),evidence:i,failure:o,finishedAtMs:r,startedAtMs:n,status:t,taskId:e}}export function processOutputEvidence(e){return{artifacts:[],logs:[...e.stdout.length===0?[]:[{stream:"stdout",text:e.stdout}],...e.stderr.length===0?[]:[{stream:"stderr",text:e.stderr}]],metrics:[]}}export function emptyEvidence(){return{artifacts:[],logs:[],metrics:[]}}export function failureFromError(e,t){const n=toError(e);return{code:t,message:n.message,...n.stack===void 0?{}:{stack:n.stack}}}export function errorDetails(e){return{message:e.message,name:e.name,...e.stack===void 0?{}:{stack:e.stack}}}export function toError(e){return e instanceof Error?e:new Error(String(e))}

package/dist/engines/adapters/native-report.d.ts

@@ -0,0 +1,25 @@
+export interface NativeReportIdentity {
+    readonly engineId: "node-vitest" | "playwright";
+    readonly invocationId: string;
+    readonly taskId: string;
+    readonly sourceFile: string;
+}
+export interface NativeReport extends NativeReportIdentity {
+    readonly schemaVersion: 1;
+    readonly result: unknown;
+}
+export interface NativeReportOptions {
+    readonly identity: NativeReportIdentity;
+    readonly reportFile: string;
+    readonly workspaceDirectory: string;
+}
+export declare const NATIVE_REPORT_JSON_BOUNDS: Readonly<{
+    maxCollectionEntries: 100000;
+    maxDepth: 64;
+    maxNodes: 100000;
+    maxStringUnits: number;
+}>;
+export declare function writeNativeReport(options: Readonly<NativeReportOptions>, result: unknown, maximumBytes: number): Promise<void>;
+export declare function readNativeReport(value: unknown, expected: Readonly<NativeReportIdentity>): NativeReport;
+export declare function nativeReporterFile(engineId: NativeReportIdentity["engineId"]): string;
+export declare function requireNativeEvidenceJson(value: unknown, label: string): void;

package/dist/engines/adapters/native-report.js

@@ -0,0 +1 @@
+import n from"node:fs/promises";import a from"node:path";import{fileURLToPath as p}from"node:url";import{requireBoundedJsonValue as u,serializeBoundedJson as w}from"../contracts/json-bounds.js";export const NATIVE_REPORT_JSON_BOUNDS=Object.freeze({maxCollectionEntries:1e5,maxDepth:64,maxNodes:1e5,maxStringUnits:1024*1024});export async function writeNativeReport(t,e,r){const o=await n.realpath(t.workspaceDirectory),c=await n.realpath(a.dirname(t.reportFile));if(o!==a.resolve(t.workspaceDirectory)||c!==o)throw new Error("Native report must stay in its invocation workspace");const s=w({schemaVersion:1,...t.identity,result:e},"Testkit native report",NATIVE_REPORT_JSON_BOUNDS,{unitLabel:"bytes",unitsOf:f=>Buffer.byteLength(f,"utf8")});if(Buffer.byteLength(s,"utf8")>r)throw new Error(`Testkit native report exceeds ${r.toString()} bytes`);const i=await n.open(t.reportFile,"wx",384);try{await i.writeFile(s,"utf8"),await i.sync()}finally{await i.close()}}export function readNativeReport(t,e){if(typeof t!="object"||t===null||Array.isArray(t))throw new Error("Testkit native report must contain an object");const r=t;if(r.schemaVersion!==1)throw new Error("Unsupported Testkit native report schemaVersion");for(const o of["engineId","invocationId","taskId","sourceFile"])if(r[o]!==e[o])throw new Error(`Testkit native report ${o} does not match its invocation`);return{schemaVersion:1,...e,result:r.result}}export function nativeReporterFile(t){const e=p(new URL("../../../",import.meta.url));return a.join(e,"dist","engines",t,"adapter","reporter.js")}export function requireNativeEvidenceJson(t,e){u(t,e,NATIVE_REPORT_JSON_BOUNDS,{unitLabel:"bytes",unitsOf:r=>Buffer.byteLength(r,"utf8")})}

package/dist/engines/adapters/workspace.d.ts

@@ -0,0 +1,4 @@
+export declare function requireRootDirectory(rootDirectory: string): Promise<string>;
+export declare function requireAbsoluteWorkspacePath(value: string, label: string): void;
+export declare function requireConsumerFile(rootDirectory: string, file: string, label: string): Promise<string>;
+export declare function safeSegment(value: string): string;

package/dist/engines/adapters/workspace.js

@@ -0,0 +1 @@
+import n from"node:crypto";import r from"node:fs/promises";import s from"node:path";import{isPathWithin as c}from"../../process/files/paths.js";export async function requireRootDirectory(t){requireAbsoluteWorkspacePath(t,"root directory");const e=await r.realpath(t);if(!(await r.stat(e)).isDirectory())throw new Error("Engine execution root directory must be a directory");return e}export function requireAbsoluteWorkspacePath(t,e){if(!s.isAbsolute(t))throw new Error(`Engine execution ${e} must be absolute`)}export async function requireConsumerFile(t,e,o){const a=s.resolve(t,e),i=await r.realpath(a);if(!c(t,i))throw new Error(`${o} must stay within the consumer root`);if(!(await r.stat(i)).isFile())throw new Error(`${o} must be a regular file`);return i}export function safeSegment(t){const e=t.trim().toLowerCase().replace(/[^a-z0-9._-]+/gu,"-").replace(/^-+|-+$/gu,"").slice(0,80);return e.length>0?e:n.createHash("sha256").update(t).digest("hex").slice(0,16)}

package/dist/engines/api/capabilities.d.ts

@@ -0,0 +1,31 @@
+import type { EngineId, PublicTestType } from "../../domain/identifiers.js";
+export declare const EXECUTION_REQUIREMENTS: readonly ["none", "optional", "required"];
+export type ExecutionRequirement = (typeof EXECUTION_REQUIREMENTS)[number];
+export declare const ENDPOINT_ACCESS_MODES: readonly ["none", "published-http"];
+export type EndpointAccessMode = (typeof ENDPOINT_ACCESS_MODES)[number];
+export declare const ENGINE_EXECUTION_HOSTS: readonly ["orchestrator", "kiln-job"];
+export type EngineExecutionHost = (typeof ENGINE_EXECUTION_HOSTS)[number];
+export declare const TASK_BATCHING_MODES: readonly ["isolated", "compatible"];
+export type TaskBatchingMode = (typeof TASK_BATCHING_MODES)[number];
+export declare const RUNTIME_ISOLATION_CAPABILITIES: readonly ["none", "orchestrated"];
+export type RuntimeIsolationCapability = (typeof RUNTIME_ISOLATION_CAPABILITIES)[number];
+export interface RunnerProfileCapabilities {
+    readonly applicationRuntime: ExecutionRequirement;
+    readonly databaseRuntime: ExecutionRequirement;
+    readonly endpointAccess: EndpointAccessMode;
+    readonly executionHost: EngineExecutionHost;
+    readonly runtimeIsolation: RuntimeIsolationCapability;
+    readonly taskBatching: TaskBatchingMode;
+}
+interface RunnerProfileIdsByEngine {
+    k6: "k6-dal" | "k6-http";
+    "node-vitest": "node-vitest-contract" | "node-vitest-data";
+    playwright: "playwright-ui";
+}
+export interface RunnerProfileDescriptor<Id extends EngineId = EngineId> {
+    readonly capabilities: RunnerProfileCapabilities;
+    readonly engineId: Id;
+    readonly id: RunnerProfileIdsByEngine[Id];
+    readonly supportedTestTypes: readonly PublicTestType[];
+}
+export {};

package/dist/engines/api/capabilities.js

@@ -0,0 +1 @@
+export const EXECUTION_REQUIREMENTS=Object.freeze(["none","optional","required"]),ENDPOINT_ACCESS_MODES=Object.freeze(["none","published-http"]),ENGINE_EXECUTION_HOSTS=Object.freeze(["orchestrator","kiln-job"]),TASK_BATCHING_MODES=Object.freeze(["isolated","compatible"]),RUNTIME_ISOLATION_CAPABILITIES=Object.freeze(["none","orchestrated"]);

package/dist/engines/api/evidence.d.ts

@@ -0,0 +1,38 @@
+export type EngineJsonPrimitive = boolean | null | number | string;
+export type EngineJsonValue = EngineJsonPrimitive | readonly EngineJsonValue[] | EngineJsonObject;
+export interface EngineJsonObject {
+    readonly [key: string]: EngineJsonValue;
+}
+export interface EngineArtifactEvidence {
+    readonly contentType?: string;
+    readonly data?: EngineJsonValue;
+    readonly kind: string;
+    readonly metadata?: EngineJsonObject;
+    readonly name: string;
+    readonly path: string;
+    readonly summary?: string;
+}
+export interface EngineLogEvidence {
+    readonly stream: "engine" | "stderr" | "stdout";
+    readonly text: string;
+}
+export interface EngineMetricEvidence {
+    readonly dimensions?: EngineJsonObject;
+    readonly name: string;
+    readonly unit?: string;
+    readonly value: number;
+}
+export interface EngineEvidence {
+    readonly artifacts: readonly EngineArtifactEvidence[];
+    readonly logs: readonly EngineLogEvidence[];
+    readonly metrics: readonly EngineMetricEvidence[];
+    readonly native?: EngineJsonObject;
+}
+export type EngineFailureClassification = "infra" | "product";
+export interface EngineFailureEvidence {
+    readonly classification?: EngineFailureClassification;
+    readonly code?: string;
+    readonly details?: EngineJsonObject;
+    readonly message: string;
+    readonly stack?: string;
+}

package/dist/engines/api/evidence.js

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

package/dist/engines/api/execution-observer.d.ts

@@ -0,0 +1,8 @@
+import type { EngineExecutionObserver, EngineExecutionRequest } from "./execution.js";
+export interface ValidatingObserverSession {
+    readonly assertValid: () => void;
+    readonly close: () => void;
+    readonly commit: () => void;
+    readonly observer: EngineExecutionObserver;
+}
+export declare function createValidatingObserverSession(request: EngineExecutionRequest): ValidatingObserverSession | null;

package/dist/engines/api/execution-observer.js

@@ -0,0 +1 @@
+export function createValidatingObserverSession(c){const s=c.observer;if(s===void 0)return null;const d=new Map(c.tasks.map(e=>[e.id,e])),n=new Set,o=new Set;let h=!1,l=!1,$,a=!1;const i=[],w=e=>{if(h)throw new Error(`${e} was emitted after engine execution closed`)},E=Object.freeze({evidenceRecorded(e,r){f(()=>{const t="Engine observer evidenceRecorded";if(w(t),e!==null){if(!d.has(e))throw new Error(`${t} refers to unknown task ${e}`);if(o.has(e))throw new Error(`${t} was emitted after taskFinished for ${e}`);if(!n.has(e))throw new Error(`${t} was emitted before taskStarted for ${e}`)}i.push(()=>{s.evidenceRecorded(e,r)})})},taskFinished(e){f(()=>{const r="Engine observer taskFinished";if(w(r),!d.has(e.taskId))throw new Error(`${r} refers to unknown task ${e.taskId}`);if(o.has(e.taskId))throw new Error(`${r} was emitted twice for task ${e.taskId}`);if(!n.has(e.taskId))throw new Error(`${r} was emitted before taskStarted for ${e.taskId}`);o.add(e.taskId);const t=Object.freeze({...e});i.push(()=>{s.taskFinished(t)})})},taskStarted(e){f(()=>{const r="Engine observer taskStarted";w(r);const t=d.get(e.id);if(t===void 0)throw new Error(`${r} refers to unknown task ${e.id}`);if(e!==t)throw new Error(`${r} does not match requested task ${e.id}`);if(o.has(e.id))throw new Error(`${r} was emitted after taskFinished for ${e.id}`);if(n.has(e.id))throw new Error(`${r} was emitted twice for task ${e.id}`);n.add(e.id),i.push(()=>{s.taskStarted(e)})})}}),f=e=>{try{e()}catch(r){throw a||(a=!0,$=r),r}};return Object.freeze({assertValid(){if(a)throw $},close(){h=!0},commit(){if(l)throw new Error("Engine observer event stream was committed twice");l=!0;const e=i.splice(0);for(const r of e)r()},observer:E})}

package/dist/engines/api/execution-scope.d.ts

@@ -0,0 +1,17 @@
+export type EngineInvocationCleanup = () => Promise<void> | void;
+export interface EngineInvocationScope {
+    defer(cleanup: EngineInvocationCleanup): void;
+}
+export interface EngineInvocationScopeController {
+    drain(): Promise<readonly Error[]>;
+    readonly scope: EngineInvocationScope;
+}
+interface EngineInvocationScopeOptions {
+    readonly timeoutMs: number;
+}
+export declare class EngineInvocationCleanupDeadlineExceededError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare function createEngineInvocationScope(options: EngineInvocationScopeOptions): EngineInvocationScopeController;
+export {};

package/dist/engines/api/execution-scope.js

@@ -0,0 +1 @@
+export class EngineInvocationCleanupDeadlineExceededError extends Error{timeoutMs;constructor(n){super(`Engine invocation cleanup exceeded its independent ${n.toString()} ms deadline`),this.name="EngineInvocationCleanupDeadlineExceededError",this.timeoutMs=n}}export function createEngineInvocationScope(t){const n=[];let i=!0,e=null;const s=Object.freeze({defer(r){if(!i)throw new Error("Engine invocation cleanup cannot be registered after draining starts");n.push(r)}});return Object.freeze({drain(){return e!==null||(i=!1,e=l(n.splice(0).reverse(),t.timeoutMs)),e},scope:s})}async function l(t,n){const i=Date.now()+n,e=[];for(const s of t){let r;try{r=s()}catch(u){e.push(a(u));continue}if(r===void 0)continue;const o=Math.max(0,i-Date.now());if(o===0){Promise.resolve(r).catch(()=>{}),e.push(new EngineInvocationCleanupDeadlineExceededError(n));continue}const c=await d(r,o);c==="timeout"?e.push(new EngineInvocationCleanupDeadlineExceededError(n)):c instanceof Error&&e.push(c)}return Object.freeze(e)}async function d(t,n){let i;const e=Promise.resolve(t).then(()=>"fulfilled",o=>a(o)),s=new Promise(o=>{i=setTimeout(()=>{o("timeout")},n)}),r=await Promise.race([e,s]);return clearTimeout(i),r}function a(t){return t instanceof Error?t:new Error(String(t))}

package/dist/engines/api/execution.d.ts

@@ -0,0 +1,99 @@
+import type { TestOutcomeStatus } from "../../domain/test-outcomes.js";
+import type { RunnerProfileDescriptor } from "./capabilities.js";
+import type { EngineEvidence, EngineFailureEvidence, EngineJsonObject, EngineJsonValue } from "./evidence.js";
+import type { EngineInvocationScope } from "./execution-scope.js";
+import type { EngineId, PublicTestType } from "../../domain/identifiers.js";
+export declare const ENGINE_TASK_DEADLINE_EXCEEDED_CODE: "TESTKIT_ENGINE_TASK_DEADLINE_EXCEEDED";
+export declare class EngineTaskDeadlineExceededError extends Error {
+    readonly code: "TESTKIT_ENGINE_TASK_DEADLINE_EXCEEDED";
+    readonly deadlineMs: number;
+    constructor(deadlineMs: number);
+}
+export declare const ENGINE_PROTOCOL_LIMITS: Readonly<{
+    cleanupTimeoutMs: 30000;
+}>;
+export interface EngineCancellationSignal {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: "abort", listener: () => void, options?: Readonly<{
+        once?: boolean;
+    }>): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+export declare function isEngineTaskDeadlineExceededReason(value: unknown): value is Readonly<{
+    code: typeof ENGINE_TASK_DEADLINE_EXCEEDED_CODE;
+    deadlineMs: number;
+}>;
+export interface EngineExecutionTask {
+    readonly deadlineMs: number;
+    readonly file: string;
+    readonly id: string;
+    readonly inputs: EngineExecutionInputs;
+    readonly orchestration: EngineTaskOrchestration;
+    readonly serviceName: string;
+    readonly suiteName: string;
+    readonly testType: PublicTestType;
+    readonly timeoutMs: number;
+}
+export interface EngineTaskOrchestration {
+    readonly lease: EngineTaskLeaseIdentity;
+    readonly mode: string;
+    readonly runtimeId?: string;
+}
+export interface EngineTaskLeaseIdentity {
+    readonly directory: string;
+    readonly id: string;
+}
+export interface EngineExecutionInputs {
+    readonly configuration?: EngineJsonObject;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly fixtures: Readonly<Record<string, EngineJsonValue>>;
+    readonly setupData?: EngineJsonValue;
+    readonly supportModules: Readonly<Record<string, string>>;
+}
+export interface EngineExecutionTarget {
+    readonly endpoints: Readonly<Record<string, string>>;
+    readonly inputs: EngineExecutionInputs;
+}
+export interface EngineExecutionWorkspace {
+    readonly artifactDirectory: string;
+    readonly rootDirectory: string;
+    readonly temporaryDirectory: string;
+}
+export interface EngineExecutionObserver {
+    evidenceRecorded(taskId: null | string, evidence: EngineEvidence): void;
+    taskFinished(outcome: EngineTaskOutcome): void;
+    taskStarted(task: EngineExecutionTask): void;
+}
+export interface EngineExecutionRequest<Id extends EngineId = EngineId> {
+    readonly invocationId: string;
+    readonly observer?: EngineExecutionObserver;
+    readonly profile: RunnerProfileDescriptor<Id>;
+    readonly signal: EngineCancellationSignal;
+    readonly target: EngineExecutionTarget;
+    readonly tasks: readonly EngineExecutionTask[];
+    readonly workspace: EngineExecutionWorkspace;
+}
+export declare function resolveEngineTaskInputs(request: Pick<EngineExecutionRequest, "target">, task: Pick<EngineExecutionTask, "inputs">): EngineExecutionInputs;
+export interface EngineTaskOutcome {
+    readonly durationMs: number;
+    readonly evidence: EngineEvidence;
+    readonly failure: EngineFailureEvidence | null;
+    readonly finishedAtMs: number;
+    readonly startedAtMs: number;
+    readonly status: TestOutcomeStatus;
+    readonly taskId: string;
+}
+export interface EngineExecutionResult {
+    readonly evidence: EngineEvidence;
+    readonly invocationId: string;
+    readonly outcomes: readonly EngineTaskOutcome[];
+}
+export type EngineExecutor<Installation> = (request: Readonly<EngineExecutionRequest>, installation: Readonly<Installation>, scope: EngineInvocationScope) => Promise<EngineExecutionResult>;
+export interface EngineExecutionBoundary<Id extends EngineId = EngineId> {
+    readonly request: Readonly<EngineExecutionRequest<Id>>;
+    acceptResult(value: EngineExecutionResult): EngineExecutionResult;
+    close(): void;
+    commit(): void;
+}
+export declare function beginEngineExecution<Id extends EngineId>(request: Readonly<EngineExecutionRequest<Id>>): EngineExecutionBoundary<Id>;

package/dist/engines/api/execution.js

@@ -0,0 +1 @@
+import{createValidatingObserverSession as u}from"./execution-observer.js";export const ENGINE_TASK_DEADLINE_EXCEEDED_CODE="TESTKIT_ENGINE_TASK_DEADLINE_EXCEEDED";export class EngineTaskDeadlineExceededError extends Error{code=ENGINE_TASK_DEADLINE_EXCEEDED_CODE;deadlineMs;constructor(n){super(`Engine task deadline ${n.toString()} was exceeded`),this.name="EngineTaskDeadlineExceededError",this.deadlineMs=n}}export const ENGINE_PROTOCOL_LIMITS=Object.freeze({cleanupTimeoutMs:3e4});export function isEngineTaskDeadlineExceededReason(e){return typeof e=="object"&&e!==null&&Reflect.get(e,"code")===ENGINE_TASK_DEADLINE_EXCEEDED_CODE&&typeof Reflect.get(e,"deadlineMs")=="number"&&Number.isSafeInteger(Reflect.get(e,"deadlineMs"))&&Number(Reflect.get(e,"deadlineMs"))>0}export function resolveEngineTaskInputs(e,n){const r=e.target.inputs,t=n.inputs;return Object.freeze({...t.configuration!==void 0?{configuration:t.configuration}:r.configuration!==void 0?{configuration:r.configuration}:{},environment:Object.freeze({...r.environment,...t.environment}),fixtures:Object.freeze({...r.fixtures,...t.fixtures}),...t.setupData!==void 0?{setupData:t.setupData}:r.setupData!==void 0?{setupData:r.setupData}:{},supportModules:Object.freeze({...r.supportModules,...t.supportModules})})}export function beginEngineExecution(e){const n=u(e),r=Object.freeze({...e,...n===null?{}:{observer:n.observer}});let t=null,o=!1,i=!1;return Object.freeze({request:r,acceptResult(s){if(o)throw new Error("Engine execution boundary is already closed");if(t!==null)throw new Error("Engine execution boundary already accepted a result");return n?.assertValid(),t=s,t},close(){o||(n?.close(),o=!0)},commit(){if(!o)throw new Error("Engine execution boundary must be closed before it is committed");if(i)throw new Error("Engine execution boundary is already committed");if(t===null)throw new Error("Engine execution boundary cannot commit without an accepted result");n?.assertValid(),n?.commit(),i=!0}})}

package/dist/engines/api/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./capabilities.js";
+export * from "./evidence.js";
+export * from "./execution.js";
+export { EngineInvocationCleanupDeadlineExceededError, createEngineInvocationScope, type EngineInvocationCleanup, type EngineInvocationScope, type EngineInvocationScopeController, } from "./execution-scope.js";
+export { ENGINE_RUNTIME_ARTIFACT_MARKER, type EngineRuntimeArtifactPayload, encodeEngineRuntimeArtifactPayload, findEncodedEngineRuntimeArtifacts, normalizeEngineJsonValue, } from "./runtime-artifact.js";

package/dist/engines/api/index.js

@@ -0,0 +1 @@
+export*from"./capabilities.js";export*from"./evidence.js";export*from"./execution.js";export{EngineInvocationCleanupDeadlineExceededError,createEngineInvocationScope}from"./execution-scope.js";export{ENGINE_RUNTIME_ARTIFACT_MARKER,encodeEngineRuntimeArtifactPayload,findEncodedEngineRuntimeArtifacts,normalizeEngineJsonValue}from"./runtime-artifact.js";

package/dist/engines/api/k6-runtime-input.d.ts

@@ -0,0 +1,26 @@
+import type { EngineJsonObject, EngineJsonValue } from "./evidence.js";
+export declare const K6_RUNTIME_INPUT_VERSION: 1;
+export declare const K6_RUNTIME_INPUT_FILE_ENV = "TESTKIT_K6_INPUT_FILE";
+export declare const K6_RUNTIME_INPUT_SHA256_ENV = "TESTKIT_K6_INPUT_SHA256";
+export declare const K6_RUNTIME_INVOCATION_ID_ENV = "TESTKIT_INVOCATION_ID";
+export declare const K6_RUNTIME_TASK_ID_ENV = "TESTKIT_TEST_ID";
+export declare const K6_RUNTIME_INPUT_MAX_CHARACTERS: number;
+export interface K6RuntimeInputDocument {
+    readonly engineId: "k6";
+    readonly fixtures: EngineJsonObject;
+    readonly invocationId: string;
+    readonly setupData?: EngineJsonValue;
+    readonly taskId: string;
+    readonly version: typeof K6_RUNTIME_INPUT_VERSION;
+}
+export interface K6RuntimeInputReaderBoundary {
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    openText(file: string): unknown;
+    sha256Hex(contents: string): string;
+}
+/**
+ * Reads and validates the k6 wire document without importing either Node or k6
+ * globals. The Sobek runtime supplies those capabilities at its outer edge.
+ */
+export declare function readK6RuntimeInput(boundary: Readonly<K6RuntimeInputReaderBoundary>): K6RuntimeInputDocument | null;
+export declare function parseK6RuntimeInputDocument(value: unknown, label?: string): K6RuntimeInputDocument;

package/dist/engines/api/k6-runtime-input.js

@@ -0,0 +1 @@
+import{CHARACTER_JSON_STRING_MEASURE as E,requireBoundedJsonValue as _,RUNTIME_INPUT_JSON_BOUNDS as f}from"../contracts/json-bounds.js";export const K6_RUNTIME_INPUT_VERSION=1,K6_RUNTIME_INPUT_FILE_ENV="TESTKIT_K6_INPUT_FILE",K6_RUNTIME_INPUT_SHA256_ENV="TESTKIT_K6_INPUT_SHA256",K6_RUNTIME_INVOCATION_ID_ENV="TESTKIT_INVOCATION_ID",K6_RUNTIME_TASK_ID_ENV="TESTKIT_TEST_ID",K6_RUNTIME_INPUT_MAX_CHARACTERS=8*1024*1024;const T=/^[a-f0-9]{64}$/u;export function readK6RuntimeInput(t){const n=t.environment[K6_RUNTIME_INPUT_FILE_ENV],e=t.environment[K6_RUNTIME_INPUT_SHA256_ENV];if(!n&&!e)return null;if(!w(n))throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} must be an absolute owned path`);if(!e||!T.test(e))throw new Error(`${K6_RUNTIME_INPUT_SHA256_ENV} must be a lowercase SHA-256 digest`);const r=t.openText(n);if(typeof r!="string")throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} must contain UTF-8 JSON text`);if(r.length>K6_RUNTIME_INPUT_MAX_CHARACTERS)throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} exceeds the ${String(K6_RUNTIME_INPUT_MAX_CHARACTERS)} character limit`);if(t.sha256Hex(r)!==e)throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} integrity check failed`);let i;try{i=JSON.parse(r)}catch(s){throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} contains invalid JSON: ${N(s)}`,{cause:s})}const o=parseK6RuntimeInputDocument(i,K6_RUNTIME_INPUT_FILE_ENV);if(o.invocationId!==t.environment[K6_RUNTIME_INVOCATION_ID_ENV])throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} invocation identity does not match`);if(o.taskId!==t.environment[K6_RUNTIME_TASK_ID_ENV])throw new Error(`${K6_RUNTIME_INPUT_FILE_ENV} task identity does not match`);return o}export function parseK6RuntimeInputDocument(t,n="k6 runtime input"){if(_(t,n,f,E),!I(t))throw new Error(`${n} must contain an object`);const e=new Set(["engineId","fixtures","invocationId","setupData","taskId","version"]);for(const r of Object.keys(t))if(!e.has(r))throw new Error(`${n} contains unknown field ${r}`);if(t.version!==K6_RUNTIME_INPUT_VERSION)throw new Error(`${n}.version must be 1`);if(t.engineId!=="k6")throw new Error(`${n}.engineId must be "k6"`);if(!I(t.fixtures))throw new Error(`${n}.fixtures must be an object`);return{engineId:"k6",fixtures:t.fixtures,invocationId:c(t.invocationId,`${n}.invocationId`),...Object.hasOwn(t,"setupData")?{setupData:t.setupData}:{},taskId:c(t.taskId,`${n}.taskId`),version:K6_RUNTIME_INPUT_VERSION}}function c(t,n){if(typeof t!="string"||t.length===0)throw new Error(`${n} must be a non-empty string`);return t}function w(t){return typeof t=="string"&&(t.startsWith("/")||/^[a-z]:[\\/]/iu.test(t)||t.startsWith("\\\\"))}function I(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function N(t){return t instanceof Error?t.message:String(t)}

package/dist/engines/api/runtime-artifact.d.ts

@@ -0,0 +1,19 @@
+import type { EngineJsonValue } from "./evidence.js";
+export declare const ENGINE_RUNTIME_ARTIFACT_MARKER: "TESTKIT_ARTIFACT:";
+export declare const MAX_ENGINE_RUNTIME_ARTIFACT_BYTES: number;
+export declare const MAX_ENGINE_RUNTIME_ARTIFACT_DEPTH = 64;
+export declare const MAX_ENGINE_RUNTIME_ARTIFACT_NODES = 100000;
+export declare const MAX_ENCODED_ENGINE_RUNTIME_ARTIFACT_BYTES: number;
+export interface EngineRuntimeArtifactPayload {
+    readonly contentType: string;
+    readonly data: EngineJsonValue;
+    readonly emittedAt: string;
+    readonly kind: null | string;
+    readonly name: string;
+    readonly summary: null | string;
+}
+export declare function normalizeEngineRuntimeArtifactPayload(value: unknown): EngineRuntimeArtifactPayload;
+export declare function encodeEngineRuntimeArtifactPayload(value: unknown): string;
+export declare function decodeEngineRuntimeArtifactPayload(encodedPayload: unknown): EngineRuntimeArtifactPayload;
+export declare function findEncodedEngineRuntimeArtifacts(output: string): readonly string[];
+export declare function normalizeEngineJsonValue(value: unknown, label?: string): EngineJsonValue;

package/dist/engines/api/runtime-artifact.js

@@ -0,0 +1 @@
+export const ENGINE_RUNTIME_ARTIFACT_MARKER="TESTKIT_ARTIFACT:",MAX_ENGINE_RUNTIME_ARTIFACT_BYTES=1048576,MAX_ENGINE_RUNTIME_ARTIFACT_DEPTH=64,MAX_ENGINE_RUNTIME_ARTIFACT_NODES=1e5,MAX_ENCODED_ENGINE_RUNTIME_ARTIFACT_BYTES=4194304;export function normalizeEngineRuntimeArtifactPayload(t){const e=m(t,"Engine runtime artifact");N(e,["contentType","data","emittedAt","kind","name","summary"]);const n={contentType:c(e.contentType,"Engine runtime artifact.contentType",200),data:normalizeEngineJsonValue(e.data,"Engine runtime artifact data"),emittedAt:A(e.emittedAt),kind:T(e.kind,"Engine runtime artifact.kind",200),name:c(e.name,"Engine runtime artifact.name",200),summary:T(e.summary,"Engine runtime artifact.summary",4096)},r=JSON.stringify(n);if(a(r)>1048576)throw new Error("Engine runtime artifact exceeds 1048576 bytes");return Object.freeze(n)}export function encodeEngineRuntimeArtifactPayload(t){const e=encodeURIComponent(JSON.stringify(normalizeEngineRuntimeArtifactPayload(t)));if(a(e)>4194304)throw new Error("Encoded engine runtime artifact exceeds 4194304 bytes");return e}export function decodeEngineRuntimeArtifactPayload(t){if(typeof t!="string"||t.length===0)throw new Error("Encoded engine runtime artifact must be a non-empty string");if(a(t)>4194304)throw new Error("Encoded engine runtime artifact exceeds 4194304 bytes");let e;try{e=decodeURIComponent(t)}catch(r){throw new Error("Encoded engine runtime artifact is not valid URI data",{cause:r})}let n;try{n=JSON.parse(e)}catch(r){throw new Error("Encoded engine runtime artifact is not valid JSON",{cause:r})}return normalizeEngineRuntimeArtifactPayload(n)}export function findEncodedEngineRuntimeArtifacts(t){const e=[];let n=0;for(;n<t.length;){const r=t.indexOf(ENGINE_RUNTIME_ARTIFACT_MARKER,n);if(r<0)break;const i=r+ENGINE_RUNTIME_ARTIFACT_MARKER.length;let o=i;for(;o<t.length&&!I(t.charCodeAt(o));)o+=1;e.push(t.slice(i,o)),n=Math.max(o,i+1)}return Object.freeze(e)}export function normalizeEngineJsonValue(t,e="Engine JSON value"){return s(t,e,"$",0,new Set,{nodes:0})}function s(t,e,n,r,i,o){if(o.nodes+=1,o.nodes>1e5)throw new Error(`${e} exceeds 100000 JSON nodes`);if(r>64)throw new Error(`${e} exceeds depth 64 at ${n}`);if(t===null||typeof t=="string"||typeof t=="boolean")return t;if(typeof t=="number"){if(!Number.isFinite(t))throw new Error(`${e} ${n} must be finite`);return t}if(typeof t!="object")throw new Error(`${e} ${n} is not a JSON value`);if(i.has(t))throw new Error(`${e} contains a cycle at ${n}`);i.add(t);try{if(Array.isArray(t))return Object.freeze(t.map((E,f)=>s(E,e,`${n}[${f.toString()}]`,r+1,i,o)));const d=Object.getPrototypeOf(t);if(d!==Object.prototype&&d!==null)throw new Error(`${e} ${n} must be a plain JSON object`);const _={};for(const[E,f]of Object.entries(t))_[E]=s(f,e,`${n}.${E}`,r+1,i,o);return Object.freeze(_)}finally{i.delete(t)}}function A(t){const e=c(t,"Engine runtime artifact.emittedAt",100);if(!Number.isFinite(Date.parse(e)))throw new Error("Engine runtime artifact.emittedAt must be a timestamp");return e}function T(t,e,n){return t===null?null:c(t,e,n)}function c(t,e,n){if(typeof t!="string"||t.trim().length===0)throw new Error(`${e} must be a non-empty string`);if(t.length>n)throw new Error(`${e} exceeds ${n.toString()} characters`);return t.trim()}function N(t,e){const n=new Set(e),r=Object.keys(t).find(i=>!n.has(i));if(r!==void 0)throw new Error(`Engine runtime artifact contains unexpected field ${r}`);for(const i of e)if(!Object.hasOwn(t,i))throw new Error(`Engine runtime artifact is missing field ${i}`)}function m(t,e){if(typeof t!="object"||t===null||Array.isArray(t))throw new Error(`${e} must be an object`);return t}function I(t){return t===34||t===9||t===10||t===13||t===32}function a(t){let e=0;for(let n=0;n<t.length;n+=1){const r=t.charCodeAt(n);if(r<128)e+=1;else if(r<2048)e+=2;else if(r>=55296&&r<=56319){const i=t.charCodeAt(n+1);i>=56320&&i<=57343?(n+=1,e+=4):e+=3}else e+=3}return e}

package/dist/engines/bundle-cache.d.ts

@@ -0,0 +1,32 @@
+export type BundleSourcemapStatus = "detected" | "none" | "not-detected-in-sample" | "present";
+export interface BundleCacheStatus {
+    duplicatedSourceCount: number;
+    entryFileCount: number;
+    exists: boolean;
+    fileCount: number;
+    jsFileCount: number;
+    manifest: {
+        entryCount: number;
+        exists: boolean;
+    };
+    path: string;
+    serviceName: string;
+    sizeBytes: number;
+    sourcemapFileCount: null | number;
+    sourcemapStatus: BundleSourcemapStatus;
+    sourceFileCount: number;
+    unmanagedFileCount: number;
+}
+export interface BundleCleanupTarget {
+    path: string;
+    reason: "stale-bundle-version";
+    serviceName: string;
+    sourceFile: null | string;
+}
+export declare function collectBundleCacheStatus(productDir: string, serviceName?: string): BundleCacheStatus;
+export declare function collectBundleCleanupTargets(productDir: string, { allConfigs, serviceName, }?: Readonly<{
+    allConfigs?: readonly {
+        readonly name: string;
+    }[];
+    serviceName?: null | string;
+}>): BundleCleanupTarget[];

package/dist/engines/bundle-cache.js

@@ -0,0 +1 @@
+import p from"fs";import c from"path";import{collectDirectorySummary as E,listFiles as g}from"../process/files/directory-status.js";const S="manifest.json",M=10080*60*1e3;export function collectBundleCacheStatus(t,e="shared"){const n=c.join(t,".testkit","_bundles",e||"shared"),s=E(n),r=g(n),o=r.filter(a=>a.path.endsWith(".js")),u=r.filter(a=>a.path.endsWith(".entry.mjs")),l=C(n),i=new Set(l.entries.flatMap(a=>[a.outputFile,a.entryFile].filter(m).map(x=>c.resolve(x)))),f=D(u),h=[...f.values()].filter(a=>a.length>1).length,d=r.filter(a=>c.basename(a.path)!==S&&!i.has(c.resolve(a.path))),F=w(o,l);return{serviceName:e,path:n,exists:s.exists,sizeBytes:s.sizeBytes,fileCount:s.fileCount,jsFileCount:o.length,entryFileCount:u.length,sourceFileCount:f.size||l.sourceFileCount,duplicatedSourceCount:h,sourcemapFileCount:F.count,sourcemapStatus:F.status,manifest:{exists:l.exists,entryCount:l.entries.length},unmanagedFileCount:d.length}}export function collectBundleCleanupTargets(t,{allConfigs:e=[],serviceName:n=null}={}){const s=n?[n]:e.map(o=>o.name).sort(),r=[];for(const o of s){const u=c.join(t,".testkit","_bundles",o||"shared");if(g(u).length===0)continue;const i=C(u),f=N(u,i.entries);r.push(...f.map(h=>({...h,serviceName:o})))}return _(r)}function C(t){const e=c.join(t,S);if(!p.existsSync(e))return{exists:!1,entries:[],sourceFileCount:0};try{const n=JSON.parse(p.readFileSync(e,"utf8")),s=b(n);return{exists:!0,entries:s,sourceFileCount:new Set(s.map(r=>r.sourceFile).filter(m)).size}}catch{return{exists:!0,entries:[],sourceFileCount:0}}}function b(t){return!A(t)||!Array.isArray(t.entries)?[]:t.entries.map(j).filter(e=>e!==null)}function j(t){if(!A(t))return null;const e={hasSourcemap:!!t.hasSourcemap};return typeof t.cacheKey=="string"&&(e.cacheKey=t.cacheKey),typeof t.createdAt=="string"&&(e.createdAt=t.createdAt),typeof t.entryFile=="string"&&(e.entryFile=t.entryFile),typeof t.lastUsedAt=="string"&&(e.lastUsedAt=t.lastUsedAt),typeof t.outputFile=="string"&&(e.outputFile=t.outputFile),typeof t.sourceFile=="string"&&(e.sourceFile=t.sourceFile),e}function D(t){const e=new Map;for(const n of t){const s=P(n.path);if(!s)continue;const r=e.get(s)||[];r.push(n),e.set(s,r)}return e}function P(t){try{const n=p.readFileSync(t,"utf8").match(/import \* as suiteModule from ("(?:\\.|[^"])+");/);if(!n)return null;const s=JSON.parse(n[1]);return typeof s=="string"?s:null}catch{return null}}function w(t,e){if(e.entries.length>0){const r=e.entries.filter(o=>o.hasSourcemap).length;return{count:r,status:r>0?"present":"none"}}const n=t.slice(0,25);return n.some(r=>T(r.path))?{count:null,status:"detected"}:{count:0,status:t.length>n.length?"not-detected-in-sample":"none"}}function T(t){try{return/sourceMappingURL=data:application\/json/.test(p.readFileSync(t,"utf8"))}catch{return!1}}function N(t,e){if(e.length===0)return[];const n=Date.now(),s=K(e,o=>o.sourceFile||o.cacheKey||o.outputFile),r=[];for(const o of s.values()){const u=[...o].sort(z),l=new Set(u.filter((i,f)=>f<2||n-y(i)<M).map(i=>i.cacheKey||i.outputFile));for(const i of u){const f=i.cacheKey||i.outputFile;if(!l.has(f))for(const h of[i.outputFile,i.entryFile].filter(m)){const d=U(t,h);d&&r.push({path:d,reason:"stale-bundle-version",sourceFile:i.sourceFile||null})}}}return r}function U(t,e){const n=c.resolve(t),s=c.resolve(n,e);if(!B(n,s))return null;const r=c.dirname(s);if(!p.existsSync(r))return s;try{const o=p.realpathSync.native(n),u=p.realpathSync.native(r);if(u!==o&&!B(o,u))return null}catch{return null}return s}function B(t,e){const n=c.relative(t,e);return!!n&&n!==".."&&!n.startsWith(`..${c.sep}`)&&!c.isAbsolute(n)}function z(t,e){return y(e)-y(t)||(t.outputFile||"").localeCompare(e.outputFile||"")}function y(t){return Date.parse(String(t.lastUsedAt||t.createdAt||0))}function K(t,e){const n=new Map;for(const s of t){const r=e(s),o=n.get(r)||[];o.push(s),n.set(r,o)}return n}function _(t){const e=new Map;for(const n of t)n.path&&e.set(c.resolve(n.path),{...n,path:c.resolve(n.path)});return[...e.values()].sort((n,s)=>n.path.localeCompare(s.path))}function A(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function m(t){return typeof t=="string"&&t.length>0}

package/dist/engines/catalog.d.ts

@@ -0,0 +1,32 @@
+import type { EngineJsonObject, RunnerProfileDescriptor } from "./api/index.js";
+import { BUILT_IN_RUNNER_PROFILES } from "./definitions.js";
+import { type EngineId, type PublicTestType, type RunnerProfileId } from "../domain/identifiers.js";
+export interface EngineProfileIdentity {
+    readonly engineId: EngineId;
+    readonly profileId: RunnerProfileId;
+    readonly testType: PublicTestType;
+}
+export interface EngineCatalog {
+    readonly profiles: readonly RunnerProfileDescriptor[];
+    profilesForTestType(testType: PublicTestType): readonly RunnerProfileDescriptor[];
+    resolve<Id extends EngineId>(testType: PublicTestType, engineId: Id): RunnerProfileDescriptor<Id>;
+}
+export declare const BUILT_IN_ENGINE_CATALOG: EngineCatalog;
+export { BUILT_IN_RUNNER_PROFILES };
+export declare function resolveEngineProfile<Id extends EngineId>(testType: PublicTestType, engineId: Id): RunnerProfileDescriptor<Id>;
+export declare function isEngineProfileIdentity(value: unknown): value is EngineProfileIdentity;
+type EngineAuthoringModule = "@gfdelarue/testkit/k6" | "@gfdelarue/testkit/node-vitest/data" | "@gfdelarue/testkit/node-vitest/contract" | "@gfdelarue/testkit/playwright";
+export interface EngineAuthoringProfile {
+    readonly engineId: EngineId;
+    readonly profileId: RunnerProfileId;
+}
+export interface ManagedPublicPackageOwner {
+    engineId: "node-vitest" | "playwright";
+    name: string;
+}
+export type EngineConfigurations = Readonly<Partial<Record<EngineId, EngineJsonObject>>>;
+export declare function buildEngineConfigurations(config: object, engineIds: ReadonlySet<EngineId>): EngineConfigurations | undefined;
+export declare function expectedEngineAuthoringModule(profileId: RunnerProfileId): EngineAuthoringModule;
+export declare function invalidEngineAuthoringImport(filePath: string, metadata: Readonly<EngineAuthoringProfile>, specifier: string, expectedModule?: EngineAuthoringModule): Error;
+export declare function requireMatchingHostImport(filePath: string, metadata: Readonly<EngineAuthoringProfile>, specifier: string): void;
+export declare function managedPublicPackageOwner(specifier: string): ManagedPublicPackageOwner | null;

package/dist/engines/catalog.js

@@ -0,0 +1 @@
+import{builtinModules as s}from"node:module";import{NODE_VITEST_PACKAGE_REQUIREMENTS as u,NODE_VITEST_PRIVATE_PACKAGE_PREFIXES as d}from"./installations/node-vitest.js";import{PLAYWRIGHT_PACKAGE_FAMILY_REQUIREMENTS as p}from"./installations/playwright.js";import{buildK6RepositoryConfiguration as f}from"./k6/adapter/repository-configuration.js";import{BUILT_IN_RUNNER_PROFILES as i}from"./definitions.js";import{isEngineId as I,isPublicTestType as l,isRunnerProfileId as c}from"../domain/identifiers.js";export const BUILT_IN_ENGINE_CATALOG=Object.freeze({profiles:i,profilesForTestType(e){return Object.freeze(i.filter(n=>n.supportedTestTypes.includes(e)))},resolve(e,n){const t=i.find(r=>r.engineId===n&&r.supportedTestTypes.includes(e));if(!t)throw new Error(`Unsupported engine/test-type pair: ${n}/${e}`);return t}});export{i as BUILT_IN_RUNNER_PROFILES};export function resolveEngineProfile(e,n){return BUILT_IN_ENGINE_CATALOG.resolve(e,n)}export function isEngineProfileIdentity(e){if(!g(e)||!l(e.testType)||!I(e.engineId)||!c(e.profileId))return!1;try{return resolveEngineProfile(e.testType,e.engineId).id===e.profileId}catch{return!1}}function g(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}const a=new Set(s.map(e=>e.replace(/^node:/u,""))),E=Object.freeze([...u.map(({packageName:e})=>Object.freeze({engineId:"node-vitest",name:e})),...p.map(({packageName:e})=>Object.freeze({engineId:"playwright",name:e}))]);export function buildEngineConfigurations(e,n){const t=n.has("k6")?f(e):void 0;return t===void 0?void 0:{k6:t}}export function expectedEngineAuthoringModule(e){switch(e){case"k6-http":case"k6-dal":return"@gfdelarue/testkit/k6";case"node-vitest-data":return"@gfdelarue/testkit/node-vitest/data";case"node-vitest-contract":return"@gfdelarue/testkit/node-vitest/contract";case"playwright-ui":return"@gfdelarue/testkit/playwright"}}export function invalidEngineAuthoringImport(e,n,t,r=expectedEngineAuthoringModule(n.profileId)){return new Error(`Invalid Testkit authoring in "${e}": ${n.engineId}/${n.profileId} may not import "${t}"; use "${r}" for this suite`)}export function requireMatchingHostImport(e,n,t){if(n.engineId==="k6"&&m(t))throw new Error(`Invalid Testkit authoring in "${e}": k6 suites may not import Node built-in module "${t}"`);if(n.engineId!=="k6"&&T(t))throw new Error(`Invalid Testkit authoring in "${e}": ${n.engineId} suites may not import k6 module "${t}"`);if(d.some(o=>t.startsWith(o)))throw new Error(`Invalid Testkit authoring in "${e}": ${n.engineId} suites may not import private Vitest implementation package "${t}"`);const r=managedPublicPackageOwner(t);if(r!==null&&r.engineId!==n.engineId)throw new Error(`Invalid Testkit authoring in "${e}": ${n.engineId} suites may not import ${r.engineId} package "${t}"`)}export function managedPublicPackageOwner(e){for(const n of E)if(e===n.name||e.startsWith(`${n.name}/`))return n;return null}function m(e){const n=e.replace(/^node:/u,"");return a.has(n)}function T(e){return e==="k6"||e.startsWith("k6/")}

package/dist/engines/contracts/fixture-manifest.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The fixture manifest that crosses every engine's runtime-input seam.
+ * The Node orchestrator builds one manifest per task
+ * (`buildRuntimeFixtureManifest`) and each guest — k6, node-vitest data,
+ * node-vitest contract — validates it with the same parser, so a manifest
+ * the host wrote can never be rejected by one guest and accepted by
+ * another.
+ */
+export interface RuntimeFixtureManifestEntry {
+    absolutePath: string;
+    aliases: string[];
+    contentType: string;
+    filename: string;
+    path: string;
+    root: string;
+    rootRelativePath: string;
+    sha256: string;
+    sizeBytes: number;
+}
+export interface RuntimeFixtureManifest {
+    entries: RuntimeFixtureManifestEntry[];
+    testFile: string;
+    version: 1;
+}
+export declare function resolveRuntimeFixtureEntry<T extends {
+    readonly aliases: readonly string[];
+    readonly path: string;
+}>(entries: readonly T[], key: string): T;
+/**
+ * Validates a manifest that arrived over a runtime-input seam and returns
+ * its entries. An empty object means "no fixtures were materialized" and
+ * yields no entries.
+ */
+export declare function parseRuntimeFixtureManifestEntries(value: unknown, label: string): RuntimeFixtureManifestEntry[];

package/dist/engines/contracts/fixture-manifest.js

@@ -0,0 +1 @@
+export function resolveRuntimeFixtureEntry(t,r){const n=t.filter(e=>e.aliases.includes(r));if(n.length===0){const e=t.map(o=>o.path).join(", ")||"none";throw new Error(`Unknown testkit fixture "${r}". Available fixtures: ${e}`)}if(n.length>1)throw new Error(`Ambiguous testkit fixture "${r}". Use one of: ${n.map(e=>e.path).join(", ")}`);return n[0]}export function parseRuntimeFixtureManifestEntries(t,r){if(s(t)&&Object.keys(t).length===0)return[];if(!s(t))throw new Error(`${r} must contain an object`);if(Reflect.get(t,"version")!==1)throw new Error(`${r}.version must be 1`);i(t,"testFile",r);const n=Reflect.get(t,"entries");if(!Array.isArray(n))throw new Error(`${r}.entries must be an array`);return n.map((e,o)=>a(e,`${r}.entries[${String(o)}]`))}function a(t,r){if(!s(t))throw new Error(`${r} must be an object`);return{absolutePath:i(t,"absolutePath",r),aliases:c(t,"aliases",r),contentType:i(t,"contentType",r),filename:i(t,"filename",r),path:i(t,"path",r),root:i(t,"root",r),rootRelativePath:i(t,"rootRelativePath",r),sha256:i(t,"sha256",r),sizeBytes:g(t,"sizeBytes",r)}}function i(t,r,n){const e=Reflect.get(t,r);if(typeof e!="string"||e.length===0)throw new Error(`${n}.${String(r)} must be a non-empty string`);return e}function c(t,r,n){const e=Reflect.get(t,r);if(!Array.isArray(e))throw new Error(`${n}.${String(r)} must be an array`);return e.map((o,f)=>{if(typeof o!="string"||o.length===0)throw new Error(`${n}.${String(r)}[${String(f)}] must be a non-empty string`);return o})}function g(t,r,n){const e=Reflect.get(t,r);if(typeof e!="number"||!Number.isSafeInteger(e)||e<0)throw new Error(`${n}.${String(r)} must be a non-negative integer`);return e}function s(t){return t!==null&&typeof t=="object"&&!Array.isArray(t)}

package/dist/engines/contracts/json-bounds.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structural bounds for JSON documents that cross a runtime-input seam.
+ * Every producer and consumer of a runtime-input document — the Node
+ * orchestrator writing it, and the k6 / node-vitest / playwright side
+ * reading it — enforces the same profile, so a document accepted on one
+ * side can never be rejected on the other.
+ */
+export interface JsonBoundsProfile {
+    readonly maxCollectionEntries: number;
+    readonly maxDepth: number;
+    readonly maxNodes: number;
+    readonly maxStringUnits: number;
+}
+/**
+ * How a realm measures string size. Hosts measure UTF-8 bytes; the k6
+ * guest has no byte-length primitive and measures UTF-16 characters.
+ * Characters never exceed bytes, so the guest bound is the looser one
+ * and a host-accepted document always passes guest validation.
+ */
+export interface JsonStringMeasure {
+    readonly unitLabel: string;
+    readonly unitsOf: (text: string) => number;
+}
+export declare const RUNTIME_INPUT_JSON_BOUNDS: JsonBoundsProfile;
+export declare const CHARACTER_JSON_STRING_MEASURE: JsonStringMeasure;
+/**
+ * Rejects values that exceed the profile or are not plain JSON.
+ *
+ * Self-contained by design: the body references only its parameters and
+ * ECMAScript built-ins, so `Function.prototype.toString()` can embed it
+ * verbatim into generated bootstrap source (see
+ * `playwrightRuntimeInputBootstrapSource`). Do not add references to
+ * module-scope bindings.
+ */
+export declare function requireBoundedJsonValue(value: unknown, label: string, profile: JsonBoundsProfile, measure: JsonStringMeasure): void;
+export declare function serializeBoundedJson(value: unknown, label: string, profile: JsonBoundsProfile, measure: JsonStringMeasure): string;

package/dist/engines/contracts/json-bounds.js

@@ -0,0 +1,2 @@
+export const RUNTIME_INPUT_JSON_BOUNDS=Object.freeze({maxCollectionEntries:1e4,maxDepth:32,maxNodes:5e4,maxStringUnits:4194304}),CHARACTER_JSON_STRING_MEASURE=Object.freeze({unitLabel:"characters",unitsOf:r=>r.length});export function requireBoundedJsonValue(r,e,t,o){let i=0;const s=(n,a)=>{if(i+=1,i>t.maxNodes)throw new Error(`${e} exceeds the ${t.maxNodes.toString()} node limit`);if(a>t.maxDepth)throw new Error(`${e} exceeds the ${t.maxDepth.toString()} level depth limit`);if(typeof n=="string"){if(o.unitsOf(n)>t.maxStringUnits)throw new Error(`${e} contains a string larger than ${t.maxStringUnits.toString()} ${o.unitLabel}`);return}if(typeof n=="number"){if(!Number.isFinite(n))throw new Error(`${e} contains a non-finite number`);return}if(n===null||typeof n=="boolean")return;if(typeof n!="object")throw new Error(`${e} contains a non-JSON value`);const c=Array.isArray(n)?n:Object.values(n);if(c.length>t.maxCollectionEntries)throw new Error(`${e} contains a collection larger than ${t.maxCollectionEntries.toString()} entries`);for(const u of c)s(u,a+1)};s(r,0)}export function serializeBoundedJson(r,e,t,o){requireBoundedJsonValue(r,e,t,o);const i=JSON.stringify(r);if(typeof i!="string")throw new Error(`${e} is not JSON-serializable`);return`${i}
+`}

package/dist/engines/contracts/k6-repository-configuration.d.ts

@@ -0,0 +1,12 @@
+import { type EngineJsonObject } from "../api/index.js";
+export declare const K6_REPOSITORY_CONFIGURATION_VERSION: 1;
+export interface K6RepositoryConfiguration {
+    readonly httpProfiles: Readonly<Record<string, K6RepositoryHttpProfile>>;
+    readonly kind: "testkit-k6-repository-configuration";
+    readonly version: typeof K6_REPOSITORY_CONFIGURATION_VERSION;
+}
+export type K6RepositoryHttpProfile = Readonly<{
+    kind: "json";
+    value: EngineJsonObject;
+}>;
+export declare function parseK6RepositoryConfiguration(value: unknown): K6RepositoryConfiguration | null;

package/dist/engines/contracts/k6-repository-configuration.js

@@ -0,0 +1 @@
+import{normalizeEngineJsonValue as u}from"../api/index.js";export const K6_REPOSITORY_CONFIGURATION_VERSION=1;export function parseK6RepositoryConfiguration(t){if(t===void 0)return null;const r=s(t,"k6 repository configuration");if(f(r,["httpProfiles","kind","version"],"k6 repository configuration"),r.kind!=="testkit-k6-repository-configuration")throw new Error('k6 repository configuration.kind must be "testkit-k6-repository-configuration"');if(r.version!==K6_REPOSITORY_CONFIGURATION_VERSION)throw new Error("k6 repository configuration.version must be 1");const o=s(r.httpProfiles,"k6 repository configuration.httpProfiles"),n=[];for(const[i,c]of Object.entries(o)){if(i.trim().length===0)throw new Error("k6 repository configuration.httpProfiles keys must be non-empty");n.push([i,p(c,`k6 repository configuration.httpProfiles.${i}`)])}const e=Object.fromEntries(n);return Object.freeze({httpProfiles:Object.freeze(e),kind:"testkit-k6-repository-configuration",version:K6_REPOSITORY_CONFIGURATION_VERSION})}function p(t,r){const o=s(t,r);if(o.kind==="json")return f(o,["kind","value"],r),Object.freeze({kind:"json",value:k(o.value,`${r}.value`)});throw new Error(`${r}.kind must be "json"`)}function k(t,r){const o=u(t,r);if(o===null||typeof o!="object"||Array.isArray(o))throw new Error(`${r} must be an object`);return o}function s(t,r){if(typeof t!="object"||t===null||Array.isArray(t))throw new Error(`${r} must be an object`);const o=Object.getPrototypeOf(t);if(o!==Object.prototype&&o!==null)throw new Error(`${r} must be a plain object`);return t}function f(t,r,o){const n=new Set(r);for(const e of Object.keys(t))if(!n.has(e))throw new Error(`${o} contains unknown field ${e}`);for(const e of r)if(!Object.hasOwn(t,e))throw new Error(`${o} is missing required field ${e}`)}

package/dist/engines/contracts/test-context.d.ts

@@ -0,0 +1,15 @@
+export interface TestNamespaceInput {
+    readonly leaseId?: unknown;
+    readonly runtimeId?: unknown;
+}
+export interface TestkitContext<Environment extends object = object> {
+    active: boolean;
+    leaseId: string | null;
+    namespace: string;
+    rawEnv: Environment;
+    runtimeId: string | null;
+}
+export declare function buildTestNamespace({ leaseId, runtimeId }?: TestNamespaceInput): string;
+export declare function readTestkitContext(env?: undefined): TestkitContext<Record<string, never>>;
+export declare function readTestkitContext<Environment extends object>(env: Environment): TestkitContext<Environment>;
+export declare function readTestkitContext<Environment extends object>(env: Environment | undefined): TestkitContext<Environment | Record<string, never>>;

package/dist/engines/contracts/test-context.js

@@ -0,0 +1 @@
+const r=String;function i(e){return r(e||"").trim().toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")}function t(e){return i(e)||null}function a(e,n){return Reflect.get(e,n)}export function buildTestNamespace({leaseId:e,runtimeId:n}={}){return t(e)||t(n)||"standalone"}export function readTestkitContext(e={}){const n=t(a(e,"TESTKIT_RUNTIME_ID")),o=t(a(e,"TESTKIT_LEASE_ID"));return{active:a(e,"TESTKIT_ACTIVE")==="1",runtimeId:n,leaseId:o,namespace:buildTestNamespace({leaseId:o,runtimeId:n}),rawEnv:e}}