sandboxedjs 0.1.25 → 0.1.27

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import EventEmitter from 'events';
+import EventEmitter from 'events/events.js';
 import streamModule from 'stream-browserify';
 
 /** The handle a pod's process manager returns. */
@@ -81,7 +81,12 @@ interface RuntimeProcessResult {
 }
 interface RuntimeProcess {
     readonly completion: Promise<RuntimeProcessResult>;
-    on(event: "output" | "error" | "exit", listener: (...args: any[]) => void): this;
+    /**
+     * `output` and `error` carry stdout and stderr; `exit` the code. `rawmode`
+     * reports the program turning terminal raw mode on or off, which a terminal
+     * needs so that it stops echoing input the program is drawing itself.
+     */
+    on(event: "output" | "error" | "exit" | "rawmode", listener: (...args: any[]) => void): this;
     write(data: string): void;
     kill(signal?: string): void;
 }
@@ -191,7 +196,7 @@ interface DirEntry {
 /**
  * The container's virtual filesystem.
  *
- * Real file content lives in a Nodepod `MemoryVolume`, which is deliberately the
+ * Real file content lives in the RuntimePod's `MemoryVolume`, deliberately the
  * *same* volume the Node.js worker processes see — so a file written by `echo`
  * is readable by `require('fs')` inside a spawned script, and vice versa.
  *
@@ -390,6 +395,14 @@ declare class Pipe implements InputStream, OutputStream {
     isTTY: boolean;
     /** Set on pipes owned by an outside caller, who may never call `end()`. */
     interactive: boolean;
+    /**
+     * Set while the running program has put the terminal in raw mode.
+     *
+     * A program in raw mode draws its own input — a prompt library redraws the
+     * whole line on every keystroke — so the terminal must stop echoing, or
+     * every character appears twice.
+     */
+    rawMode: boolean;
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -733,7 +746,7 @@ declare function createContext(init: ContextInit): ExecContext;
  * The container's network stack.
  *
  * There is no real socket layer: HTTP servers started inside the container are
- * registered with Nodepod's request proxy, and this module is the routing and
+ * registered with the RuntimePod's request proxy, and this module is the routing and
  * name-resolution layer on top — interfaces for `ip`/`ifconfig`, a hosts file
  * resolver, a listening-port table for `ss`/`netstat`, and an outbound policy
  * that decides whether `curl https://example.com` is allowed to touch the real
@@ -792,7 +805,7 @@ declare class NetworkStack {
     registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
     unregisterListener(port: number): void;
     listening(): ListeningPort[];
-    /** Ports Nodepod's proxy has registered for this instance. */
+    /** Ports the pod's proxy has registered for this instance. */
     private knownPodPorts;
     /** True when something inside the container answers on `port`. */
     isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;
@@ -1719,7 +1732,7 @@ declare class Container {
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
-     * Nodepod's public `request()` runs the body through `toString("utf8")` on
+     * A RuntimePod's public `request()` may run the body through `toString("utf8")` on
      * its way in, so anything above `0x7f` is replaced: a five-byte payload
      * containing `0x89` and `0xff` arrives as nine. That silently destroys every
      * upload — an image or a video reaches the server the wrong size and no
@@ -1759,7 +1772,7 @@ declare class Container {
     get cwd(): string;
     get env(): Record<string, string>;
     private assertActive;
-    /** Tear down every process and release the Nodepod instance. */
+    /** Tear down every process and release the runtime pod. */
     dispose(): void;
     get isDisposed(): boolean;
 }
@@ -2101,17 +2114,16 @@ interface RootfsOptions {
 declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
 
 /**
- * The Node.js runtime, backed by Nodepod.
+ * The Node.js command adapter, backed by the clean-room RuntimePod.
  *
- * Nodepod runs the script in an isolated worker over the *same* memory volume
+ * The pod runs the script over the *same* memory volume
  * the container's filesystem uses, so `require('fs')` inside a script sees the
  * files `echo` and `tar` created, and anything the script writes is visible to
  * the shell afterwards.
  *
- * Two gaps in the underlying `spawn` are papered over here:
+ * Two details of the underlying `spawn` are handled here:
  *  - only `node` resolves as a command, so everything else is dispatched by our
- *    own kernel rather than being handed to Nodepod's shell (which hangs on an
- *    unknown command);
+ *    own kernel rather than being handed to the Node process runner;
  *  - the worker's stdin has no end-of-stream signal, so when a pipeline feeds
  *    a script we materialise stdin as a file and install a real stdin stream
  *    over it before the script loads.
@@ -2262,6 +2274,16 @@ declare class CommonJsEngine {
     main: CommonJsModule | null;
     /** `package.json` per directory; resolution reads them constantly. */
     private readonly manifests;
+    private evaluationDepth;
+    /**
+     * Is a module body running synchronously right now?
+     *
+     * `process.exit` unwinds by throwing, and that is only safe while one of
+     * this engine's own frames is on the stack to catch it. Thrown from a later
+     * callback — a stream handler, a timer — it would escape into whichever
+     * library called that callback and surface as an unrelated crash.
+     */
+    get isEvaluating(): boolean;
     constructor(volume: RuntimeVolume, options?: Omit<CommonJsEngineOptions, "volume">);
     /**
      * Evaluate an entry point.
@@ -2426,12 +2448,31 @@ interface CoreModulesOptions {
     spawnChild?: SpawnChild;
     /** File holding the process's standard input, exposed as descriptor 0. */
     stdinPath?: string;
+    /** Keep `process.stdin` open and fed by {@link writeStdin} rather than ending it. */
+    interactiveStdin?: boolean;
+    /** Report the standard streams as a terminal, which is what makes CLIs prompt. */
+    tty?: boolean;
+    /** Called when the program turns raw mode on or off. */
+    onRawMode?: (enabled: boolean) => void;
 }
 /** Build the core-module table injected into each isolated JS worker. */
 declare function createCoreModules(options: CoreModulesOptions): {
     builtins: Record<string, unknown>;
     globals: Record<string, unknown>;
     process: Record<string, any>;
+    /** Deliver a chunk of input to an interactive `process.stdin`. */
+    writeStdin(data: string): void;
+    /** Signal end-of-input to an interactive `process.stdin`. */
+    endStdin(): void;
+    /**
+     * Is the program waiting on input?
+     *
+     * Node keeps a process alive for an open stdin only while something is
+     * actually reading it, and that distinction matters here: a CLI sitting on a
+     * prompt has no timers pending and would otherwise look finished, while a
+     * program that never touches stdin must still be allowed to exit.
+     */
+    readingStdin(): boolean;
     /**
      * How many timers this process still has outstanding.
      *
@@ -2442,6 +2483,8 @@ declare function createCoreModules(options: CoreModulesOptions): {
      * script that has simply finished.
      */
     pendingHandles(): number;
+    /** Active timers which called `unref()` and therefore only merit startup grace. */
+    pendingUnrefed(): number;
 };
 
 interface EsmTransformResult {
@@ -2528,9 +2571,18 @@ declare class LocalRuntimePod implements RuntimePod {
     private readonly aliases;
     private readonly modules;
     private readonly esbuild;
+    private rolldownBinding;
     private constructor();
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    /**
+     * Rolldown's JavaScript API synchronously requires its compiled binding.
+     * When a project contains Rolldown, preload the official WASI build in the
+     * host and expose it through the module override table before evaluation.
+     * Keeping this demand-driven avoids adding WASM startup cost to ordinary
+     * shells and Node programs.
+     */
+    private prepareRolldown;
     /**
      * Wait until the process has either started serving or genuinely run out of
      * work.
@@ -2565,6 +2617,10 @@ interface RegistryManifest {
     };
     dependencies?: Record<string, string>;
     optionalDependencies?: Record<string, string>;
+    os?: string[];
+    cpu?: string[];
+    libc?: string[];
+    main?: string;
     bin?: string | Record<string, string>;
 }
 interface CleanInstallerOptions {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import EventEmitter from 'events';
+import EventEmitter from 'events/events.js';
 import streamModule from 'stream-browserify';
 
 /** The handle a pod's process manager returns. */
@@ -81,7 +81,12 @@ interface RuntimeProcessResult {
 }
 interface RuntimeProcess {
     readonly completion: Promise<RuntimeProcessResult>;
-    on(event: "output" | "error" | "exit", listener: (...args: any[]) => void): this;
+    /**
+     * `output` and `error` carry stdout and stderr; `exit` the code. `rawmode`
+     * reports the program turning terminal raw mode on or off, which a terminal
+     * needs so that it stops echoing input the program is drawing itself.
+     */
+    on(event: "output" | "error" | "exit" | "rawmode", listener: (...args: any[]) => void): this;
     write(data: string): void;
     kill(signal?: string): void;
 }
@@ -191,7 +196,7 @@ interface DirEntry {
 /**
  * The container's virtual filesystem.
  *
- * Real file content lives in a Nodepod `MemoryVolume`, which is deliberately the
+ * Real file content lives in the RuntimePod's `MemoryVolume`, deliberately the
  * *same* volume the Node.js worker processes see — so a file written by `echo`
  * is readable by `require('fs')` inside a spawned script, and vice versa.
  *
@@ -390,6 +395,14 @@ declare class Pipe implements InputStream, OutputStream {
     isTTY: boolean;
     /** Set on pipes owned by an outside caller, who may never call `end()`. */
     interactive: boolean;
+    /**
+     * Set while the running program has put the terminal in raw mode.
+     *
+     * A program in raw mode draws its own input — a prompt library redraws the
+     * whole line on every keystroke — so the terminal must stop echoing, or
+     * every character appears twice.
+     */
+    rawMode: boolean;
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -733,7 +746,7 @@ declare function createContext(init: ContextInit): ExecContext;
  * The container's network stack.
  *
  * There is no real socket layer: HTTP servers started inside the container are
- * registered with Nodepod's request proxy, and this module is the routing and
+ * registered with the RuntimePod's request proxy, and this module is the routing and
  * name-resolution layer on top — interfaces for `ip`/`ifconfig`, a hosts file
  * resolver, a listening-port table for `ss`/`netstat`, and an outbound policy
  * that decides whether `curl https://example.com` is allowed to touch the real
@@ -792,7 +805,7 @@ declare class NetworkStack {
     registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
     unregisterListener(port: number): void;
     listening(): ListeningPort[];
-    /** Ports Nodepod's proxy has registered for this instance. */
+    /** Ports the pod's proxy has registered for this instance. */
     private knownPodPorts;
     /** True when something inside the container answers on `port`. */
     isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;
@@ -1719,7 +1732,7 @@ declare class Container {
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
-     * Nodepod's public `request()` runs the body through `toString("utf8")` on
+     * A RuntimePod's public `request()` may run the body through `toString("utf8")` on
      * its way in, so anything above `0x7f` is replaced: a five-byte payload
      * containing `0x89` and `0xff` arrives as nine. That silently destroys every
      * upload — an image or a video reaches the server the wrong size and no
@@ -1759,7 +1772,7 @@ declare class Container {
     get cwd(): string;
     get env(): Record<string, string>;
     private assertActive;
-    /** Tear down every process and release the Nodepod instance. */
+    /** Tear down every process and release the runtime pod. */
     dispose(): void;
     get isDisposed(): boolean;
 }
@@ -2101,17 +2114,16 @@ interface RootfsOptions {
 declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
 
 /**
- * The Node.js runtime, backed by Nodepod.
+ * The Node.js command adapter, backed by the clean-room RuntimePod.
  *
- * Nodepod runs the script in an isolated worker over the *same* memory volume
+ * The pod runs the script over the *same* memory volume
  * the container's filesystem uses, so `require('fs')` inside a script sees the
  * files `echo` and `tar` created, and anything the script writes is visible to
  * the shell afterwards.
  *
- * Two gaps in the underlying `spawn` are papered over here:
+ * Two details of the underlying `spawn` are handled here:
  *  - only `node` resolves as a command, so everything else is dispatched by our
- *    own kernel rather than being handed to Nodepod's shell (which hangs on an
- *    unknown command);
+ *    own kernel rather than being handed to the Node process runner;
  *  - the worker's stdin has no end-of-stream signal, so when a pipeline feeds
  *    a script we materialise stdin as a file and install a real stdin stream
  *    over it before the script loads.
@@ -2262,6 +2274,16 @@ declare class CommonJsEngine {
     main: CommonJsModule | null;
     /** `package.json` per directory; resolution reads them constantly. */
     private readonly manifests;
+    private evaluationDepth;
+    /**
+     * Is a module body running synchronously right now?
+     *
+     * `process.exit` unwinds by throwing, and that is only safe while one of
+     * this engine's own frames is on the stack to catch it. Thrown from a later
+     * callback — a stream handler, a timer — it would escape into whichever
+     * library called that callback and surface as an unrelated crash.
+     */
+    get isEvaluating(): boolean;
     constructor(volume: RuntimeVolume, options?: Omit<CommonJsEngineOptions, "volume">);
     /**
      * Evaluate an entry point.
@@ -2426,12 +2448,31 @@ interface CoreModulesOptions {
     spawnChild?: SpawnChild;
     /** File holding the process's standard input, exposed as descriptor 0. */
     stdinPath?: string;
+    /** Keep `process.stdin` open and fed by {@link writeStdin} rather than ending it. */
+    interactiveStdin?: boolean;
+    /** Report the standard streams as a terminal, which is what makes CLIs prompt. */
+    tty?: boolean;
+    /** Called when the program turns raw mode on or off. */
+    onRawMode?: (enabled: boolean) => void;
 }
 /** Build the core-module table injected into each isolated JS worker. */
 declare function createCoreModules(options: CoreModulesOptions): {
     builtins: Record<string, unknown>;
     globals: Record<string, unknown>;
     process: Record<string, any>;
+    /** Deliver a chunk of input to an interactive `process.stdin`. */
+    writeStdin(data: string): void;
+    /** Signal end-of-input to an interactive `process.stdin`. */
+    endStdin(): void;
+    /**
+     * Is the program waiting on input?
+     *
+     * Node keeps a process alive for an open stdin only while something is
+     * actually reading it, and that distinction matters here: a CLI sitting on a
+     * prompt has no timers pending and would otherwise look finished, while a
+     * program that never touches stdin must still be allowed to exit.
+     */
+    readingStdin(): boolean;
     /**
      * How many timers this process still has outstanding.
      *
@@ -2442,6 +2483,8 @@ declare function createCoreModules(options: CoreModulesOptions): {
      * script that has simply finished.
      */
     pendingHandles(): number;
+    /** Active timers which called `unref()` and therefore only merit startup grace. */
+    pendingUnrefed(): number;
 };
 
 interface EsmTransformResult {
@@ -2528,9 +2571,18 @@ declare class LocalRuntimePod implements RuntimePod {
     private readonly aliases;
     private readonly modules;
     private readonly esbuild;
+    private rolldownBinding;
     private constructor();
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    /**
+     * Rolldown's JavaScript API synchronously requires its compiled binding.
+     * When a project contains Rolldown, preload the official WASI build in the
+     * host and expose it through the module override table before evaluation.
+     * Keeping this demand-driven avoids adding WASM startup cost to ordinary
+     * shells and Node programs.
+     */
+    private prepareRolldown;
     /**
      * Wait until the process has either started serving or genuinely run out of
      * work.
@@ -2565,6 +2617,10 @@ interface RegistryManifest {
     };
     dependencies?: Record<string, string>;
     optionalDependencies?: Record<string, string>;
+    os?: string[];
+    cpu?: string[];
+    libc?: string[];
+    main?: string;
     bin?: string | Record<string, string>;
 }
 interface CleanInstallerOptions {