rightsize 0.1.0

package/dist/core/generic-container.js

@@ -0,0 +1,385 @@
+import { FreePorts } from "./free-ports.js";
+import { RunId } from "./run-id.js";
+import { Network } from "./network.js";
+import { PortBindConflictError } from "./errors.js";
+import { Wait } from "./wait.js";
+import { registerSyncCleanup, unregisterSyncCleanup } from "./cleanup.js";
+import { Backends } from "./backends.js";
+const MAX_START_ATTEMPTS = 5;
+let sequence = 0;
+function nextSequence() {
+    sequence += 1;
+    return sequence;
+}
+/** Typed-first, string-fallback classification: walk the cause chain for a typed conflict, else match the daemon's own wording. */
+function isPortBindConflict(err) {
+    let current = err;
+    const seen = new Set();
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof PortBindConflictError) {
+            return true;
+        }
+        if (current instanceof Error) {
+            const message = current.message.toLowerCase();
+            if (message.includes("address already in use") || message.includes("already allocated")) {
+                return true;
+            }
+            current = current.cause;
+            continue;
+        }
+        break;
+    }
+    return false;
+}
+async function swallow(fn) {
+    try {
+        await fn();
+    }
+    catch {
+        // Best-effort teardown: never let a stop/remove failure escape.
+    }
+}
+/**
+ * The builder, launcher, and lifecycle guard for a single container — the
+ * one class every module (`RedisContainer`, `PostgresContainer`, …)
+ * subclasses, and the type you reach for directly for any image without a
+ * dedicated module.
+ *
+ * The instance itself is the guard: after `start()` it implements
+ * `Symbol.asyncDispose`, so `await using c = await new GenericContainer(img).start()`
+ * tears the container down at scope exit — the direct analog of the Kotlin
+ * `AutoCloseable` and Rust's RAII guard, expressed with TC39 explicit
+ * resource management. Prefer `await using` in tests; use explicit
+ * `start()`/`stop()` where a `using` scope can't span a framework hook
+ * (Jest/Vitest `beforeAll`/`afterAll`, `node:test`'s `before`/`after`).
+ *
+ * Builder methods (`withEnv`, `withExposedPorts`, …) mutate and return
+ * `this` for chaining; none of them perform I/O. All I/O happens in
+ * `start()`, `stop()`, `exec()`, `logs()`, and `followOutput()`.
+ */
+export class GenericContainer {
+    image;
+    envPairs = [];
+    exposedPorts = [];
+    command;
+    network;
+    aliasNames = [];
+    mounts = [];
+    waitStrategy = Wait.forListeningPort();
+    memoryLimitMb;
+    backendOverride;
+    handle;
+    backend;
+    mappedPorts = new Map();
+    running = false;
+    /** Builds against `image` (e.g. `"redis:8.6-alpine"`); no I/O happens until `start()`. */
+    constructor(image) {
+        this.image = image;
+    }
+    /** Convenience: `new GenericContainer(image).start()`. */
+    static async start(image) {
+        return new GenericContainer(image).start();
+    }
+    /** Sets an environment variable visible to the workload. Last-write-wins if called again with the same key; insertion order is otherwise preserved. */
+    withEnv(key, value) {
+        // Last-write-wins, insertion-ordered: drop any prior entry for this key
+        // before pushing, so re-setting the same key doesn't duplicate it while
+        // still preserving the position of first-set for untouched keys.
+        this.envPairs = this.envPairs.filter(([k]) => k !== key);
+        this.envPairs.push([key, value]);
+        return this;
+    }
+    /** Publishes these guest ports to pre-allocated host ports (see `FreePorts`); read back with `getMappedPort`. */
+    withExposedPorts(...ports) {
+        this.exposedPorts.push(...ports);
+        return this;
+    }
+    /** Overrides the image's default ENTRYPOINT/CMD. Omit this call entirely to run the image unmodified. */
+    withCommand(...cmd) {
+        this.command = cmd;
+        return this;
+    }
+    /** Joins a `Network`, making this container reachable from (and to) its running siblings by alias. */
+    withNetwork(net) {
+        this.network = net;
+        return this;
+    }
+    /** Names this container answers to on its network — resolved via `Network.resolve(alias, port)` by other members. */
+    withNetworkAliases(...names) {
+        this.aliasNames.push(...names);
+        return this;
+    }
+    /** Copies a host file into the guest before boot, at `guestPath`. Read-only is enforced on docker; advisory only on msb (current microsandbox releases do not enforce guest-side read-only mounts). */
+    withCopyFileToContainer(file, guestPath) {
+        this.mounts.push({ hostPath: file.path, guestPath, readOnly: true });
+        return this;
+    }
+    /** Sets the readiness check `start()` waits on before returning. Defaults to `Wait.forListeningPort()`. */
+    waitingFor(strategy) {
+        this.waitStrategy = strategy;
+        return this;
+    }
+    /** Raises the container's memory ceiling (in MB) above the backend default — required by several JVM-heavy modules; see each module's own doc for its pin. */
+    withMemoryLimit(megabytes) {
+        this.memoryLimitMb = megabytes;
+        return this;
+    }
+    /** Test/advanced seam: pin the backend instead of resolving `Backends.active()`. */
+    withBackend(backend) {
+        this.backendOverride = backend;
+        return this;
+    }
+    /** Module hook: override to adjust the spec once mapped host ports are known (e.g. advertised listeners). */
+    customizeSpec(spec, _mapped) {
+        return spec;
+    }
+    /** Module hook: runs after the container is ready (e.g. `rs.initiate` for a Mongo replica set). */
+    containerIsStarted() {
+        return Promise.resolve();
+    }
+    /**
+     * Module hook: runs the instant `start()` has resolved a backend — before
+     * `ensureNetwork`, port allocation, or the container is created/booted at
+     * all. The one hook that lets a module reject a backend-incompatible
+     * request (e.g. `FlinkContainer.withTaskManager()` on msb) without paying
+     * for a boot first. `containerIsStarted()` (above) fires much later, after
+     * this container is already fully up — fine for post-readiness setup, but
+     * too late to fail fast on a capability the backend never had.
+     */
+    containerIsStarting(_backend) {
+        return Promise.resolve();
+    }
+    /**
+     * Module hook: the backend this container actually started against (only
+     * valid once `start()` has resolved it — i.e. from within
+     * `containerIsStarted()` or later). Lets a module's post-start hook branch
+     * on backend capability, e.g. `FlinkContainer.withTaskManager()` throwing a
+     * typed `UnsupportedByBackendError` on msb instead of attempting a
+     * network-link topology the exec-tunnel emulation can't carry.
+     */
+    currentBackend() {
+        return this.requireHandle().backend;
+    }
+    resolveBackend() {
+        return this.backendOverride ?? Backends.active();
+    }
+    buildSpec(name, ports) {
+        const spec = {
+            name,
+            image: this.image,
+            env: this.envPairs.map(([k, v]) => [k, v]),
+            command: this.command,
+            ports: this.exposedPorts.map((guestPort) => ({
+                hostPort: ports.get(guestPort) ?? (() => {
+                    throw new Error(`no allocated host port for guest port ${guestPort}`);
+                })(),
+                guestPort,
+            })),
+            mounts: this.mounts,
+            networkId: this.network?.id,
+            aliases: this.aliasNames,
+            runId: RunId.value,
+            memoryLimitMb: this.memoryLimitMb,
+        };
+        return this.customizeSpec(spec, (guest) => {
+            const p = ports.get(guest);
+            if (p === undefined) {
+                throw new Error(`no allocated host port for guest port ${guest}`);
+            }
+            return p;
+        });
+    }
+    async allocatePorts() {
+        const ports = new Map();
+        for (const guestPort of this.exposedPorts) {
+            ports.set(guestPort, await FreePorts.allocate());
+        }
+        return ports;
+    }
+    releasePorts(ports) {
+        for (const hostPort of ports.values()) {
+            FreePorts.release(hostPort);
+        }
+    }
+    /**
+     * Resolves a backend, allocates host ports, boots the container, installs
+     * any network links, and waits for readiness — in that order. On ANY
+     * failure partway through (a bad wait strategy, a network-link rejection,
+     * a port conflict exhausting its retries), everything already allocated
+     * or started is torn down to completion BEFORE this rejects: a
+     * half-started container never leaks, and there is no detached
+     * fire-and-forget cleanup running after `start()` has already returned
+     * control to the caller.
+     *
+     * A host-port-bind conflict specifically retries (up to 5 attempts) with
+     * a fresh port before giving up — pre-allocated ports can still lose an
+     * allocate-then-bind race to an unrelated process.
+     */
+    async start() {
+        const backend = this.resolveBackend();
+        await this.containerIsStarting(backend);
+        if (this.network !== undefined) {
+            await backend.ensureNetwork(this.network.id);
+        }
+        let handle;
+        let allocatedPorts;
+        let lastConflict;
+        for (let attempt = 0; attempt < MAX_START_ATTEMPTS; attempt++) {
+            const ports = await this.allocatePorts();
+            const name = `rz-${RunId.value}-${nextSequence()}`;
+            const spec = this.buildSpec(name, ports);
+            let createdHandle;
+            try {
+                createdHandle = await backend.create(spec);
+                await backend.start(createdHandle);
+                handle = createdHandle;
+                allocatedPorts = ports;
+                break;
+            }
+            catch (err) {
+                if (createdHandle !== undefined) {
+                    await swallow(() => backend.stop(createdHandle));
+                    await swallow(() => backend.remove(createdHandle));
+                }
+                this.releasePorts(ports);
+                if (isPortBindConflict(err)) {
+                    lastConflict = err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        if (handle === undefined || allocatedPorts === undefined) {
+            throw new Error(`Failed to start '${this.image}' after ${MAX_START_ATTEMPTS} attempts: every attempt hit a host port already in use by another process.`, { cause: lastConflict });
+        }
+        // Assign guard fields: getMappedPort/exec/logs become valid from here,
+        // even though readiness (below) hasn't been confirmed yet.
+        this.handle = handle;
+        this.backend = backend;
+        this.mappedPorts = allocatedPorts;
+        this.running = true;
+        // Real synchronous teardown, not a placeholder: if this process dies
+        // before stop() ever runs (process.exit / SIGINT / SIGTERM), the exit
+        // hook in cleanup.ts calls straight into the backend's own blocking
+        // cleanupSync — the same mechanism a crash-recovery reaper would find
+        // necessary, just invoked proactively instead of on the next process's
+        // startup sweep.
+        registerSyncCleanup(handle.id, () => backend.cleanupSync(handle.id));
+        try {
+            const links = this.network?.linksForNewMember() ?? [];
+            await backend.installNetworkLinks(handle, links);
+            // Register AFTER links are computed/installed — a container must
+            // never see itself in its own linksForNewMember() call.
+            if (this.network !== undefined) {
+                this.network.register(this, this.aliasNames, backend);
+            }
+            await this.waitStrategy.waitUntilReady(this.asWaitTarget());
+        }
+        catch (err) {
+            // A half-started container never leaks regardless of which step
+            // failed: tear down to completion before this rejection surfaces, so
+            // start() never returns until cleanup has actually finished.
+            await this.stop();
+            throw err;
+        }
+        await this.containerIsStarted();
+        return this;
+    }
+    /**
+     * Stops and removes the backend-native resource, releases its host ports,
+     * and clears the port map. Idempotent — stopping a container that never
+     * started, or stopping twice, is a harmless no-op the second time. Errors
+     * from the backend's own stop/remove calls are swallowed (best-effort
+     * teardown); this method itself never throws.
+     */
+    async stop() {
+        if (!this.running || this.handle === undefined || this.backend === undefined) {
+            return;
+        }
+        const handle = this.handle;
+        const backend = this.backend;
+        this.running = false;
+        await swallow(() => backend.stop(handle));
+        await swallow(() => backend.remove(handle));
+        unregisterSyncCleanup(handle.id);
+        this.releasePorts(this.mappedPorts);
+        this.mappedPorts = new Map();
+    }
+    /** `= stop()`. What `await using c = await new GenericContainer(img).start()` calls at scope exit; never throws. */
+    async [Symbol.asyncDispose]() {
+        await this.stop();
+    }
+    /** Whether `start()` has completed and `stop()` has not yet run. */
+    get isRunning() {
+        return this.running;
+    }
+    /** Always `"127.0.0.1"` — every published port is bound loopback-only, on both backends. */
+    get host() {
+        return "127.0.0.1";
+    }
+    /** Names this container answers to on its network (set via `withNetworkAliases`). Part of the `NetworkMember` contract `Network` uses to compute links. */
+    get aliases() {
+        return this.aliasNames;
+    }
+    /** Every guest port this container published (set via `withExposedPorts`). Part of the `NetworkMember` contract `Network` uses to compute links. */
+    get exposedGuestPorts() {
+        return this.exposedPorts;
+    }
+    /**
+     * The host port bound to `guestPort`. Throws distinct messages for the
+     * two ways this can be wrong: not running at all ("call start() first"),
+     * versus running but never exposed via `withExposedPorts` ("call
+     * withExposedPorts(N)").
+     */
+    getMappedPort(guestPort) {
+        if (!this.running) {
+            throw new Error(`Container is not running — call start() first.`);
+        }
+        const port = this.mappedPorts.get(guestPort);
+        if (port === undefined) {
+            throw new Error(`Port ${guestPort} is not exposed — call withExposedPorts(${guestPort}).`);
+        }
+        return port;
+    }
+    /** Alias for `getMappedPort`, satisfying the `NetworkMember`/`WaitTarget` shape (which name this method `mappedPort`). */
+    mappedPort(guestPort) {
+        return this.getMappedPort(guestPort);
+    }
+    requireHandle() {
+        if (!this.running || this.handle === undefined || this.backend === undefined) {
+            throw new Error(`Container is not running — call start() first.`);
+        }
+        return { handle: this.handle, backend: this.backend };
+    }
+    /** Runs a one-shot command inside the running container and waits for it to exit. Throws if the container is not running. */
+    async exec(...cmd) {
+        const { handle, backend } = this.requireHandle();
+        return backend.exec(handle, cmd);
+    }
+    /** Fetches the workload's logs so far (a bounded tail), as a single string. Throws if the container is not running. */
+    async logs() {
+        const { handle, backend } = this.requireHandle();
+        return backend.logs(handle);
+    }
+    /**
+     * Streams log lines to `consumer` as they're produced, in order, with no
+     * duplicates — including the final unterminated fragment after the
+     * workload exits, delivered exactly once. Call `close()` on the returned
+     * handle to stop delivery without flushing anything further.
+     */
+    async followOutput(consumer) {
+        const { handle, backend } = this.requireHandle();
+        return backend.followLogs(handle, consumer);
+    }
+    asWaitTarget() {
+        return {
+            host: this.host,
+            mappedPort: (guestPort) => this.getMappedPort(guestPort),
+            exposedGuestPorts: this.exposedPorts,
+            currentLogs: () => this.logs(),
+            describe: () => `container '${this.handle?.spec.name ?? this.image}' (image ${this.image})`,
+        };
+    }
+}
+//# sourceMappingURL=generic-container.js.map

package/dist/core/generic-container.js.map

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

package/dist/core/model.d.ts

@@ -0,0 +1,60 @@
+/** A published container port: a host port already chosen, mapped to the port the workload listens on inside the guest. */
+export interface PortBinding {
+    /** The host-side port, pre-allocated by `FreePorts`. */
+    readonly hostPort: number;
+    /** The port the workload listens on inside the guest. */
+    readonly guestPort: number;
+}
+/** A host path copied into the guest before boot. `readOnly` defaults to `true` via the builder (`withCopyFileToContainer`). */
+export interface FileMount {
+    /** Absolute host path to copy from. */
+    readonly hostPath: string;
+    /** Destination path inside the guest. */
+    readonly guestPath: string;
+    /** Enforced on docker; advisory only on msb (current microsandbox releases do not enforce guest-side read-only mounts). */
+    readonly readOnly: boolean;
+}
+/** The result of a one-shot `exec` inside a running container. */
+export interface ExecResult {
+    /** The command's process exit code. */
+    readonly exitCode: number;
+    /** Everything the command wrote to stdout. */
+    readonly stdout: string;
+    /** Everything the command wrote to stderr. */
+    readonly stderr: string;
+}
+/**
+ * The immutable, backend-agnostic description of a container to launch.
+ * Built by `GenericContainer` from its builder calls and handed to
+ * whichever `SandboxBackend` is active — a spec never changes once built,
+ * and building one performs no I/O.
+ */
+export interface ContainerSpec {
+    /** The container's name, `rz-<runId>-<seq>`. */
+    readonly name: string;
+    /** The image reference, e.g. `"redis:8.6-alpine"`. */
+    readonly image: string;
+    /**
+     * Array of pairs, not a Map: insertion-ordered, with last-write-wins
+     * deduping when a builder overwrites a key.
+     */
+    readonly env: ReadonlyArray<readonly [string, string]>;
+    /** `undefined` means the image's own ENTRYPOINT/CMD runs unmodified. */
+    readonly command: ReadonlyArray<string> | undefined;
+    /**
+     * Already-chosen host ports — the core invariant of this library: a
+     * backend binds these, it never allocates its own. See `FreePorts`.
+     */
+    readonly ports: ReadonlyArray<PortBinding>;
+    /** Host files/directories to copy into the guest before boot. */
+    readonly mounts: ReadonlyArray<FileMount>;
+    /** The `Network.id` this container joins, if any. */
+    readonly networkId: string | undefined;
+    /** Names this container answers to on its network. */
+    readonly aliases: ReadonlyArray<string>;
+    /** The process-wide `RunId.value` that named this container. */
+    readonly runId: string;
+    /** An explicit memory ceiling in MB, if the module or caller set one via `withMemoryLimit`. */
+    readonly memoryLimitMb: number | undefined;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/core/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/core/model.ts"],"names":[],"mappings":"AAAA,2HAA2H;AAC3H,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gIAAgI;AAChI,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C"}

package/dist/core/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/core/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/core/model.ts"],"names":[],"mappings":""}

package/dist/core/mountable-file.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A file resolved to an absolute host path, ready to pass to
+ * `GenericContainer.withCopyFileToContainer`. `path` is always absolute —
+ * `forHostPath` resolves it immediately, and `forResource` copies to a
+ * cleaned-on-exit temp file first.
+ */
+export declare class MountableFile {
+    /** The resolved, absolute host path. */
+    readonly path: string;
+    private constructor();
+    /** Resolves a host filesystem path (relative to `process.cwd()` if not already absolute). */
+    static forHostPath(hostPath: string): MountableFile;
+    /**
+     * JS has no classpath and no cheap "caller's directory": `import.meta.url`
+     * only ever gives the DEFINING module's own directory, and recovering the
+     * true call site would need a fragile `Error().stack` parse that differs
+     * between Node and Bun. So the base is explicit rather than inferred:
+     * `relPath` resolves against `baseUrl` (typically the calling module's own
+     * `import.meta.url`) when given, and against `process.cwd()` otherwise.
+     * There is no classpath-relative resolution here — only an explicit
+     * base (an `import.meta.url` you pass in) or the process cwd.
+     */
+    static forResource(relPath: string, baseUrl?: string): MountableFile;
+}
+//# sourceMappingURL=mountable-file.d.ts.map

package/dist/core/mountable-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountable-file.d.ts","sourceRoot":"","sources":["../../src/core/mountable-file.ts"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,qBAAa,aAAa;IAEtB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAFvB,OAAO;IAKP,6FAA6F;IAC7F,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAInD;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;CAKrE"}

package/dist/core/mountable-file.js

@@ -0,0 +1,64 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+const tempCopies = [];
+let exitHookInstalled = false;
+function installExitCleanup() {
+    if (exitHookInstalled) {
+        return;
+    }
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const p of tempCopies) {
+            try {
+                fs.rmSync(p, { force: true });
+            }
+            catch {
+                // best-effort; the OS reclaims tmpdir eventually regardless
+            }
+        }
+    });
+}
+function copyToTemp(sourcePath) {
+    const dest = path.join(os.tmpdir(), `rightsize-${randomBytes(6).toString("hex")}-${path.basename(sourcePath)}`);
+    fs.copyFileSync(sourcePath, dest);
+    tempCopies.push(dest);
+    installExitCleanup();
+    return dest;
+}
+/**
+ * A file resolved to an absolute host path, ready to pass to
+ * `GenericContainer.withCopyFileToContainer`. `path` is always absolute —
+ * `forHostPath` resolves it immediately, and `forResource` copies to a
+ * cleaned-on-exit temp file first.
+ */
+export class MountableFile {
+    path;
+    constructor(
+    /** The resolved, absolute host path. */
+    path) {
+        this.path = path;
+    }
+    /** Resolves a host filesystem path (relative to `process.cwd()` if not already absolute). */
+    static forHostPath(hostPath) {
+        return new MountableFile(path.resolve(hostPath));
+    }
+    /**
+     * JS has no classpath and no cheap "caller's directory": `import.meta.url`
+     * only ever gives the DEFINING module's own directory, and recovering the
+     * true call site would need a fragile `Error().stack` parse that differs
+     * between Node and Bun. So the base is explicit rather than inferred:
+     * `relPath` resolves against `baseUrl` (typically the calling module's own
+     * `import.meta.url`) when given, and against `process.cwd()` otherwise.
+     * There is no classpath-relative resolution here — only an explicit
+     * base (an `import.meta.url` you pass in) or the process cwd.
+     */
+    static forResource(relPath, baseUrl) {
+        const baseDir = baseUrl === undefined ? process.cwd() : path.dirname(fileURLToPath(baseUrl));
+        const resolved = path.resolve(baseDir, relPath);
+        return new MountableFile(copyToTemp(resolved));
+    }
+}
+//# sourceMappingURL=mountable-file.js.map

package/dist/core/mountable-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountable-file.js","sourceRoot":"","sources":["../../src/core/mountable-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,UAAU,GAAa,EAAE,CAAC;AAChC,IAAI,iBAAiB,GAAG,KAAK,CAAC;AAE9B,SAAS,kBAAkB;IACzB,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IACD,iBAAiB,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,4DAA4D;YAC9D,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,UAAkB;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,aAAa,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAChH,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAClC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,kBAAkB,EAAE,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IAGb;IAFX;IACE,wCAAwC;IAC/B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IACpB,CAAC;IAEJ,6FAA6F;IAC7F,MAAM,CAAC,WAAW,CAAC,QAAgB;QACjC,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,CAAC,OAAe,EAAE,OAAgB;QAClD,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7F,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,CAAC;CACF"}

package/dist/core/network.d.ts

@@ -0,0 +1,58 @@
+import type { SandboxBackend, NetworkLink } from "./backend.js";
+/**
+ * The subset of a running container `Network` needs in order to compute
+ * links for a newly-joining sibling: its aliases, its exposed guest ports
+ * mapped to host ports, and whether it is currently running (a stopped
+ * container never gets linked to).
+ */
+export interface NetworkMember {
+    /** Names this member answers to on the network. */
+    readonly aliases: ReadonlyArray<string>;
+    /** Whether this member is currently running (a stopped member is never linked to). */
+    readonly isRunning: boolean;
+    /** Guest ports this member has exposed. */
+    readonly exposedGuestPorts: ReadonlyArray<number>;
+    /** The host port bound to `guestPort`. */
+    mappedPort(guestPort: number): number;
+}
+/**
+ * Alias-based connectivity between containers, on both backends. Docker
+ * implements it with a native bridge network; msb — where each container is
+ * a fully isolated microVM — emulates it with an `/etc/hosts` alias plus a
+ * TCP relay over the sandbox's exec channel. `Network.resolve` returns the
+ * same `"alias:port"` string either way, so code written against it doesn't
+ * need to know which backend is active.
+ *
+ * Implements `Symbol.asyncDispose`, so `await using net = Network.newNetwork()`
+ * tears the network down at scope exit alongside its member containers.
+ */
+export declare class Network implements AsyncDisposable {
+    /** This network's process-unique id, `rz-net-<8hex>`. */
+    readonly id: string;
+    private readonly aliasPorts;
+    private readonly members;
+    private lastBackend;
+    private constructor();
+    /** Creates a new network with a process-unique id (`rz-net-<8hex>`). Pass it to `withNetwork` on each member container. */
+    static newNetwork(): Network;
+    /** "alias:guestPort" for a registered (alias, guestPort) pair; throws naming the alias otherwise. */
+    resolve(alias: string, guestPort: number): string;
+    /**
+     * Links a newly-starting container needs installed toward every ALREADY
+     * RUNNING sibling, computed before `register` runs — so a container can
+     * never end up linked to itself, and only genuinely-running siblings
+     * (never a half-started or already-stopped one) contribute links.
+     */
+    linksForNewMember(): ReadonlyArray<NetworkLink>;
+    /**
+     * Registers a container as a network member AFTER its links to existing
+     * siblings were computed and installed — never before, or the ordering
+     * that prevents self-links breaks.
+     */
+    register(member: NetworkMember, aliases: ReadonlyArray<string>, backend: SandboxBackend): void;
+    /** Removes the backend-native network. Best-effort: safe to call even if no member ever started. */
+    close(): Promise<void>;
+    /** `= close()`. What `await using net = Network.newNetwork()` calls at scope exit. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/core/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/core/network.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD,0CAA0C;IAC1C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,OAAQ,YAAW,eAAe;IAC7C,yDAAyD;IACzD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0C;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,WAAW,CAA6B;IAEhD,OAAO;IAIP,2HAA2H;IAC3H,MAAM,CAAC,UAAU,IAAI,OAAO;IAI5B,qGAAqG;IACrG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQjD;;;;;OAKG;IACH,iBAAiB,IAAI,aAAa,CAAC,WAAW,CAAC;IAe/C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAe9F,oGAAoG;IAC9F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,sFAAsF;IAChF,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}