@gadgetinc/substrate 0.1.0-rc.1

package/dist/runtime/process-event-loop.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Per-Process Event Loop
+ *
+ * Each process gets its own event loop instance with isolated:
+ * - nextTick queue
+ * - Timer management (heap + single browser timer)
+ * - setImmediate (check) queue
+ * - Close callbacks queue
+ *
+ * The event loop implements Node.js phase ordering:
+ * 1. timers - setTimeout/setInterval callbacks
+ * 2. pending callbacks - I/O callbacks deferred to next loop
+ * 3. poll - retrieve new I/O events from kernel
+ * 4. check - setImmediate callbacks
+ * 5. close callbacks - socket.on('close', ...)
+ *
+ * Between each phase, nextTick queue is drained, then Promise microtasks run.
+ */
+import type { KernelBridge, KernelEvent } from "../kernel/types.js";
+import { type Waker } from "./process-waker.js";
+/**
+ * Set the global pending work hook.
+ * Called by the WASM package interceptor to keep event loops alive during installation.
+ */
+export declare function setGlobalPendingWorkHook(hook: (() => boolean) | null): void;
+export declare class UnhandledEventLoopError extends Error {
+    constructor(message: string, cause: unknown);
+}
+type Callback = (...args: unknown[]) => void;
+interface ImmediateEntry {
+    id: number;
+    callback: Callback;
+    args?: unknown[];
+    ref: boolean;
+    cleared: boolean;
+}
+/**
+ * Timer entry in the heap
+ */
+interface TimerEntry {
+    id: number;
+    callback: Callback;
+    args?: unknown[];
+    expireAt: number;
+    delay: number;
+    refresh(): void;
+    interval: number | null;
+    ref: boolean;
+    cleared: boolean;
+}
+/**
+ * Timer handle returned to user code
+ */
+export declare class Timeout {
+    private _id;
+    private _timer;
+    constructor(id: number, timer: TimerEntry);
+    ref(): this;
+    unref(): this;
+    hasRef(): boolean;
+    refresh(): this;
+    [Symbol.toPrimitive](): number;
+    [Symbol.dispose](): void;
+}
+/**
+ * Immediate handle returned to user code
+ */
+export declare class Immediate {
+    private _id;
+    private _immediate;
+    constructor(id: number, immediate: ImmediateEntry);
+    ref(): this;
+    unref(): this;
+    hasRef(): boolean;
+    [Symbol.toPrimitive](): number;
+    [Symbol.dispose](): void;
+}
+export type TimerHandle = Timeout;
+export type ImmediateHandle = Immediate;
+/**
+ * Event handler callback type
+ */
+export type EventHandler<T extends KernelEvent = KernelEvent> = (event: T) => void;
+/**
+ * Typed event names matching kernel event types
+ */
+export type EventType = "fs_watch_event" | "fs_read_complete" | "fs_read_error" | "fs_write_complete" | "fs_write_error" | "net_accept" | "net_readable" | "net_closed" | "proc_exit" | "pipe_readable" | "proc_stdout" | "proc_stderr" | "timer_fired" | "log";
+export { type Waker, createWaker, registerWaker, unregisterWaker, wakeAllWakers, } from "./process-waker.js";
+export declare const createProcessEventLoop: (pid: number, kernel: KernelBridge) => ProcessEventLoopImpl;
+/**
+ * Get a process event loop, throwing an error if not found.
+ * NOTE TO LLMs: Do not right defensive code for this function.
+ * If the runtime needs an event loop and one doesn't exist, throw an error.
+ * It is a critical error if this function throws and we should know early.
+ */
+export declare const getProcessEventLoop: (pid: number) => ProcessEventLoopImpl;
+/**
+ * Reset all event loops (test helper).
+ */
+export declare const resetEventLoops: () => void;
+export type ProcessEventLoop = ProcessEventLoopImpl;
+/**
+ * I/O handle callback type - called when kernel events are ready for this handle
+ */
+type HandleCallback = (event: KernelEvent) => void;
+/**
+ * Async context snapshot — maps AsyncLocalStorage instances to their stores.
+ * Used to propagate context across async boundaries (setTimeout, Promise.then, etc.)
+ */
+export type AsyncContext = Map<object, unknown>;
+/**
+ * Per-process event loop
+ *
+ * Each process gets its own isolated event loop with its own queues and timers.
+ */
+declare class ProcessEventLoopImpl {
+    /** Process ID this event loop belongs to */
+    readonly pid: number;
+    /** Kernel bridge (shared across processes) */
+    private kernel;
+    /** Kernel event queue ID for this process */
+    private eqId;
+    /** Whether the event loop is running */
+    private running;
+    /**
+     * Set when process.exit() is called. Ensures the event loop exits even if
+     * user code catches the ProcessExitError. The stored code/signal are used
+     * to throw a new ProcessExitError after the loop breaks.
+     */
+    private _exitRequested;
+    /**
+     * The currently active async context for this process.
+     * Maps AsyncLocalStorage instances to their store values.
+     * null means no context is active (default state).
+     */
+    private _currentAsyncContext;
+    /** nextTick queue - drains synchronously, runs BEFORE Promise microtasks */
+    private nextTickQueue;
+    /**
+     * Node microtask queue - for Promise .then() callbacks and queueMicrotask()
+     * This runs AFTER nextTick but still within our controlled checkpoint.
+     * User code's Promise continuations go here instead of browser's microtask queue.
+     */
+    private nodeMicrotaskQueue;
+    /** Timer heap - ordered by expiration time */
+    private timerHeap;
+    private nextTimerId;
+    /** Immediate (check) queue */
+    private immediateQueue;
+    private nextImmediateId;
+    /** Close callbacks queue */
+    private closeQueue;
+    /** Pending I/O callbacks (from poll phase) */
+    private pendingCallbacks;
+    /**
+     * Registered I/O handles by ID.
+     * Key format: "server:{server_id}" or "conn:{conn_id}" or "watch:{watch_id}"
+     */
+    private handles;
+    private refCount;
+    /** Waker for signaling the event loop to wake up from poll */
+    wake: Waker;
+    private _globals;
+    private _builtinModules;
+    private _checkUnhandledRejections;
+    constructor(pid: number, kernel: KernelBridge);
+    /**
+     * Create a wrapped fetch function that returns SubstratePromise.
+     * This ensures that fetch() continuations run through our event loop's
+     * microtask queue instead of the browser's native microtask queue.
+     */
+    private createWrappedFetch;
+    /**
+     * Initialize the kernel event queue for this process
+     */
+    private initKernelEventQueue;
+    /**
+     * Get the kernel event queue ID for this process.
+     * Used when registering for kernel events (e.g., net_listen with eq_id).
+     */
+    getEventQueueId(): number | null;
+    /**
+     * Capture the current async context. Returns null if no context is active.
+     * Called when scheduling callbacks (setTimeout, nextTick, Promise.then, etc.)
+     * to snapshot the context at schedule time.
+     */
+    captureAsyncContext(): AsyncContext | null;
+    /**
+     * Run a function within a given async context.
+     * The previous context is saved and restored after the function completes.
+     */
+    runInAsyncContext<T>(context: AsyncContext | null, fn: () => T): T;
+    /**
+     * Replace the current async context entirely.
+     * Used by AsyncLocalStorage.enterWith() which permanently modifies
+     * the context for the remainder of the current execution.
+     */
+    setCurrentAsyncContext(context: AsyncContext | null): void;
+    /**
+     * Wrap a callback with the current async context so it is restored
+     * when the callback executes. This is the core mechanism for propagating
+     * AsyncLocalStorage stores across async boundaries.
+     */
+    private wrapWithContext;
+    /**
+     * Register a server handle. When NetAccept events arrive for this server,
+     * the callback will be queued as a pending I/O callback.
+     */
+    registerServer(serverId: number, callback: HandleCallback, ref?: boolean): void;
+    /**
+     * Unregister a server handle.
+     */
+    unregisterServer(serverId: number): void;
+    /**
+     * Register a connection handle. When events arrive for this connection,
+     * the callback will be queued as a pending I/O callback.
+     */
+    registerConnection(connId: number, callback: HandleCallback, ref?: boolean): void;
+    /**
+     * Register a filesystem watch handle. When FsWatch events arrive for this watch,
+     * the callback will be queued as a pending I/O callback.
+     */
+    registerFsWatch(watchId: number, callback: HandleCallback, ref?: boolean): void;
+    /**
+     * Register a pipe/fd handle. When PipeReadable events arrive for this fd,
+     * the callback will be queued as a pending I/O callback.
+     */
+    registerFdReadable(fd: number, callback: HandleCallback, ref?: boolean): void;
+    /**
+     * Unregister a connection handle.
+     */
+    unregisterConnection(connId: number): void;
+    /**
+     * Unregister a filesystem watch handle.
+     */
+    unregisterFsWatch(watchId: number): void;
+    /**
+     * Unregister a pipe/fd handle.
+     */
+    unregisterFdReadable(fd: number): void;
+    /**
+     * Queue a callback as a pending I/O callback.
+     * These run in the pending callbacks phase.
+     */
+    queuePendingCallback(callback: Callback): void;
+    setGlobal(key: string, value: unknown): void;
+    /**
+     * Report an unhandled promise rejection.
+     *
+     * Called by the SubstratePromise checkpoint after microtask queues drain.
+     * Mirrors Node.js semantics: if a process.on('unhandledRejection') handler
+     * exists, emit the event. Otherwise, print the error and exit with code 1.
+     */
+    reportUnhandledRejection(reason: unknown, promise: unknown): void;
+    isBuiltinModule(name: string): boolean;
+    runWithGlobals<T>(fn: () => T): T;
+    nextTick(callback: Callback, ...args: unknown[]): void;
+    queueMicrotask(callback: Callback): void;
+    setImmediate(callback: Callback, ...args: unknown[]): Immediate;
+    clearImmediate(immediate: Immediate | number | null | undefined): void;
+    queuePending(callback: Callback): void;
+    queueClose(callback: Callback): void;
+    setTimeout(callback: Callback, delayMs: number, ...args: unknown[]): Timeout;
+    setInterval(callback: Callback, intervalMs: number, ...args: unknown[]): Timeout;
+    clearTimeout(timeout: Timeout | number | null | undefined): void;
+    clearInterval(interval: Timeout | number | null | undefined): void;
+    /**
+     * Add a reference to keep the event loop alive.
+     * Used by servers, sockets, and other long-running handles.
+     */
+    ref(): void;
+    /**
+     * Remove a reference. When all references are removed and no other work
+     * is pending, the event loop will exit.
+     */
+    unref(): void;
+    /**
+     * Start the event loop
+     */
+    start(): Promise<void>;
+    /**
+     * Run a single event loop iteration (test helper).
+     */
+    runOnce(): Promise<void>;
+    /**
+     * Request the event loop to exit with the given code.
+     *
+     * Called by process.exit(). In real Node.js, process.exit() is uncatchable —
+     * it terminates the process immediately. In Substrate, process.exit() throws
+     * a ProcessExitError which CAN be caught by user code (e.g., pnpm wraps
+     * internal scripts in try/catch). This method ensures the event loop exits
+     * on the next iteration even if user code swallows the error. The stored
+     * code/signal are re-thrown as a ProcessExitError after the loop breaks.
+     */
+    requestExit(code: number, signal?: string | null): void;
+    /**
+     * Stop the event loop
+     */
+    stop(): void;
+    /**
+     * Check if the event loop is running
+     */
+    isRunning(): boolean;
+    /**
+     * Test helper for inspecting waker state.
+     */
+    __getWakerWaiterCount(): number;
+    private loopAlive;
+    /**
+     * Check if the process was signaled before the event loop started.
+     *
+     * This handles the race condition where:
+     * 1. Parent spawns child, gets pid
+     * 2. Parent calls child.kill() before child's event loop creates its event queue
+     * 3. Kernel emits ProcExit event, but eq_id is None so it's dropped
+     * 4. Child's event loop starts and never sees the signal
+     *
+     * By checking the process's signal state at startup, we can recover from this.
+     */
+    private checkPendingSignal;
+    private runIteration;
+    private poll;
+    /**
+     * Poll kernel event queue and dispatch events to listeners.
+     * Returns true if any events were processed.
+     */
+    private pollKernelEvents;
+    /**
+     * Dispatch a kernel event by looking up the handle and queuing its callback
+     * as a pending I/O callback.
+     */
+    private dispatchKernelEvent;
+    private computePollTimeout;
+    /**
+     * Find the next non-cleared, ref'd timer (for poll timeout calculation).
+     * Unlike peekNextActiveTimer(), this only returns ref'd timers.
+     */
+    private peekNextRefedTimer;
+    private drainPhaseQueue;
+    private callAndDrainNextTickAndMicrotaskQueues;
+    private callAndRethrow;
+    private drainNextTickAndMicrotaskQueues;
+    private drainQueue;
+    private hasImmediateWork;
+    private addTimer;
+    private runTimers;
+    private peekNextActiveTimer;
+    /**
+     * Check if there are any ref'd timers that would keep the loop alive.
+     * Unref'd timers don't keep the loop alive but will still fire if the loop
+     * is running for other reasons.
+     */
+    private hasActiveTimers;
+    private timersDueNow;
+}
+//# sourceMappingURL=process-event-loop.d.ts.map

package/dist/runtime/process-event-loop.d.ts.map

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

package/dist/runtime/process-handler.d.ts

@@ -0,0 +1,71 @@
+import type { ProcessContext } from "./process-context.js";
+import type { BinaryName, BinarySpec } from "../binaries.js";
+/**
+ * Callback invoked when a process exits.
+ */
+export type ProcessExitCallback = (exitCode: number, signal: string | null) => void;
+/**
+ * Process Handler Interface
+ *
+ * Handlers are responsible for the full lifecycle of a process:
+ * - Parsing arguments
+ * - Setting up execution environment
+ * - Running the process (however that makes sense for this handler)
+ * - Calling onExit when complete
+ *
+ * For Node.js handlers, this means creating an event loop internally.
+ * Future handlers (WASM, etc.) may use different execution models.
+ */
+export interface ProcessHandler {
+    /** List of commands this handler can execute */
+    commands: string[];
+    /**
+     * Install the binary for the process from a tar URL.
+     * Optional - only needed for handlers that require external installation.
+     */
+    install?(tarUrl: string): Promise<void>;
+    /**
+     * Start a process.
+     *
+     * The handler is responsible for:
+     * 1. Parsing arguments
+     * 2. Setting up the execution environment
+     * 3. Running the process (creating event loop, starting WASM, etc.)
+     * 4. Calling onExit(code, signal) when the process completes
+     *
+     * This method should return quickly - the actual execution happens
+     * asynchronously via the handler's internal scheduling mechanism.
+     *
+     * @param command - The command being executed
+     * @param args - Arguments passed to the command
+     * @param processContext - The ProcessContext for this execution
+     * @param onExit - Callback to invoke when the process exits
+     */
+    start(command: string, args: string[], processContext: ProcessContext, onExit: ProcessExitCallback): void;
+}
+/**
+ * Register a process handler.
+ *
+ * If a handler already exists for any of the commands, it will be replaced.
+ * This allows WASM packages to override handlers when detected.
+ */
+export declare function registerHandler(handler: ProcessHandler): void;
+/**
+ * Get a handler for a command.
+ */
+export declare function getHandler(command: string): ProcessHandler;
+/**
+ * Check if a handler exists for a command.
+ */
+export declare function hasHandler(command: string): boolean;
+/**
+ * Get all registered commands.
+ */
+export declare function getRegisteredCommands(): string[];
+/**
+ * Initialize process handlers for the specified binaries.
+ *
+ * This is called during Substrate boot to set up handlers that need installation.
+ */
+export declare function initProcessHandlers(binaries: Partial<Record<BinaryName, BinarySpec>>): Promise<void>;
+//# sourceMappingURL=process-handler.d.ts.map

package/dist/runtime/process-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/process-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAU7D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;AAEpF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAAC;CACT;AAKD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAY7D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAM1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAQhD;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/runtime/process-handlers/node.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js Process Handler
+ *
+ * Handles `node` command by running scripts within an isolated ProcessContext.
+ * Each child process has its own event loop, module cache, and state.
+ */
+import type { ProcessHandler } from "../process-handler.js";
+/**
+ * Handler for `node` command
+ *
+ * Executes Node.js scripts in an isolated ProcessContext with its own event loop.
+ *
+ * Supports:
+ * - Running .js/.mjs/.cjs files
+ * - -e/--eval for inline code
+ * - -p/--print for eval + print
+ * - -c/--check for syntax checking
+ * - -r/--require for preloading modules
+ */
+declare const NodeHandler: ProcessHandler;
+export default NodeHandler;
+//# sourceMappingURL=node.d.ts.map

package/dist/runtime/process-handlers/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAcjF;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,WAAW,EAAE,cA8DlB,CAAC;AAuPF,eAAe,WAAW,CAAC"}

package/dist/runtime/process-handlers/npm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * npm Process Handler
+ *
+ * Delegates to real npm, auto-installing on first use if needed.
+ */
+import type { ProcessHandler } from "../process-handler.js";
+export declare const NPM_INSTALL_PATH = "/usr/lib/node_modules/npm";
+export declare const NPM_BIN_PATH = "/usr/lib/node_modules/npm/bin/npm-cli.js";
+/**
+ * Check if real npm is already installed
+ */
+export declare function isNpmInstalled(): boolean;
+/**
+ * Handler for `npm` command
+ *
+ * Auto-installs npm on first use, then delegates to real npm.
+ */
+export declare const NpmHandler: ProcessHandler;
+export default NpmHandler;
+//# sourceMappingURL=npm.d.ts.map

package/dist/runtime/process-handlers/npm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/npm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAMjF,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAC5D,eAAO,MAAM,YAAY,6CAA6C,CAAC;AAEvE;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAMxC;AAMD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,cAqDxB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/runtime/process-handlers/npx.d.ts

@@ -0,0 +1,11 @@
+/**
+ * npx Process Handler
+ *
+ * Delegates to npx-cli.js which ships with the npm package.
+ * No separate installation needed — npx is available whenever npm is installed.
+ */
+import type { ProcessHandler } from "../process-handler.js";
+export declare const NPX_BIN_PATH = "/usr/lib/node_modules/npm/bin/npx-cli.js";
+export declare const NpxHandler: ProcessHandler;
+export default NpxHandler;
+//# sourceMappingURL=npx.d.ts.map

package/dist/runtime/process-handlers/npx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npx.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/npx.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAIjF,eAAO,MAAM,YAAY,6CAA6C,CAAC;AAEvE,eAAO,MAAM,UAAU,EAAE,cAWxB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/runtime/process-handlers/pnpm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * pnpm Process Handler
+ *
+ * Delegates to real pnpm, auto-installing on first use if needed.
+ */
+import type { ProcessHandler } from "../process-handler.js";
+export declare const PNPM_INSTALL_PATH = "/usr/lib/node_modules/pnpm";
+export declare const PNPM_BIN_PATH = "/usr/lib/node_modules/pnpm/bin/pnpm.cjs";
+export declare function isPnpmInstalled(): boolean;
+export declare const PnpmHandler: ProcessHandler;
+export default PnpmHandler;
+//# sourceMappingURL=pnpm.d.ts.map

package/dist/runtime/process-handlers/pnpm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pnpm.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/pnpm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAKjF,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAC9D,eAAO,MAAM,aAAa,4CAA4C,CAAC;AAEvE,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAED,eAAO,MAAM,WAAW,EAAE,cA+BzB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/runtime/process-handlers/shell.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shell Handler
+ *
+ * Shims common shells (sh, bash) to support npm postinstall scripts and other
+ * shell-based commands. Parses simple commands and delegates to known handlers.
+ *
+ * Supports:
+ * - `sh -c "node install.js"` → delegates to node handler
+ * - `sh -c "npm run build"` → delegates to npm handler
+ * - `bash -c "command"` → same as sh
+ *
+ * Does NOT support:
+ * - Pipes: `cmd1 | cmd2`
+ * - Redirects: `cmd > file`
+ * - Shell builtins: `cd`, `export`, `echo` (most)
+ * - Complex quoting/escaping
+ */
+import type { ProcessHandler } from "../process-handler.js";
+/**
+ * Shell handler that intercepts sh/bash -c commands and delegates to known handlers.
+ */
+export declare const ShellHandler: ProcessHandler;
+export default ShellHandler;
+//# sourceMappingURL=shell.d.ts.map

package/dist/runtime/process-handlers/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAkDjF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cA+F1B,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/runtime/process-handlers/yarn.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Yarn Classic Process Handler
+ *
+ * Delegates to real Yarn Classic (v1.x), auto-installing on first use if needed.
+ */
+import type { ProcessHandler } from "../process-handler.js";
+export declare const YARN_INSTALL_PATH = "/usr/lib/node_modules/yarn";
+export declare const YARN_BIN_PATH = "/usr/lib/node_modules/yarn/bin/yarn.js";
+export declare function isYarnInstalled(): boolean;
+export declare const YarnHandler: ProcessHandler;
+export default YarnHandler;
+//# sourceMappingURL=yarn.d.ts.map

package/dist/runtime/process-handlers/yarn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yarn.d.ts","sourceRoot":"","sources":["../../../src/runtime/process-handlers/yarn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAKjF,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAC9D,eAAO,MAAM,aAAa,2CAA2C,CAAC;AAEtE,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAED,eAAO,MAAM,WAAW,EAAE,cA+BzB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/runtime/process-helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared Process Helpers
+ *
+ * Utilities for creating per-process console and formatting values.
+ * Used by both NodeHandler and worker_threads.
+ */
+import type { ProcessContext } from "./process-context.js";
+/**
+ * Format a value for console output
+ */
+export declare function formatValue(value: unknown): string;
+/**
+ * Create a console object that writes to a process's stdout/stderr.
+ * This is injected into process contexts to shadow the global console.
+ */
+export declare function createConsole(processContext: ProcessContext): Console;
+//# sourceMappingURL=process-helpers.d.ts.map

package/dist/runtime/process-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/process-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBlD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,cAAc,GAAG,OAAO,CA4CrE"}