sandboxedjs 0.1.36 → 0.1.37

package/dist/container-BsPKqY9R.d.cts

@@ -0,0 +1,1789 @@
+/** The handle a pod's process manager returns. */
+interface ChildHandle {
+    pid: number;
+    state: "starting" | "running" | "exited";
+    exitCode: number | undefined;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
+    exec(): void;
+    sendStdin(data: string): void;
+    /**
+     * Close the child's input.
+     *
+     * Without this a child that reads stdin to EOF — every filter, and every
+     * tool a library pipes into, `xsel` and `base64` alike — waits forever for
+     * an end that never comes, and the parent waits on its exit.
+     */
+    endStdin?(): void;
+    kill(signal?: string): void;
+}
+interface ChildSpawnConfig {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    parentPid?: number;
+    /**
+     * The child was given the parent's streams (`stdio: "inherit"`).
+     *
+     * Its input is then the parent's terminal rather than a pipe that will end,
+     * which is the difference between a program that waits for what the user
+     * types and one that reads to end-of-input and stops.
+     */
+    inheritStdio?: boolean;
+}
+type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
+/**
+ * Run a child to completion without returning to the event loop.
+ *
+ * Supplied only by a pod that can actually block — one whose guest runs on its
+ * own thread. Where it is absent the synchronous entry points keep reporting
+ * that they are unavailable, which is the honest answer for an in-realm pod.
+ */
+type SyncSpawn = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    input?: string;
+    inheritStdio?: boolean;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    signal: string | null;
+    error?: {
+        code?: string;
+        message: string;
+    };
+};
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn, defaultEnv?: () => Record<string, string>): Record<string, unknown>;
+
+/**
+ * Clean-room contracts between SandboxedJS and its JavaScript runtime.
+ *
+ * These deliberately describe only behavior SandboxedJS consumes. Runtime
+ * implementations may use Web Workers in browsers or worker_threads on Node.
+ */
+
+interface VolumeStats {
+    totalBytes: number;
+    fileCount: number;
+    /** New runtime spelling. */
+    directoryCount?: number;
+    /** Compatibility spelling used by existing volume implementations. */
+    dirCount?: number;
+}
+interface VolumeStat {
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    ino: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface RuntimeVolume {
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    mkdirSync(path: string, options?: {
+        mode?: number;
+    }): void;
+    rmdirSync(path: string): void;
+    unlinkSync(path: string): void;
+    renameSync(from: string, to: string): void;
+    symlinkSync(target: string, path: string): void;
+    linkSync(existing: string, path: string): void;
+    truncateSync(path: string, length?: number): void;
+    chmodSync(path: string, mode: number): void;
+    lchmodSync(path: string, mode: number): void;
+    chownSync(path: string, uid: number, gid: number): void;
+    lchownSync(path: string, uid: number, gid: number): void;
+    utimesSync(path: string, atime: Date, mtime: Date): void;
+    getStats(): VolumeStats;
+}
+interface RuntimeProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface RuntimeProcess {
+    readonly completion: Promise<RuntimeProcessResult>;
+    /**
+     * `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;
+}
+interface RuntimeHttpResponse {
+    statusCode?: number;
+    statusMessage?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | ArrayBuffer;
+}
+interface RuntimePackageInstaller {
+    install(name: string, version?: string, options?: Record<string, unknown>): Promise<unknown>;
+    installFromManifest(path: string, options?: Record<string, unknown>): Promise<unknown>;
+    /** Create a view that installs into another project root. */
+    forCwd?(cwd: string): RuntimePackageInstaller;
+}
+/** The process-manager protocol a container's kernel bridge substitutes for. */
+interface RuntimeProcessManager {
+    spawn(config: ChildSpawnConfig): ChildHandle;
+}
+interface RuntimePod {
+    readonly volume: RuntimeVolume;
+    readonly packages: RuntimePackageInstaller;
+    readonly instanceId: string;
+    readonly processManager: RuntimeProcessManager;
+    readonly proxy: {
+        activePorts(instanceId?: string): number[];
+    };
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    request(port: number, init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    snapshot(options?: Record<string, unknown>): unknown;
+    restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
+    teardown(): void;
+}
+
+type FileKind = "file" | "directory" | "symlink" | "chardev" | "blockdev" | "fifo" | "socket";
+/** Render as `drwxr-xr-x`, honouring setuid/setgid/sticky. */
+declare function formatMode(mode: number): string;
+/** Zero-padded octal permissions, as `stat -c %a`/`%04a` would show. */
+declare function octalMode(mode: number, width?: number): string;
+/**
+ * Apply a `chmod` spec to an existing mode. Accepts octal (`755`, `0644`) and
+ * the symbolic grammar (`u+rwx,go-w`, `a=r`, `+X`, `u+s`, `o+t`).
+ *
+ * @param isDir whether the target is a directory — needed for the `X` flag.
+ */
+declare function applyChmod(spec: string, current: number, isDir: boolean, umask?: number): number;
+/** Parse the `umask` builtin's argument. */
+declare function parseUmask(spec: string): number;
+
+/**
+ * The `Stats` object handed back by `Vfs.stat`. Shaped like `fs.Stats` so it
+ * feels familiar, but with a real `st_mode` that carries the file-type bits
+ * (which the underlying volume stores separately).
+ */
+
+interface StatInit {
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    ino: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs?: number;
+    dev?: number;
+    rdev?: number;
+    blksize?: number;
+}
+declare class Stats {
+    readonly mode: number;
+    readonly size: number;
+    readonly uid: number;
+    readonly gid: number;
+    readonly ino: number;
+    readonly nlink: number;
+    readonly dev: number;
+    readonly rdev: number;
+    readonly blksize: number;
+    readonly atimeMs: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+    constructor(init: StatInit);
+    get blocks(): number;
+    get atime(): Date;
+    get mtime(): Date;
+    get ctime(): Date;
+    get birthtime(): Date;
+    get kind(): FileKind;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isCharacterDevice(): boolean;
+    isBlockDevice(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+    /** Permission bits only, with the type bits masked off. */
+    get perms(): number;
+}
+interface DirEntry {
+    name: string;
+    kind: FileKind;
+}
+
+/**
+ * The container's virtual filesystem.
+ *
+ * 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.
+ *
+ * On top of that volume this layer adds the parts a Linux userland expects and
+ * the raw volume does not have: file-type bits in `st_mode`, permission and
+ * ownership checks, an `O_*` open/fd table, and pluggable *virtual providers*
+ * that synthesise `/proc`, `/sys` and `/dev` on demand.
+ */
+
+/** The identity a filesystem operation runs as. */
+interface Cred {
+    uid: number;
+    gid: number;
+    groups: number[];
+    umask: number;
+}
+declare const ROOT_CRED: Cred;
+declare function makeCred(uid: number, gid: number, groups?: number[], umask?: number): Cred;
+/** A file that does not live in the volume — `/proc/uptime`, `/dev/null`, … */
+interface VirtualNode {
+    kind: FileKind;
+    /** Permission bits only; the type bits are added from `kind`. */
+    mode: number;
+    uid?: number;
+    gid?: number;
+    size?: number;
+    mtimeMs?: number;
+    /** Symlink target, when `kind === "symlink"`. */
+    target?: string;
+    read?(): Uint8Array | string;
+    write?(data: Uint8Array, append: boolean): void;
+    /** Directory listing, when `kind === "directory"`. */
+    list?(): string[];
+}
+/**
+ * Supplies a subtree of synthetic files. `resolve` receives the path *relative*
+ * to `root` ("" means the mount point itself) and returns null for misses.
+ */
+interface VirtualProvider {
+    root: string;
+    resolve(rel: string): VirtualNode | null;
+    /**
+     * When true (the default) the provider owns its whole subtree and a miss is
+     * `ENOENT` — that is what `/proc` wants, so a dead pid does not resolve to a
+     * stale on-disk file. `/dev` and `/sys` set this to false so that synthetic
+     * nodes overlay a real directory users can still write into.
+     */
+    exclusive?: boolean;
+}
+interface WriteOptions {
+    mode?: number;
+    append?: boolean;
+    cred?: Cred;
+    /** Skip the permission check — used by kernel-internal writes. */
+    privileged?: boolean;
+}
+interface ResolveOptions {
+    cred?: Cred;
+    /** Follow a symlink in the final position. Off for `lstat`, `rm`, `chmod -h`. */
+    followFinal?: boolean;
+}
+declare class Vfs {
+    readonly volume: RuntimeVolume;
+    private readonly providers;
+    private nextVirtualIno;
+    private readonly virtualInos;
+    constructor(volume: RuntimeVolume);
+    addProvider(provider: VirtualProvider): void;
+    removeProvider(root: string): void;
+    /** The mount points currently served synthetically. */
+    get virtualRoots(): string[];
+    private lookupVirtual;
+    /** True when a miss at `abs` must be ENOENT rather than a volume lookup. */
+    private isUnderProvider;
+    /** Synthetic children a non-exclusive provider contributes to a directory. */
+    private virtualChildren;
+    private virtualIno;
+    /** True when `cred` may perform `mode` (R_OK/W_OK/X_OK) on a stat result. */
+    permitted(st: Stats, mode: number, cred: Cred): boolean;
+    private require;
+    /**
+     * Walk `abs` component by component, following symlinks and checking search
+     * (`+x`) permission on every directory along the way, exactly like `namei`.
+     *
+     * Returns the fully resolved absolute path. Does *not* require the final
+     * component to exist — callers decide whether a miss is fatal.
+     */
+    resolvePath(abs: string, opts?: ResolveOptions): string;
+    /** lstat that returns null instead of throwing, for internal probing. */
+    private tryLstat;
+    private readlinkRaw;
+    /** stat(2) — follows symlinks. */
+    stat(abs: string, opts?: {
+        cred?: Cred;
+    }): Stats;
+    /** lstat(2) — does not follow a symlink in the final position. */
+    lstat(abs: string): Stats;
+    private statFromVirtual;
+    exists(abs: string, cred?: Cred): boolean;
+    lexists(abs: string): boolean;
+    access(abs: string, mode?: number, cred?: Cred): void;
+    realpath(abs: string, cred?: Cred): string;
+    readFile(abs: string, cred?: Cred): Uint8Array;
+    readText(abs: string, cred?: Cred): string;
+    readdir(abs: string, cred?: Cred): string[];
+    /** True when the volume itself has a real directory at `abs`. */
+    private volumeHasDir;
+    readdirWithTypes(abs: string, cred?: Cred): DirEntry[];
+    readlink(abs: string, cred?: Cred): string;
+    writeFile(abs: string, data: Uint8Array | string, opts?: WriteOptions): void;
+    appendFile(abs: string, data: Uint8Array | string, opts?: WriteOptions): void;
+    truncate(abs: string, len?: number, cred?: Cred): void;
+    mkdir(abs: string, opts?: {
+        mode?: number;
+        recursive?: boolean;
+        cred?: Cred;
+    }): void;
+    private mkdirOne;
+    rmdir(abs: string, cred?: Cred): void;
+    unlink(abs: string, cred?: Cred): void;
+    /** Recursive delete, the engine behind `rm -r`. */
+    rmrf(abs: string, cred?: Cred): void;
+    private requireParentWrite;
+    rename(from: string, to: string, cred?: Cred): void;
+    copyFile(from: string, to: string, cred?: Cred): void;
+    symlink(target: string, linkPath: string, cred?: Cred): void;
+    link(existing: string, newPath: string, cred?: Cred): void;
+    chmod(abs: string, mode: number, cred?: Cred, follow?: boolean): void;
+    chown(abs: string, uid: number, gid: number, cred?: Cred, follow?: boolean): void;
+    utimes(abs: string, atimeMs: number, mtimeMs: number, cred?: Cred): void;
+    /** `touch` semantics: create when missing, otherwise bump the timestamps. */
+    touch(abs: string, cred?: Cred, timeMs?: number): void;
+    /** Depth-first walk yielding absolute paths. Symlinks are not followed. */
+    walk(abs: string, opts?: {
+        includeSelf?: boolean;
+        cred?: Cred;
+        maxDepth?: number;
+    }): Generator<string>;
+    /** Recursive copy used by `cp -r` and the container's `copyIn` helper. */
+    copyTree(from: string, to: string, cred?: Cred): void;
+    /** Free/used byte accounting for `df` and `du`. */
+    usage(abs?: string): {
+        files: number;
+        dirs: number;
+        bytes: number;
+    };
+}
+
+/**
+ * Byte streams for stdin/stdout/stderr, pipelines and redirections.
+ *
+ * Everything here is promise-based rather than Node-stream based: commands are
+ * plain async functions, a pipeline is just a chain of `Pipe` objects, and a
+ * closed reader turns further writes into `EPIPE` the way a real pipe does.
+ */
+
+interface OutputStream {
+    write(data: Uint8Array | string): void;
+    end(): void;
+    /** True once the far end went away — producers should stop. */
+    readonly closed: boolean;
+    isTTY: boolean;
+    /** Terminal width, when this is a TTY. */
+    columns?: number;
+    rows?: number;
+}
+interface InputStream {
+    /** Resolves to null at EOF. `size` is a maximum, not a guarantee. */
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    /** One line without its terminator; null at EOF. */
+    readLine(): Promise<string | null>;
+    /** Bytes already buffered, for non-blocking peeks. */
+    readonly available: number;
+    close(): void;
+    isTTY: boolean;
+    /**
+     * True when the far end is a live caller who may never signal EOF — a
+     * terminal, or the `stdin` pipe of `Container.spawn`. Programs that would
+     * otherwise slurp stdin before starting must not block on these.
+     */
+    readonly interactive?: boolean;
+}
+interface Stdio {
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+}
+/** An in-memory pipe: writable on one end, readable on the other. */
+declare class Pipe implements InputStream, OutputStream {
+    private chunks;
+    private buffered;
+    private writerClosed;
+    private readerClosed;
+    private wakers;
+    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.
+     */
+    private raw;
+    onRawMode?: (enabled: boolean) => void;
+    get rawMode(): boolean;
+    set rawMode(enabled: boolean);
+    columns: number | undefined;
+    rows: number | undefined;
+    get closed(): boolean;
+    get ended(): boolean;
+    get available(): number;
+    write(data: Uint8Array | string): void;
+    end(): void;
+    close(): void;
+    private wake;
+    private waitForData;
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    private lineRemainder;
+    readLine(): Promise<string | null>;
+    /** Seed the pipe with content then close it — handy for here-docs. */
+    static from(data: Uint8Array | string): Pipe;
+    static empty(): Pipe;
+}
+/** Discards everything; `/dev/null` as an output stream. */
+declare class NullOutput implements OutputStream {
+    readonly closed = false;
+    isTTY: boolean;
+    write(): void;
+    end(): void;
+}
+/** Always at EOF; `/dev/null` as an input stream. */
+declare class NullInput implements InputStream {
+    readonly available = 0;
+    isTTY: boolean;
+    read(): Promise<null>;
+    readAll(): Promise<Uint8Array>;
+    readLine(): Promise<null>;
+    close(): void;
+}
+/** Collects everything written, for `exec()` and command substitution. */
+declare class BufferSink implements OutputStream {
+    private readonly onWrite?;
+    private chunks;
+    private total;
+    private _closed;
+    isTTY: boolean;
+    columns: number | undefined;
+    rows: number | undefined;
+    constructor(onWrite?: ((chunk: Uint8Array) => void) | undefined);
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+    bytes(): Uint8Array;
+    text(): string;
+    get length(): number;
+    reset(): void;
+}
+/** Forwards each write to a callback — used to stream into a terminal. */
+declare class CallbackSink implements OutputStream {
+    private readonly sink;
+    private _closed;
+    isTTY: boolean;
+    columns: number | undefined;
+    rows: number | undefined;
+    constructor(sink: (text: string) => void, opts?: {
+        isTTY?: boolean;
+        columns?: number;
+        rows?: number;
+    });
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/** Fan-out, for `tee` and for `2>&1`-style duplication. */
+declare class TeeOutput implements OutputStream {
+    private readonly targets;
+    constructor(targets: OutputStream[]);
+    get closed(): boolean;
+    isTTY: boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/**
+ * Writes into a VFS file. Buffers in memory and flushes on every write so a
+ * long-running redirect (`cmd > log &`) is observable while it runs.
+ */
+declare class FileOutput implements OutputStream {
+    private readonly vfs;
+    private readonly path;
+    private readonly opts;
+    private _closed;
+    isTTY: boolean;
+    constructor(vfs: Vfs, path: string, opts?: {
+        append?: boolean;
+        cred?: Cred;
+        mode?: number;
+    });
+    get closed(): boolean;
+    write(data: Uint8Array | string): void;
+    end(): void;
+}
+/** Reads a VFS file as an input stream, for `cmd < file`. */
+declare class FileInput implements InputStream {
+    private pipe;
+    isTTY: boolean;
+    constructor(vfs: Vfs, path: string, cred?: Cred);
+    get available(): number;
+    read(size?: number): Promise<Uint8Array | null>;
+    readAll(): Promise<Uint8Array>;
+    readLine(): Promise<string | null>;
+    close(): void;
+}
+/** Convenience factory for a fully buffered stdio triple. */
+declare function captureStdio(stdin?: Uint8Array | string): {
+    stdio: Stdio;
+    out: BufferSink;
+    err: BufferSink;
+};
+
+/**
+ * The process table.
+ *
+ * Processes here are cooperative JavaScript tasks, not OS processes, but they
+ * carry the state Linux tooling expects to see: pid/ppid/pgid/sid, a state
+ * letter, credentials, a cwd, an environment, and an exit status that encodes
+ * the killing signal. `ps`, `kill`, `jobs` and `/proc` all read from here.
+ */
+
+type ProcessState = "R" | "S" | "D" | "T" | "Z" | "X";
+type Env = Record<string, string>;
+interface ProcessOptions {
+    argv: string[];
+    cwd: string;
+    env: Env;
+    cred: Cred;
+    ppid?: number;
+    pgid?: number;
+    sid?: number;
+    stdio?: Partial<Stdio>;
+    tty?: string | null;
+    /** Marks the process as a shell builtin frame rather than a real command. */
+    kind?: ProcessKind;
+}
+type ProcessKind = "init" | "shell" | "builtin" | "command" | "node" | "python" | "script";
+declare class Process {
+    readonly pid: number;
+    ppid: number;
+    pgid: number;
+    sid: number;
+    argv: string[];
+    cwd: string;
+    env: Env;
+    cred: Cred;
+    kind: ProcessKind;
+    tty: string | null;
+    state: ProcessState;
+    exitCode: number | null;
+    /** Signal that terminated the process, if any. */
+    termSignal: string | null;
+    readonly startTime: number;
+    cpuMs: number;
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+    readonly children: Set<Process>;
+    private readonly aborter;
+    private readonly exitWaiters;
+    private readonly signalHandlers;
+    constructor(opts: ProcessOptions);
+    /** Basename of argv[0], the `comm` field in `ps`. */
+    get comm(): string;
+    get cmdline(): string;
+    get running(): boolean;
+    get signal(): AbortSignal;
+    /** Seconds since the process started, for `ps etime`. */
+    get elapsedMs(): number;
+    setStdio(stdio: Partial<Stdio>): void;
+    onSignal(sig: string, handler: "default" | "ignore" | ((sig: string) => void)): void;
+    /**
+     * Deliver a signal. Returns true when the process handled or died from it.
+     * Catchable signals run the installed handler; uncatchable ones always kill.
+     */
+    deliver(sigSpec: string | number): boolean;
+    exit(code: number): void;
+    /** Remove from the table entirely — the parent has reaped us. */
+    reap(): void;
+    wait(): Promise<number>;
+}
+interface ProcessFilter {
+    pid?: number;
+    pgid?: number;
+    uid?: number;
+    comm?: string;
+    includeDead?: boolean;
+}
+declare class ProcessTable {
+    private readonly map;
+    create(opts: ProcessOptions): Process;
+    get(pid: number): Process | undefined;
+    has(pid: number): boolean;
+    remove(pid: number): void;
+    list(filter?: ProcessFilter): Process[];
+    get size(): number;
+    /** Send a signal to a pid, a process group (negative pid), or everything (-1). */
+    signal(target: number, sig: string | number): number;
+    /** Drop finished processes so the table does not grow without bound. */
+    gc(keepMs?: number): void;
+    clear(): void;
+}
+/** Reset the pid counter — used by tests and by `Container.reset()`. */
+declare function resetPidCounter(start?: number): void;
+
+/**
+ * The user and group database, backed by real `/etc/passwd`, `/etc/group` and
+ * `/etc/shadow` files so `cat /etc/passwd` and `id` agree with each other and
+ * `useradd` is just a file edit.
+ */
+
+interface PasswdEntry {
+    name: string;
+    passwd: string;
+    uid: number;
+    gid: number;
+    gecos: string;
+    home: string;
+    shell: string;
+}
+interface GroupEntry {
+    name: string;
+    passwd: string;
+    gid: number;
+    members: string[];
+}
+declare class UserDatabase {
+    private readonly vfs;
+    constructor(vfs: Vfs);
+    private readLines;
+    users(): PasswdEntry[];
+    groups(): GroupEntry[];
+    userByName(name: string): PasswdEntry | undefined;
+    userByUid(uid: number): PasswdEntry | undefined;
+    groupByName(name: string): GroupEntry | undefined;
+    groupByGid(gid: number): GroupEntry | undefined;
+    /** Accepts a name or a numeric id, the way `chown` arguments do. */
+    resolveUid(spec: string): number | undefined;
+    resolveGid(spec: string): number | undefined;
+    nameForUid(uid: number): string;
+    nameForGid(gid: number): string;
+    /** Every group id a user belongs to, primary first. */
+    groupsFor(name: string): number[];
+    credFor(nameOrUid: string | number, umask?: number): Cred;
+    nextFreeUid(min?: number, max?: number): number;
+    nextFreeGid(min?: number, max?: number): number;
+    addUser(entry: PasswdEntry, opts?: {
+        createHome?: boolean;
+        password?: string;
+    }): void;
+    addGroup(entry: GroupEntry): void;
+    removeUser(name: string): boolean;
+    removeGroup(name: string): boolean;
+    /** Add `user` to the supplementary members of `group`. */
+    addUserToGroup(user: string, group: string): boolean;
+}
+
+/**
+ * The contract every in-container program implements.
+ *
+ * A "binary" is an async function over an `ExecContext`, returning an exit
+ * code. The shell, the coreutils and the language runtimes all speak this one
+ * interface, which is what lets `node`, `python3` and `grep` sit side by side
+ * in `$PATH` and be pipelined together.
+ */
+
+interface ExecContext {
+    /** argv[0] is the command name as invoked. */
+    readonly argv: string[];
+    readonly stdin: InputStream;
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    readonly env: Env;
+    readonly cwd: string;
+    readonly vfs: Vfs;
+    readonly kernel: Kernel;
+    readonly proc: Process;
+    readonly cred: Cred;
+    readonly signal: AbortSignal;
+    /** Command name, for error prefixes. */
+    readonly name: string;
+    /** argv without argv[0]. */
+    readonly args: string[];
+    /** Resolve a possibly relative path against the process cwd. */
+    path(p: string): string;
+    /** Write to stdout verbatim. */
+    write(text: string | Uint8Array): void;
+    /** Write a line to stdout. */
+    line(text?: string): void;
+    /** Write `name: message` to stderr, followed by a newline. */
+    warn(message: string): void;
+    /** Report an error and produce an exit code in one expression. */
+    fail(message: string, code?: number): number;
+    /** Turn a caught filesystem error into the message coreutils would print. */
+    reportError(e: unknown, subject?: string): number;
+    /** Change the calling process's directory (used by `cd`, `chroot`). */
+    chdir(dir: string): void;
+}
+interface Command {
+    readonly name: string;
+    /** One-line summary shown by `help` and `whatis`. */
+    readonly summary?: string;
+    /** Usage string shown on `--help` and on a `UsageError`. */
+    readonly usage?: string;
+    /** Longer text shown by `man`. */
+    readonly manual?: string;
+    /** Aliases registered into the same PATH entry, e.g. `egrep` → `grep`. */
+    readonly aliases?: string[];
+    /** Where the binary claims to live, for `which` and `type`. */
+    readonly path?: string;
+    run(ctx: ExecContext): Promise<number> | number;
+}
+declare function defineCommand(cmd: Command): Command;
+declare class CommandRegistry {
+    private readonly commands;
+    register(cmd: Command): void;
+    registerAll(cmds: Command[]): void;
+    get(name: string): Command | undefined;
+    has(name: string): boolean;
+    names(): string[];
+    all(): Command[];
+    /** Default install location, used when populating `/bin` and `/usr/bin`. */
+    binPath(name: string): string;
+}
+interface ContextInit {
+    argv: string[];
+    proc: Process;
+    kernel: Kernel;
+    stdin?: InputStream;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: Env;
+    cwd?: string;
+    cred?: Cred;
+}
+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 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
+ * network.
+ */
+
+interface NetInterface {
+    name: string;
+    mac: string;
+    ipv4: string;
+    netmask: string;
+    broadcast?: string;
+    ipv6?: string;
+    mtu: number;
+    up: boolean;
+    loopback: boolean;
+    rxBytes: number;
+    txBytes: number;
+    rxPackets: number;
+    txPackets: number;
+}
+interface ListeningPort {
+    port: number;
+    proto: "tcp" | "udp";
+    address: string;
+    pid: number;
+    program: string;
+    since: number;
+}
+interface NetworkOptions {
+    /**
+     * Allow outbound requests to the real internet. When false (the default),
+     * `curl`/`wget`/`fetch` only reach servers running inside the container.
+     */
+    allowOutbound?: boolean;
+    /** Host allowlist applied when `allowOutbound` is on. `null` means any host. */
+    allowedHosts?: string[] | null;
+    /** Address handed to eth0. */
+    ipv4?: string;
+    gateway?: string;
+}
+declare class NetworkStack {
+    private readonly pod;
+    private readonly vfs;
+    private readonly ifaces;
+    private readonly listeners;
+    readonly options: Required<Pick<NetworkOptions, "allowOutbound">> & NetworkOptions;
+    constructor(pod: RuntimePod, vfs: Vfs, options?: NetworkOptions);
+    interfaces(): NetInterface[];
+    interface(name: string): NetInterface | undefined;
+    setInterfaceUp(name: string, up: boolean): boolean;
+    get gateway(): string;
+    /** Resolve through `/etc/hosts`; returns null when the name is not local. */
+    resolve(host: string): string | null;
+    isLocal(host: string): boolean;
+    registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
+    unregisterListener(port: number): void;
+    listening(): ListeningPort[];
+    /** 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>;
+    /** Wait for an in-container server to start answering on `port`. */
+    waitForPort(port: number, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<boolean>;
+    outboundAllowed(url: string): boolean;
+    procNetDev(): string;
+    procNetRoute(): string;
+    countTx(bytes: number, iface?: string): void;
+    countRx(bytes: number, iface?: string): void;
+}
+
+/**
+ * The kernel: the object that owns the filesystem, the process table, the user
+ * database and the executable namespace, and knows how to turn an `argv` into
+ * a running process.
+ *
+ * Executables in `$PATH` are real files. Built-in programs are installed as
+ * tiny stub files whose shebang points at the in-kernel implementation, so
+ * `ls -l /usr/bin/grep`, `which grep` and `file /usr/bin/grep` all behave, and
+ * a user-written script in `/usr/local/bin` is dispatched by exactly the same
+ * lookup path.
+ */
+
+interface KernelOptions {
+    pod: RuntimePod;
+    hostname?: string;
+    /** Login user for interactive sessions. Defaults to `root`. */
+    user?: string;
+    env?: Env;
+    /** Total "RAM" reported by `free`, `/proc/meminfo` and `top`. */
+    memoryBytes?: number;
+    /** Simulated CPU count for `nproc` and `/proc/cpuinfo`. */
+    cpus?: number;
+    now?: () => number;
+}
+interface RunOptions {
+    cwd?: string;
+    env?: Env;
+    cred?: Cred;
+    stdin?: InputStream | string | Uint8Array;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    ppid?: number;
+    pgid?: number;
+    kind?: ProcessKind;
+    tty?: string | null;
+    /** Wall-clock budget; the process is sent SIGKILL when it expires. */
+    timeoutMs?: number;
+}
+interface RunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    pid: number;
+    signal: string | null;
+    timedOut: boolean;
+}
+type ExecutableKind = "builtin" | "script" | "unknown";
+interface ResolvedExecutable {
+    kind: ExecutableKind;
+    /** Absolute path of the file that was found. */
+    path: string;
+    /** Present when `kind === "builtin"`. */
+    command?: Command;
+    /** Interpreter argv from a `#!` line, when `kind === "script"`. */
+    interpreter?: string[];
+}
+interface MountEntry {
+    device: string;
+    mountpoint: string;
+    fstype: string;
+    options: string;
+    totalBytes: number;
+}
+declare class Kernel {
+    readonly vfs: Vfs;
+    readonly procs: ProcessTable;
+    readonly commands: CommandRegistry;
+    readonly users: UserDatabase;
+    readonly pod: RuntimePod;
+    readonly bootTime: number;
+    readonly memoryBytes: number;
+    readonly cpus: number;
+    readonly now: () => number;
+    /** Populated by the network module once it is attached. */
+    net: NetworkStack;
+    /** init — pid 1, the ancestor of everything. */
+    readonly init: Process;
+    private readonly builtinByPath;
+    private readonly mounts;
+    private disposed;
+    private _current;
+    /**
+     * The process whose builtin is currently on the stack. `/proc/self` resolves
+     * through this. It is set around each dispatch, so a command that reads
+     * `/proc/self/...` synchronously always sees itself.
+     */
+    get currentProcess(): Process | null;
+    constructor(opts: KernelOptions);
+    get hostname(): string;
+    set hostname(value: string);
+    get uptimeMs(): number;
+    addMount(entry: MountEntry): void;
+    removeMount(mountpoint: string): boolean;
+    mountTable(): MountEntry[];
+    /**
+     * Install a command as a real file in `$PATH`. The file holds a shebang that
+     * points at the in-kernel dispatcher, which is what `resolve` looks for.
+     */
+    installCommand(cmd: Command, dir?: string): void;
+    installCommands(cmds: Command[], dir?: string): void;
+    /** Directories from `$PATH`, with a sane fallback. */
+    pathDirs(env: Env): string[];
+    /**
+     * Find `name` the way `execvp` does. Returns null when nothing matches.
+     */
+    resolveExecutable(name: string, cwd: string, env: Env, cred?: Cred): ResolvedExecutable | null;
+    /** `which`-style lookup that only reports the path. */
+    which(name: string, cwd: string, env: Env, cred?: Cred): string | null;
+    /** Every executable name reachable through `$PATH`, for tab completion. */
+    executableNames(env: Env, cred?: Cred): string[];
+    private toInputStream;
+    /**
+     * Create a process for `argv` and start it. Returns the process immediately;
+     * `proc.wait()` resolves with the exit code.
+     */
+    spawn(argv: string[], opts?: RunOptions): Process;
+    /** Run to completion and collect stdout/stderr. */
+    run(argv: string[], opts?: RunOptions): Promise<RunResult>;
+    /**
+     * Resolve `proc.argv` and execute it in-process. Interpreted scripts are
+     * dispatched by re-entering with the interpreter's argv, up to a small depth
+     * so a self-referential shebang cannot loop forever.
+     */
+    private dispatch;
+    /** Convenience for internal callers that just want the text output. */
+    capture(argv: string[], opts?: RunOptions): Promise<string>;
+    dispose(): void;
+    get isDisposed(): boolean;
+    assertActive(): void;
+}
+
+/** Shell syntax tree. Words stay raw; `expand.ts` interprets them. */
+type RedirectOp = ">" | ">>" | "<" | "<>" | ">|" | ">&" | "<&" | "&>" | "&>>" | "<<" | "<<<";
+interface Redirect {
+    op: RedirectOp;
+    /** Source fd, e.g. `2` in `2>file`. Defaults per operator. */
+    fd?: number;
+    /** Target word (a filename, an fd number, or here-doc/string content). */
+    target: string;
+    /** Populated for `<<`. */
+    heredoc?: {
+        body: string;
+        expand: boolean;
+    };
+}
+interface Assignment {
+    name: string;
+    /** Raw value word; undefined for `name=` with nothing after it. */
+    value: string;
+    /** `name+=value`. */
+    append: boolean;
+    /** `name=(a b c)` array literal. */
+    arrayWords?: string[];
+}
+type Node = ListNode | PipelineNode | SimpleCommandNode | SubshellNode | GroupNode | IfNode | ForNode | ForArithNode | WhileNode | CaseNode | FunctionNode | ArithCommandNode | CondNode;
+type ListOperator = ";" | "&" | "&&" | "||";
+interface ListItem {
+    node: Node;
+    /** Operator that *follows* this item. */
+    op: ListOperator;
+}
+interface ListNode {
+    type: "list";
+    items: ListItem[];
+}
+interface PipelineNode {
+    type: "pipeline";
+    commands: Node[];
+    /** `! cmd` inverts the exit status. */
+    negated: boolean;
+    /** `cmd |& next` pipes stderr too. */
+    stderrToo: boolean[];
+    /** `time cmd` */
+    timed?: boolean;
+}
+interface SimpleCommandNode {
+    type: "command";
+    assignments: Assignment[];
+    words: string[];
+    redirects: Redirect[];
+}
+interface SubshellNode {
+    type: "subshell";
+    body: Node;
+    redirects: Redirect[];
+}
+interface GroupNode {
+    type: "group";
+    body: Node;
+    redirects: Redirect[];
+}
+interface IfClause {
+    condition: Node;
+    body: Node;
+}
+interface IfNode {
+    type: "if";
+    clauses: IfClause[];
+    elseBody?: Node;
+    redirects: Redirect[];
+}
+interface ForNode {
+    type: "for";
+    name: string;
+    /** Absent means `for x; do` which iterates `"$@"`. */
+    words?: string[];
+    body: Node;
+    redirects: Redirect[];
+    /** `select` shares the same shape. */
+    select?: boolean;
+}
+interface ForArithNode {
+    type: "for-arith";
+    init: string;
+    condition: string;
+    step: string;
+    body: Node;
+    redirects: Redirect[];
+}
+interface WhileNode {
+    type: "while";
+    condition: Node;
+    body: Node;
+    until: boolean;
+    redirects: Redirect[];
+}
+interface CaseItem {
+    patterns: string[];
+    body: Node | null;
+    /** `;;` stops, `;&` falls through, `;;&` retests. */
+    terminator: ";;" | ";&" | ";;&";
+}
+interface CaseNode {
+    type: "case";
+    word: string;
+    items: CaseItem[];
+    redirects: Redirect[];
+}
+interface FunctionNode {
+    type: "function";
+    name: string;
+    body: Node;
+    redirects: Redirect[];
+}
+interface ArithCommandNode {
+    type: "arith";
+    expression: string;
+    redirects: Redirect[];
+}
+/** `[[ ... ]]` — parsed as a small expression tree of its own. */
+type CondExpr = {
+    type: "unary";
+    op: string;
+    operand: string;
+} | {
+    type: "binary";
+    op: string;
+    left: string;
+    right: string;
+} | {
+    type: "not";
+    operand: CondExpr;
+} | {
+    type: "and";
+    left: CondExpr;
+    right: CondExpr;
+} | {
+    type: "or";
+    left: CondExpr;
+    right: CondExpr;
+} | {
+    type: "word";
+    value: string;
+};
+interface CondNode {
+    type: "cond";
+    expression: CondExpr;
+    redirects: Redirect[];
+}
+
+/**
+ * Shell variable table: scalars, indexed arrays, export/readonly attributes,
+ * and the function-local scoping that `local` introduces.
+ */
+interface VarAttributes {
+    exported?: boolean;
+    readonly?: boolean;
+    integer?: boolean;
+    /** `declare -l` / `-u` case folding. */
+    lower?: boolean;
+    upper?: boolean;
+}
+interface VarEntry extends VarAttributes {
+    value: string;
+    array?: string[];
+    assoc?: Map<string, string>;
+}
+declare class Variables {
+    /** Innermost scope last; index 0 is the global scope. */
+    private readonly scopes;
+    constructor(initial?: Record<string, string>);
+    pushScope(): void;
+    popScope(): void;
+    get depth(): number;
+    private find;
+    has(name: string): boolean;
+    get(name: string): string | undefined;
+    entry(name: string): VarEntry | undefined;
+    getArray(name: string): string[] | undefined;
+    isArray(name: string): boolean;
+    set(name: string, value: string, attrs?: VarAttributes): void;
+    /** Declare in the innermost scope, shadowing outer definitions (`local`). */
+    setLocal(name: string, value: string, attrs?: VarAttributes): void;
+    setArray(name: string, values: string[], attrs?: VarAttributes): void;
+    setIndex(name: string, index: number, value: string): void;
+    append(name: string, value: string): void;
+    unset(name: string): boolean;
+    export(name: string, exported?: boolean): void;
+    markReadonly(name: string): void;
+    names(): string[];
+    /** The environment handed to a child process. */
+    environment(): Record<string, string>;
+    /** Every variable with its attributes, for `declare -p` / `set`. */
+    all(): Array<{
+        name: string;
+        entry: VarEntry;
+    }>;
+}
+
+/**
+ * Word expansion, in the order POSIX specifies:
+ *
+ *   brace → tilde → parameter/command/arithmetic → field splitting →
+ *   pathname → quote removal
+ *
+ * The tricky part is that only text produced by *unquoted* expansions may be
+ * field-split, and only unquoted text may be globbed. Each fragment therefore
+ * carries `split` and `glob` flags through the pipeline, and quote removal is
+ * the last thing that happens.
+ */
+
+interface ExpandContext {
+    vars: Variables;
+    /** `$1`, `$2`, … */
+    positional: string[];
+    /** `$0` */
+    scriptName: string;
+    /** `$?` */
+    lastStatus: number;
+    /** `$$` */
+    shellPid: number;
+    /** `$!` */
+    lastBackgroundPid: number;
+    /** `$-` */
+    optionFlags: string;
+    cwd: string;
+    vfs: Vfs;
+    cred: Cred;
+    /** Home directory lookup for `~user`. */
+    homeFor(user: string): string | undefined;
+    /** Runs a command substitution and returns its stdout. */
+    runSubstitution(command: string): Promise<string>;
+    /** Materialises `<(cmd)` / `>(cmd)` as a path. Optional. */
+    processSubstitution?(command: string, direction: "in" | "out"): Promise<string>;
+    /** `set -u` */
+    nounset?: boolean;
+    /** `set -f` */
+    noglob?: boolean;
+    /** Extended globbing (`shopt -s extglob`). */
+    extglob?: boolean;
+    /** Include dotfiles in globs (`shopt -s dotglob`). */
+    dotglob?: boolean;
+    /** Leave an unmatched glob as-is (bash default) or drop it (`nullglob`). */
+    nullglob?: boolean;
+    /** Error out on an unmatched glob (`failglob`). */
+    failglob?: boolean;
+}
+/** Full expansion of a list of words, as used for command arguments. */
+declare function expandWords(words: string[], ctx: ExpandContext): Promise<string[]>;
+/** Expand one word into zero or more fields. */
+declare function expandWord(word: string, ctx: ExpandContext): Promise<string[]>;
+/** `a{b,c}d` → `abd acd`; `{1..5}` and `{a..e}` sequences too. */
+declare function braceExpand(word: string): string[];
+declare function shellQuote(value: string): string;
+
+/**
+ * The shell interpreter.
+ *
+ * Walks the syntax tree, applies redirections, wires pipelines together, and
+ * dispatches each simple command to a function, a builtin, or the kernel's
+ * executable lookup — in that order, which is the order bash uses.
+ */
+
+interface ShellIO {
+    stdin: InputStream;
+    stdout: OutputStream;
+    stderr: OutputStream;
+}
+interface ShellOptions {
+    /** `set -e` */
+    errexit: boolean;
+    /** `set -u` */
+    nounset: boolean;
+    /** `set -x` */
+    xtrace: boolean;
+    /** `set -v` */
+    verbose: boolean;
+    /** `set -f` */
+    noglob: boolean;
+    /** `set -o pipefail` */
+    pipefail: boolean;
+    /** `set -n` */
+    noexec: boolean;
+    /** `set -m` */
+    monitor: boolean;
+    /** `set -C` */
+    noclobber: boolean;
+    /** `set -a` */
+    allexport: boolean;
+    /** Interactive shells print prompts and keep history. */
+    interactive: boolean;
+    /** Login shells source `/etc/profile`. */
+    login: boolean;
+}
+interface Job {
+    id: number;
+    pgid: number;
+    command: string;
+    state: "running" | "done" | "stopped";
+    exitCode: number | null;
+    promise: Promise<number>;
+    pids: number[];
+}
+declare class ShellExit {
+    readonly code: number;
+    constructor(code: number);
+}
+interface ShellInit {
+    kernel: Kernel;
+    proc: Process;
+    cwd?: string;
+    env?: Record<string, string>;
+    cred?: Cred;
+    options?: Partial<ShellOptions>;
+    positional?: string[];
+    scriptName?: string;
+}
+declare class Shell {
+    readonly kernel: Kernel;
+    readonly proc: Process;
+    readonly vars: Variables;
+    readonly functions: Map<string, Node>;
+    readonly aliases: Map<string, string>;
+    readonly traps: Map<string, string>;
+    readonly dirStack: string[];
+    readonly jobs: Job[];
+    readonly history: string[];
+    options: ShellOptions;
+    shopts: Set<string>;
+    positional: string[];
+    scriptName: string;
+    lastStatus: number;
+    lastBackgroundPid: number;
+    cwd: string;
+    cred: Cred;
+    /** Pipeline exit statuses, exposed as `PIPESTATUS`. */
+    pipeStatus: number[];
+    private nextJobId;
+    private functionDepth;
+    private tempFileCounter;
+    private exiting;
+    constructor(init: ShellInit);
+    /** Parse and run a script fragment. Returns the last exit status. */
+    execute(source: string, io: ShellIO): Promise<number>;
+    /** Signal the current terminal pipeline without terminating the interactive shell. */
+    interruptForeground(signal: string, stdin: InputStream): void;
+    get isExiting(): boolean;
+    /** True when `source` is not yet a complete command (for REPL continuation). */
+    static isIncomplete(source: string): boolean;
+    expandContext(): ExpandContext;
+    optionFlagString(): string;
+    /** Run `command` in a subshell and return its stdout. */
+    captureSubshell(command: string): Promise<string>;
+    /** `<(cmd)` — run the command now and hand back a path holding its output. */
+    private makeProcessSubstitution;
+    /** A copy that shares nothing mutable with this shell. */
+    fork(): Shell;
+    private currentIO;
+    run(node: Node, io: ShellIO): Promise<number>;
+    private runList;
+    /** Skip past short-circuited members of an `&&`/`||` chain. */
+    private skipChain;
+    private runPipeline;
+    /**
+     * Every stage of a pipeline runs in its own subshell in bash. Sharing the
+     * variable table would let `echo x | read v` leak `v` into the parent.
+     */
+    private forkForPipeline;
+    private reportTime;
+    private startBackgroundJob;
+    private runSubshell;
+    private runGroup;
+    private runIf;
+    /** Conditions are exempt from `set -e`. */
+    private runCondition;
+    private runFor;
+    private runSelect;
+    private runForArith;
+    private runWhile;
+    private runCase;
+    private runFunctionDefinition;
+    private runArithCommand;
+    private runCond;
+    private evalCond;
+    private runSimpleCommand;
+    private reportCommandError;
+    /** One level of alias substitution on the command word. */
+    private substituteAlias;
+    private invoke;
+    private callFunction;
+    private runExternal;
+    /** `VAR=x cmd` — set for the duration, then restore. */
+    private applyTemporaryAssignments;
+    applyAssignment(assignment: SimpleCommandNode["assignments"][number], exported: boolean): Promise<void>;
+    applyRedirects(redirects: Redirect[], io: ShellIO): Promise<{
+        io: ShellIO;
+        cleanup: () => void;
+    }>;
+    private openInput;
+    private openOutput;
+    private expandHeredoc;
+    setTrap(signal: string, action: string): void;
+    runTrap(signal: string, io: ShellIO): Promise<void>;
+    changeDirectory(target: string): void;
+    throwBreak(levels: number): never;
+    throwContinue(levels: number): never;
+    throwReturn(code: number): never;
+    throwExit(code: number): never;
+    addJob(job: Job): void;
+    reapJobs(): Job[];
+}
+
+/**
+ * The CPython runtime: Pyodide, wired to the container the same way
+ * the other runtimes are — filesystem, argv, environment and standard streams.
+ *
+ * This is real CPython, so `sqlite3`, `dataclasses`, `decimal`, `typing` and
+ * the rest of the standard library are present, and `micropip` can install
+ * pure-Python wheels.
+ *
+ * CPython keeps its own library inside the Emscripten filesystem, so:
+ *
+ *  - the container is mounted subtree by subtree rather than over `/`, so
+ *    Pyodide's standard-library files survive;
+ *  - an interpreter costs roughly a second and a half to start, so one is kept
+ *    per container and each program is run in a fresh namespace instead.
+ */
+
+interface CPythonOptions {
+    /**
+     * Where Pyodide's own assets live.
+     *
+     * Node resolves them from the installed package, so this is only needed in a
+     * browser, where they are served or taken from a CDN.
+     */
+    indexURL?: string;
+    /**
+     * URL of the Pyodide ES module, for hosts that cannot resolve the package by
+     * name — a browser without a bundler, typically.
+     */
+    moduleURL?: string;
+}
+declare function configureCPython(options?: CPythonOptions): void;
+/** True when this host can start CPython at all. */
+declare function isCPythonAvailable(): Promise<boolean>;
+
+/** The existing Python CLI surface, backed exclusively by CPython/Pyodide. */
+
+declare const PYTHON_VERSION = "3.13";
+interface PythonOptions {
+    /** Where Pyodide's assets live; only a browser normally needs this. */
+    indexURL?: string;
+    /** URL of pyodide.mjs, for browsers without package resolution. */
+    pyodideURL?: string;
+}
+declare function configurePython(options?: PythonOptions): void;
+declare const isPythonAvailable: typeof isCPythonAvailable;
+
+/**
+ * A promise-based filesystem façade for host code, shaped like `fs/promises`
+ * so it reads naturally from the outside.
+ */
+
+/** Data accepted by the host-facing filesystem API.
+ *
+ * `Blob` includes browser `File` objects, which is what an `<input
+ * type="file">` returns. The bytes are copied into the container; no host
+ * filesystem path is ever resolved by the sandbox.
+ */
+type FileData = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+declare class ContainerFs {
+    private readonly kernel;
+    constructor(kernel: Kernel);
+    private get vfs();
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, encoding: "utf8" | "utf-8"): Promise<string>;
+    writeFile(path: string, data: FileData, opts?: {
+        mode?: number;
+    }): Promise<void>;
+    appendFile(path: string, data: FileData): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdir(path: string, opts: {
+        withFileTypes: true;
+    }): Promise<DirEntry[]>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    rm(path: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    copyFile(from: string, to: string): Promise<void>;
+    stat(path: string): Promise<Stats>;
+    lstat(path: string): Promise<Stats>;
+    exists(path: string): Promise<boolean>;
+    symlink(target: string, link: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    /** Every path beneath `root`, depth-first. */
+    walk(root?: string): Promise<string[]>;
+    /** Total bytes and file counts, as `df` reports them. */
+    usage(root?: string): Promise<{
+        files: number;
+        dirs: number;
+        bytes: number;
+    }>;
+    /** Read many files at once, keyed by path. */
+    readAll(paths: string[]): Promise<Record<string, string>>;
+    /** Write a whole map of files, creating parents. */
+    writeAll(files: Record<string, FileData>, opts?: {
+        cwd?: string;
+    }): Promise<void>;
+}
+
+/**
+ * A stateful shell session — `cd`, variables, functions and history persist
+ * across calls, the way a terminal does. `Container.exec` is deliberately
+ * stateless; this is the other half.
+ */
+
+interface SessionInit {
+    cwd: string;
+    env: Record<string, string>;
+    cred: Cred;
+    hooks?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    };
+}
+interface SessionRunOptions {
+    stdin?: string | Uint8Array | InputStream;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    timeoutMs?: number;
+    /** Present the session as attached to a terminal. */
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+}
+interface SessionResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    output: string;
+}
+declare class Session {
+    private readonly kernel;
+    readonly shell: Shell;
+    readonly proc: Process;
+    private closed;
+    constructor(kernel: Kernel, init: SessionInit);
+    private readonly hooks;
+    get cwd(): string;
+    get env(): Record<string, string>;
+    get history(): string[];
+    /** Run a command line, keeping every side effect for the next call. */
+    run(command: string, opts?: SessionRunOptions): Promise<SessionResult>;
+    /** Stream a long-running command; resolves when it exits. */
+    stream(command: string, handlers?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    }): Promise<number>;
+    /** Feed the session an arbitrary output stream, for terminal integration. */
+    pipeTo(command: string, stdout: OutputStream, stderr: OutputStream, stdin?: InputStream): Promise<number>;
+    /** True when the last command asked the shell to exit. */
+    get isExiting(): boolean;
+    close(): void;
+}
+
+/**
+ * The public surface: a Linux-like container you can boot inside any Node
+ * process, run commands in, and throw away.
+ *
+ * ```ts
+ * const box = await createContainer({ files: { "/app/index.js": "console.log(1)" } });
+ * await box.exec("node /app/index.js");
+ * ```
+ */
+
+interface ContainerOptions {
+    /**
+     * Files to seed the filesystem with, keyed by absolute (or `cwd`-relative)
+     * path. Parent directories are created automatically — this is the fast way
+     * to drop a whole project in and run it.
+     */
+    files?: Record<string, string | Uint8Array>;
+    /** Directory `files` keys are resolved against, and the default cwd. Default `/`. */
+    cwd?: string;
+    hostname?: string;
+    /**
+     * Login user. `"root"` (default) runs privileged; any other name is created
+     * with uid 1000 and sudo rights. Pass `null` for a root-only image.
+     */
+    user?: string | null;
+    env?: Record<string, string>;
+    /** RAM reported by `free`, `top` and `/proc/meminfo`. Default 2 GiB. */
+    memory?: number;
+    /** CPU count reported by `nproc` and `/proc/cpuinfo`. Default 4. */
+    cpus?: number;
+    network?: NetworkOptions;
+    timezone?: string;
+    /** Default wall-clock limit for `exec`. Omit for no limit. */
+    timeoutMs?: number;
+    /** Called for every byte any command writes to stdout, across the container. */
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    /** Invoked when an in-container HTTP server starts listening. */
+    onServerReady?: (port: number, url: string) => void;
+    /**
+     * Run on a JavaScript runtime you booted yourself.
+     *
+     * The container boots a {@link LocalRuntimePod} when this is omitted, which
+     * is what almost every caller wants. Pass one to share a single runtime
+     * across containers, to seed it differently, or to substitute an
+     * implementation of your own — anything satisfying {@link RuntimePod} works.
+     *
+     * ```ts
+     * const pod = await LocalRuntimePod.boot({ workdir: "/app" });
+     * const box = await createContainer({ pod, cwd: "/app" });
+     * ```
+     */
+    pod?: RuntimePod;
+    /**
+     * Where guest programs run.
+     *
+     * `"auto"` (the default) tries the worker runtime and reports any fallback.
+     * `"worker"` requires a working guest worker and shared-memory channel: boot
+     * rejects with the cause if either is unavailable, rather than letting
+     * synchronous child-process calls fail later. `"realm"` opts out explicitly.
+     * Processes requiring host-native modules can still run in the host realm.
+     */
+    isolation?: "auto" | "worker" | "realm";
+    /** Receives the reason for an automatic fallback; defaults to console.warn. */
+    onRuntimeFallback?: (error: Error) => void;
+    /**
+     * Where to load the guest worker bundle from.
+     *
+     * Defaults to the copy shipped beside the main bundle, which is what a
+     * published package wants. Worth setting when a bundler has moved or
+     * rewritten it — or when running from source, where the built file is the
+     * only one a Worker can load.
+     */
+    workerUrl?: string | URL;
+    /** Python runtime settings; a browser host uses this to locate the wasm. */
+    python?: PythonOptions;
+}
+interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Run as this user instead of the container default. */
+    user?: string;
+    stdin?: string | Uint8Array;
+    /** Stream output as it is produced, in addition to buffering it. */
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    timeoutMs?: number;
+    /** Report the command as running on a terminal (affects `ls` colour, `-t`). */
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+}
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** stdout and stderr interleaved in write order. */
+    output: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+interface SpawnHandle {
+    pid: number;
+    stdin: Pipe;
+    stdout: Pipe;
+    stderr: Pipe;
+    /** Resolves with the exit code. */
+    wait(): Promise<number>;
+    kill(signal?: string): void;
+    readonly exitCode: number | null;
+}
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    bytes: Uint8Array;
+    json<T = unknown>(): T;
+}
+declare class Container {
+    readonly kernel: Kernel;
+    readonly pod: RuntimePod;
+    readonly fs: ContainerFs;
+    readonly net: NetworkStack;
+    private readonly defaults;
+    private readonly hooks;
+    private disposed;
+    private defaultSession;
+    private readonly restoreNodeChildProcessBridge;
+    private constructor();
+    static create(opts?: ContainerOptions): Promise<Container>;
+    /**
+     * Drop a map of files into the container. Keys may be absolute or relative
+     * to `opts.cwd`; parent directories are created as needed.
+     */
+    mount(files: Record<string, string | Uint8Array>, opts?: {
+        cwd?: string;
+        mode?: number;
+    }): this;
+    private mountSync;
+    /** Copy a directory tree from the host filesystem into the container. */
+    copyIn(hostPath: string, containerPath: string): Promise<void>;
+    /** Copy a file or directory out of the container onto the host. */
+    copyOut(containerPath: string, hostPath: string): Promise<void>;
+    /** Run a shell command line and collect its output. */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /** Run a program directly, without a shell parsing the arguments. */
+    run(argv: string[], opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Start a command and get streams back, for long-running processes such as a
+     * dev server that you want to watch and later kill.
+     */
+    spawn(command: string, opts?: ExecOptions): SpawnHandle;
+    /**
+     * A stateful shell session: `cd`, variables and functions persist between
+     * calls, the way a terminal behaves.
+     */
+    session(opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        user?: string;
+    }): Session;
+    /** The container-wide session used by `shell()` shorthand helpers. */
+    get shell(): Session;
+    private makeStdio;
+    /** Send an HTTP request to a server running inside the container. */
+    request(port: number, init?: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+        body?: string | Uint8Array;
+    }): Promise<HttpResponse>;
+    /**
+     * Deliver a request whose body is bytes, without letting them become text.
+     *
+     * 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
+     * longer decodes, with no error raised anywhere.
+     *
+     * Its own dispatcher one layer down does preserve bytes, so a binary body
+     * goes straight there. This reaches past the published surface deliberately,
+     * so it is written to fail soft: any shape it does not recognise returns
+     * `null` and the caller falls back to the ordinary path, which is exactly
+     * the behaviour that existed before. Text bodies never come through here.
+     */
+    private dispatchBinary;
+    /** Wait until something inside the container answers on `port`. */
+    waitForPort(port: number, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<boolean>;
+    /**
+     * Bridge a container port onto a real host port, so a browser (or anything
+     * else on your machine) can reach a dev server running inside the sandbox.
+     */
+    expose(port: number, opts?: {
+        hostPort?: number;
+        hostname?: string;
+    }): Promise<{
+        url: string;
+        port: number;
+        close(): Promise<void>;
+    }>;
+    /** A serialisable snapshot of the whole filesystem. */
+    snapshot(opts?: {
+        shallow?: boolean;
+    }): unknown;
+    restore(snapshot: unknown): Promise<void>;
+    get hostname(): string;
+    get user(): string;
+    get cwd(): string;
+    get env(): Record<string, string>;
+    private assertActive;
+    /** Tear down every process and release the runtime pod. */
+    dispose(): void;
+    get isDisposed(): boolean;
+}
+/** Boot a container. The one function most callers need. */
+declare function createContainer(opts?: ContainerOptions): Promise<Container>;
+
+export { type ProcessKind as $, type KernelOptions as A, BufferSink as B, Container as C, type DirEntry as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, type MountEntry as M, type Node as N, type OutputStream as O, type NetInterface as P, type NetworkOptions as Q, type RuntimeVolume as R, Shell as S, NetworkStack as T, NullInput as U, Vfs as V, NullOutput as W, PYTHON_VERSION as X, type PasswdEntry as Y, Pipe as Z, Process as _, type ShellIO as a, type ProcessOptions as a0, type ProcessState as a1, ProcessTable as a2, type PythonOptions as a3, ROOT_CRED as a4, type ResolvedExecutable as a5, type RunOptions as a6, type RunResult as a7, type RuntimeProcessManager as a8, type RuntimeProcessResult as a9, isCPythonAvailable as aA, isPythonAvailable as aB, makeCred as aC, octalMode as aD, parseUmask as aE, resetPidCounter as aF, shellQuote as aG, type SessionInit as aa, type SessionResult as ab, type SessionRunOptions as ac, ShellExit as ad, type ShellInit as ae, type ShellOptions as af, type SpawnHandle as ag, Stats as ah, type Stdio as ai, TeeOutput as aj, UserDatabase as ak, Variables as al, type VirtualNode as am, type VirtualProvider as an, type WriteOptions as ao, applyChmod as ap, braceExpand as aq, captureStdio as ar, configureCPython as as, configurePython as at, createChildProcessModule as au, createContext as av, defineCommand as aw, expandWord as ax, expandWords as ay, formatMode as az, Session as b, type Cred as c, type Command as d, type VolumeStat as e, type VolumeStats as f, type RuntimeHttpResponse as g, type SpawnChild as h, type SyncSpawn as i, type RuntimePod as j, type RuntimePackageInstaller as k, type ChildSpawnConfig as l, type ChildHandle as m, type RuntimeProcess as n, createContainer as o, type CPythonOptions as p, CallbackSink as q, CommandRegistry as r, ContainerFs as s, type ContainerOptions as t, type ContextInit as u, type Env as v, type ExecOptions as w, type ExecResult as x, FileInput as y, FileOutput as z };