node-or-bun 0.0.0-stage → 0.2.1

package/dist/adapters/node.js

@@ -0,0 +1,233 @@
+import { spawn } from "node:child_process";
+import { PROCESS_CLEANUP_STEP_MS } from "../contract.js";
+import { ProcessRuntimeError, processError } from "../errors.js";
+import { rejectedReasons, settleOperation, withCause, } from "../internal/settlement.js";
+import { cleanupDirectChild } from "../internal/termination.js";
+const streamOrThrow = (stream, name) => {
+    if (stream === null) {
+        throw processError("launch", `${name} capture stream was unavailable`);
+    }
+    return stream;
+};
+const observeExit = (child) => {
+    let terminal = false;
+    let terminalResolve;
+    const terminalProof = new Promise((resolve) => {
+        terminalResolve = resolve;
+    });
+    let settle;
+    let reject;
+    const exited = new Promise((resolve, rejectPromise) => {
+        settle = resolve;
+        reject = rejectPromise;
+    });
+    void exited.catch(() => undefined);
+    const onExit = (exitCode, signal) => {
+        if (terminal)
+            return;
+        terminal = true;
+        terminalResolve();
+        settle({ exitCode, signal: signal === null ? null : String(signal) });
+    };
+    const onError = (error) => {
+        // ChildProcess errors may be emitted while a live child remains. They are
+        // observation failures, not proof that the process reached a terminal state.
+        if (terminal)
+            return;
+        reject(processError("launch", "child process observation failed", error));
+    };
+    child.once("exit", onExit);
+    child.on("error", onError);
+    return {
+        exited,
+        isTerminal: () => terminal,
+        hasPid: () => child.pid !== undefined,
+        waitForTerminal: (timeoutMs) => {
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            });
+            const settled = terminalProof.then(() => true);
+            return Promise.race([settled, timeout]).finally(() => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            });
+        },
+    };
+};
+const defaultCleanup = (child, cause, observation) => {
+    if (!observation.hasPid()) {
+        return Promise.reject(processError("cleanup", "child process was never spawned"));
+    }
+    return cleanupDirectChild({
+        cause,
+        isTerminal: observation.isTerminal,
+        waitForTerminal: observation.waitForTerminal,
+        terminate: (signal) => {
+            if (!child.kill(signal) && !observation.isTerminal()) {
+                throw processError("cleanup", `child process rejected ${signal}`);
+            }
+        },
+    });
+};
+const closeNodeCapture = async (child) => {
+    const streams = [child.stdout, child.stderr].filter((stream) => stream !== null);
+    await Promise.all(streams.map((stream) => new Promise((resolve, reject) => {
+        if (stream.closed) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const onClose = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        const onError = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        };
+        stream.once("close", onClose);
+        // Keep the listener attached after the first failure so repeated
+        // native stream errors cannot become unhandled EventEmitter errors.
+        stream.on("error", onError);
+        stream.destroy();
+    })));
+};
+const closeNodeCaptureWithin = async (child) => {
+    const close = closeNodeCapture(child);
+    close.catch(() => undefined);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(processError("cleanup", "native capture closure timed out")), PROCESS_CLEANUP_STEP_MS);
+    });
+    try {
+        await Promise.race([close, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};
+const createRunning = (child, observation, cleanupHook) => {
+    const stdout = streamOrThrow(child.stdout, "stdout");
+    const stderr = streamOrThrow(child.stderr, "stderr");
+    let cleanupPromise;
+    let closePromise;
+    return {
+        stdout,
+        stderr,
+        exited: observation.exited,
+        cleanup: (cause) => {
+            cleanupPromise ??= (async () => {
+                await cleanupHook(child, cause);
+            })();
+            return cleanupPromise;
+        },
+        closeCapture: () => {
+            closePromise ??= closeNodeCapture(child);
+            return closePromise;
+        },
+    };
+};
+const defaultAcquire = (request, retain) => {
+    const environment = request.environment === undefined
+        ? Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined))
+        : { ...request.environment };
+    const child = spawn(request.command, [...request.args], {
+        cwd: request.cwd,
+        env: environment,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    retain(child);
+};
+export const createNodeProcessAdapter = (options = {}) => {
+    const hasAcquire = options.acquire !== undefined;
+    const hasCleanup = options.cleanup !== undefined;
+    if (hasAcquire !== hasCleanup) {
+        throw processError("invalid-input", "acquire and cleanup hooks must be provided together");
+    }
+    const acquire = options.acquire ?? defaultAcquire;
+    const customCleanup = options.cleanup;
+    return {
+        launch: async (request) => {
+            let retainedChild;
+            let retainCount = 0;
+            let observation;
+            const retain = (child) => {
+                retainCount += 1;
+                if (retainCount !== 1 || !(child instanceof Object)) {
+                    throw processError("invalid-input", "retain must be called exactly once with one child");
+                }
+                retainedChild = child;
+                observation = observeExit(child);
+            };
+            const rollback = async (cause) => {
+                const child = retainedChild;
+                if (child === undefined) {
+                    throw processError("launch", "process setup failed", cause);
+                }
+                const observed = observation ?? observeExit(child);
+                const cleanupSettlement = await settleOperation(async () => {
+                    if (customCleanup !== undefined) {
+                        await customCleanup(child, "failed");
+                    }
+                    else if (observed.hasPid()) {
+                        await defaultCleanup(child, "failed", observed);
+                    }
+                });
+                const closeSettlement = await settleOperation(() => closeNodeCaptureWithin(child));
+                const failures = rejectedReasons([
+                    cleanupSettlement,
+                    closeSettlement,
+                ]);
+                if (failures.length > 0) {
+                    const cleanupCause = failures.length === 1
+                        ? failures[0]
+                        : new AggregateError(failures, "cleanup and capture closure both failed");
+                    throw withCause(new ProcessRuntimeError("cleanup", "process setup cleanup failed", {
+                        cause: cleanupCause,
+                        initiatingError: cause,
+                        incompleteCustody: true,
+                    }), cleanupCause);
+                }
+                throw processError("launch", "process setup failed", cause);
+            };
+            try {
+                acquire(request, retain);
+            }
+            catch (cause) {
+                return rollback(cause);
+            }
+            if (retainedChild === undefined || observation === undefined) {
+                return rollback(new Error("acquire did not retain one child"));
+            }
+            let running;
+            try {
+                const observed = observation ?? observeExit(retainedChild);
+                running = createRunning(retainedChild, observed, customCleanup ?? ((child, cause) => defaultCleanup(child, cause, observed)));
+                await new Promise((resolve, reject) => {
+                    const onSpawn = () => {
+                        retainedChild?.off("error", onError);
+                        resolve();
+                    };
+                    const onError = (error) => {
+                        retainedChild?.off("spawn", onSpawn);
+                        reject(error);
+                    };
+                    retainedChild?.once("spawn", onSpawn);
+                    retainedChild?.once("error", onError);
+                });
+                return running;
+            }
+            catch (cause) {
+                return rollback(cause);
+            }
+        },
+    };
+};
+//# sourceMappingURL=node.js.map

package/dist/adapters/node.js.map

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

package/dist/contract.d.ts

@@ -0,0 +1,39 @@
+import type { ProcessRuntimeFacts } from "./errors.js";
+export type Exit = {
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+};
+export type Launch = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly environment?: Readonly<Record<string, string>>;
+};
+export type Request = Launch & {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly strictUtf8?: boolean;
+};
+export type CompletionCause = "exited" | "cancelled" | "timeout" | "failed";
+export type RunningProcess = {
+    readonly stdout: AsyncIterable<Uint8Array>;
+    readonly stderr: AsyncIterable<Uint8Array>;
+    readonly exited: Promise<Exit>;
+    readonly cleanup: (cause: CompletionCause) => Promise<void>;
+    readonly closeCapture: () => Promise<void>;
+};
+export type ProcessAdapter = {
+    readonly launch: (request: Launch) => Promise<RunningProcess>;
+};
+export type ProcessRunResult = Exit & {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly facts: ProcessRuntimeFacts;
+};
+export type ProcessExecutor = {
+    readonly run: (request: Request) => Promise<ProcessRunResult>;
+};
+export declare const PROCESS_CAPTURE_LIMIT_BYTES: number;
+export declare const PROCESS_CLEANUP_STEP_MS = 1000;
+export declare const PROCESS_TIMEOUT_MAX_MS = 2147483647;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5E,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/D,CAAC;AAEF,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAC3D,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,sBAAsB,aAAgB,CAAC"}

package/dist/contract.js

@@ -0,0 +1,4 @@
+export const PROCESS_CAPTURE_LIMIT_BYTES = 4 * 1024 * 1024;
+export const PROCESS_CLEANUP_STEP_MS = 1_000;
+export const PROCESS_TIMEOUT_MAX_MS = 2_147_483_647;
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AA4CA,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAC7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+import type { Exit } from "./contract.js";
+export type ProcessErrorCode = "invalid-input" | "launch" | "output-limit" | "invalid-output" | "stream" | "timeout" | "cancelled" | "cleanup";
+export type ProcessInitiatingCause = "launch" | "timeout" | "cancellation" | "capture" | "observation" | "decode" | "exit" | null;
+export type ProcessRuntimeFacts = {
+    readonly initiatingCause: ProcessInitiatingCause;
+    readonly completionRequestedBeforeExitObservation: boolean;
+    readonly observedExit: Exit | null;
+    readonly lateFailureCodes: readonly ProcessErrorCode[];
+    readonly outputBounded: boolean;
+    readonly incompleteCustody: boolean;
+};
+export type ProcessCapturedOutput = {
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type ProcessRuntimeErrorOptions = {
+    readonly cause?: unknown;
+    readonly initiatingError?: unknown;
+    readonly incompleteCustody?: boolean;
+    readonly facts?: Partial<ProcessRuntimeFacts>;
+    readonly output?: ProcessCapturedOutput | null;
+};
+export declare class ProcessRuntimeError extends Error {
+    readonly code: ProcessErrorCode;
+    readonly initiatingError: unknown;
+    readonly facts: ProcessRuntimeFacts;
+    /** Bounded decoded captures, or null if either capture/decode is unavailable. */
+    readonly output: ProcessCapturedOutput | null;
+    constructor(code: ProcessErrorCode, message: string, options?: ProcessRuntimeErrorOptions);
+    get incompleteCustody(): boolean;
+}
+export declare const isProcessRuntimeError: (value: unknown) => value is ProcessRuntimeError;
+export declare const processError: (code: ProcessErrorCode, message: string, cause?: unknown) => ProcessRuntimeError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE1C,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,QAAQ,GACR,cAAc,GACd,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,MAAM,sBAAsB,GAC9B,QAAQ,GACR,SAAS,GACT,cAAc,GACd,SAAS,GACT,aAAa,GACb,QAAQ,GACR,MAAM,GACN,IAAI,CAAC;AAET,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,wCAAwC,EAAE,OAAO,CAAC;IAC3D,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,iFAAiF;IACjF,SAAiB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAEtD,YACE,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,0BAA+B,EA0BzC;IAED,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF;AAED,eAAO,MAAM,qBAAqB,UACzB,OAAO,KACb,KAAK,IAAI,mBAC0B,CAAC;AAEvC,eAAO,MAAM,YAAY,SACjB,gBAAgB,WACb,MAAM,UACP,OAAO,KACd,mBAC2E,CAAC"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+export class ProcessRuntimeError extends Error {
+    code;
+    initiatingError;
+    facts;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "ProcessRuntimeError";
+        this.code = code;
+        this.initiatingError = options.initiatingError ?? null;
+        // Keep captured content out of ordinary error enumeration/JSON. Explicit
+        // access is still sensitive and callers decide whether to expose it.
+        Object.defineProperty(this, "output", {
+            value: options.output == null
+                ? null
+                : Object.freeze({ stdout: options.output.stdout, stderr: options.output.stderr }),
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+        this.facts = Object.freeze({
+            initiatingCause: options.facts?.initiatingCause ?? null,
+            completionRequestedBeforeExitObservation: options.facts?.completionRequestedBeforeExitObservation ?? false,
+            observedExit: options.facts?.observedExit ?? null,
+            lateFailureCodes: Object.freeze([...(options.facts?.lateFailureCodes ?? [])]),
+            outputBounded: options.facts?.outputBounded ?? false,
+            incompleteCustody: options.facts?.incompleteCustody ?? options.incompleteCustody ?? false,
+        });
+    }
+    get incompleteCustody() {
+        return this.facts.incompleteCustody;
+    }
+}
+export const isProcessRuntimeError = (value) => value instanceof ProcessRuntimeError;
+export const processError = (code, message, cause) => new ProcessRuntimeError(code, message, cause === undefined ? {} : { cause });
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AA4CA,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,CAAmB;IACvB,eAAe,CAAU;IACzB,KAAK,CAAsB;IAIpC,YACE,IAAsB,EACtB,OAAe,EACf,OAAO,GAA+B,EAAE;QAExC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;QACvD,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE;YACpC,KAAK,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;gBAC3B,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnF,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;YACzB,eAAe,EAAE,OAAO,CAAC,KAAK,EAAE,eAAe,IAAI,IAAI;YACvD,wCAAwC,EACtC,OAAO,CAAC,KAAK,EAAE,wCAAwC,IAAI,KAAK;YAClE,YAAY,EAAE,OAAO,CAAC,KAAK,EAAE,YAAY,IAAI,IAAI;YACjD,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,gBAAgB,IAAI,EAAE,CAAC,CAAC,CAAC;YAC7E,aAAa,EAAE,OAAO,CAAC,KAAK,EAAE,aAAa,IAAI,KAAK;YACpD,iBAAiB,EACf,OAAO,CAAC,KAAK,EAAE,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,IAAI,KAAK;SACzE,CAAC,CAAC;IACL,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,KAAc,EACgB,EAAE,CAChC,KAAK,YAAY,mBAAmB,CAAC;AAEvC,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAsB,EACtB,OAAe,EACf,KAAe,EACM,EAAE,CACvB,IAAI,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC"}

package/dist/executor.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessAdapter, ProcessExecutor } from "./contract.js";
+export declare const createProcessExecutor: (adapter: ProcessAdapter) => ProcessExecutor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACd,eAAe,EAIhB,MAAM,eAAe,CAAC;AAoFvB,eAAO,MAAM,qBAAqB,YAAa,cAAc,KAAG,eA4Q/D,CAAC"}