rightsize 0.1.0

package/dist/backend-msb/provisioner.js

@@ -0,0 +1,332 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as http from "node:http";
+import * as https from "node:https";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createHash } from "node:crypto";
+import { ProvisionError } from "../core/errors.js";
+import { PlatformInfo } from "./platform.js";
+export const MSB_VERSION = "0.6.3";
+const DEFAULT_BASE = `https://github.com/superradcompany/microsandbox/releases/download/v${MSB_VERSION}`;
+const CONNECT_READ_TIMEOUT_MS = 300_000;
+const STALE_LOCK_AGE_MS = 5 * 60 * 1000;
+const LOCK_POLL_MS = 200;
+const LOCK_WAIT_MAX_MS = 30_000;
+/**
+ * `%LOCALAPPDATA%` is the Windows-idiomatic location for a machine-local,
+ * non-roaming native toolchain cache (as opposed to `%USERPROFILE%`, which a
+ * roaming-profile setup can sync, or a Unix-style dotfile under the home
+ * dir). Falls back to `%USERPROFILE%\AppData\Local` if the env var is unset,
+ * matching what `os.homedir()` resolves to on a normal Windows install when
+ * `LOCALAPPDATA` isn't populated (rare, but seen on some minimal/CI images).
+ */
+function defaultCacheDir() {
+    const override = process.env["RIGHTSIZE_CACHE_DIR"];
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env["LOCALAPPDATA"] ?? path.join(os.homedir(), "AppData", "Local");
+        return path.join(localAppData, "rightsize");
+    }
+    return path.join(os.homedir(), ".cache", "rightsize");
+}
+/**
+ * "Is this a usable, already-provisioned msb binary": on macOS/Linux this
+ * means POSIX-executable (the release asset ships without the exec bit set,
+ * so a bare `existsSync` would pass on a half-downloaded or permission-wrong
+ * file); Windows has no execute-bit concept, so an existing regular `.exe`
+ * file is the whole check there — `fs.constants.X_OK` on Windows is
+ * documented to reduce to an existence check anyway, but an explicit branch
+ * keeps the intent visible rather than relying on that platform quirk.
+ */
+function isExecutableFile(p) {
+    if (process.platform === "win32") {
+        try {
+            return fs.statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isInstalled(msbPath, krunPath) {
+    if (!isExecutableFile(msbPath)) {
+        return false;
+    }
+    return fs.existsSync(krunPath);
+}
+/** Follows a bounded chain of 30x redirects — the release CDN issues one hop to the actual asset host. */
+function fetchBuffer(url, maxRedirects = 5) {
+    const transport = url.startsWith("https:") ? https : http;
+    return new Promise((resolveFetch, rejectFetch) => {
+        const req = transport.get(url, { timeout: CONNECT_READ_TIMEOUT_MS }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400 && res.headers.location !== undefined) {
+                res.resume();
+                if (maxRedirects <= 0) {
+                    rejectFetch(new ProvisionError(`too many redirects fetching ${url}`));
+                    return;
+                }
+                const nextUrl = new URL(res.headers.location, url).toString();
+                fetchBuffer(nextUrl, maxRedirects - 1).then(resolveFetch, rejectFetch);
+                return;
+            }
+            if (status !== 200) {
+                res.resume();
+                rejectFetch(new ProvisionError(`HTTP ${status} fetching ${url}`));
+                return;
+            }
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => resolveFetch(Buffer.concat(chunks)));
+            res.on("error", (err) => rejectFetch(err));
+        });
+        req.on("timeout", () => req.destroy(new ProvisionError(`timed out fetching ${url}`)));
+        req.on("error", (err) => rejectFetch(err));
+    });
+}
+/** Tolerant of extra whitespace and either column order — `sha256sum` output vs a hand-authored manifest can vary. */
+function parseChecksums(text) {
+    const sums = new Map();
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            continue;
+        }
+        const parts = line.split(/\s+/);
+        if (parts.length < 2) {
+            throw new ProvisionError(`malformed line in checksums.sha256: '${line}'`);
+        }
+        const [hex, filename] = parts;
+        if (hex !== undefined && filename !== undefined) {
+            sums.set(filename, hex.toLowerCase());
+        }
+    }
+    return sums;
+}
+function sha256Hex(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+function parseLockInfo(text) {
+    const [pidStr, tsStr] = text.trim().split("\n");
+    const pid = Number(pidStr);
+    const timestamp = Number(tsStr);
+    if (!Number.isFinite(pid) || !Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    return { pid, timestamp };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH: no such process. EPERM: a live process we don't own — still alive.
+        return err.code === "EPERM";
+    }
+}
+function isLockStale(info) {
+    if (info === undefined) {
+        // An unparseable lock file cannot be trusted as "held" — treat it as stale.
+        return true;
+    }
+    if (!isProcessAlive(info.pid)) {
+        return true;
+    }
+    return Date.now() - info.timestamp > STALE_LOCK_AGE_MS;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Cross-process install-dir lock via `fs.open(path, "wx")` (O_EXCL create) —
+ * the closest Node stdlib equivalent to a kernel-held advisory lock, except
+ * that unlike an OS advisory lock it is NOT released automatically
+ * when the holding process dies. The lock file therefore records
+ * `${pid}\n${timestamp}` so a waiter can positively detect a dead holder
+ * (`process.kill(pid, 0)` throwing `ESRCH`) rather than only ever guessing
+ * from file age. Staleness is thus two independent conditions, either one
+ * sufficient to take over: the recorded PID is provably dead, OR the lock
+ * predates the staleness threshold (a live-but-wedged holder).
+ */
+async function withInstallLock(lockPath, fn) {
+    const deadline = Date.now() + LOCK_WAIT_MAX_MS;
+    for (;;) {
+        let handle;
+        try {
+            handle = await fsp.open(lockPath, "wx");
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                throw err;
+            }
+            // Someone else holds the lock file (or a stale one is sitting there).
+            let existing;
+            try {
+                existing = await fsp.readFile(lockPath, "utf8");
+            }
+            catch {
+                existing = "";
+            }
+            const info = parseLockInfo(existing);
+            if (isLockStale(info)) {
+                // Stale takeover: remove and retry immediately. A second racer may
+                // beat us to the same removal+recreate — that's fine, they'll just
+                // loop again on the next EEXIST.
+                try {
+                    await fsp.unlink(lockPath);
+                }
+                catch {
+                    // Already removed by a concurrent racer — fall through to retry.
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new ProvisionError(`timed out waiting for the msb install lock at ${lockPath}`);
+            }
+            await sleep(LOCK_POLL_MS);
+            continue;
+        }
+        try {
+            await handle.writeFile(`${process.pid}\n${Date.now()}`);
+            return await fn();
+        }
+        finally {
+            await handle.close();
+            await fsp.unlink(lockPath).catch(() => {
+                // Best-effort: if it's already gone (a stale-takeover racer beat us
+                // to cleanup) there's nothing left to do.
+            });
+        }
+    }
+}
+/**
+ * `mode` is a POSIX permission-bits concept; Windows has no execute bit and
+ * `fs.writeFile`'s `mode` option is a documented no-op there for anything
+ * beyond the read-only attribute, which this provisioner never needs to set.
+ * The caller's `executable` flag therefore only matters on macOS/Linux —
+ * passing it through unconditionally is harmless on Windows (Node ignores
+ * it), but the chmod-shaped intent is Windows-irrelevant, so it is spelled
+ * out here rather than left implicit.
+ */
+async function downloadVerified(baseUrl, asset, destDir, sums, executable) {
+    const expected = sums.get(asset);
+    if (expected === undefined) {
+        throw new ProvisionError(`No SHA-256 for '${asset}' in ${baseUrl}/checksums.sha256`);
+    }
+    await fsp.mkdir(destDir, { recursive: true });
+    const tmp = path.join(destDir, `.dl-${process.pid}-${Date.now()}-${asset}.part`);
+    let ok = false;
+    try {
+        const buf = await fetchBuffer(`${baseUrl}/${asset}`);
+        const actual = sha256Hex(buf);
+        if (actual !== expected) {
+            throw new ProvisionError(`SHA-256 mismatch for ${asset} from ${baseUrl} (expected ${expected}, got ${actual}) ` +
+                `— delete ${destDir} and retry, or set MSB_PATH to a trusted msb binary`);
+        }
+        const mode = process.platform === "win32" ? undefined : executable ? 0o755 : 0o644;
+        await fsp.writeFile(tmp, buf, mode !== undefined ? { mode } : undefined);
+        ok = true;
+        return tmp;
+    }
+    finally {
+        if (!ok) {
+            await fsp.unlink(tmp).catch(() => { });
+        }
+    }
+}
+/**
+ * Downloads and SHA-256-verifies BOTH assets to temp files before moving
+ * either into place, then renames krun into `lib/` FIRST and the `msb`
+ * binary into `bin/` LAST. `msb`'s presence is therefore the commit marker
+ * for a genuinely complete install — a crash between the two renames can
+ * never leave a present-msb/missing-krun state, because `isInstalled`
+ * requires both files and whichever half is missing gets re-downloaded on
+ * the next call.
+ */
+async function downloadAndInstall(baseUrl, platform, installDir, msbPath, krunPath) {
+    const checksumsText = (await fetchBuffer(`${baseUrl}/checksums.sha256`)).toString("utf8");
+    const sums = parseChecksums(checksumsText);
+    const msbAsset = PlatformInfo.msbAsset(platform);
+    const krunAsset = PlatformInfo.krunAsset(platform);
+    const msbTmp = await downloadVerified(baseUrl, msbAsset, path.join(installDir, "bin"), sums, true);
+    const krunTmp = await downloadVerified(baseUrl, krunAsset, path.join(installDir, "lib"), sums, false);
+    try {
+        await fsp.rename(krunTmp, krunPath);
+        await fsp.rename(msbTmp, msbPath);
+    }
+    finally {
+        await fsp.unlink(msbTmp).catch(() => { });
+        await fsp.unlink(krunTmp).catch(() => { });
+    }
+}
+/** Test seam: the full resolution logic parameterized over the release base URL, cache dir, and environment. */
+export async function ensureInstalledAt(baseUrl, cacheDir, env) {
+    const override = env["MSB_PATH"];
+    if (override !== undefined) {
+        // Windows has no execute-bit concept: "is a real file that exists" is
+        // the whole validity check there (see isExecutableFile's doc comment);
+        // macOS/Linux keep requiring the POSIX execute bit.
+        if (!isExecutableFile(override)) {
+            throw new ProvisionError(`MSB_PATH='${override}' is not an executable file`);
+        }
+        return override;
+    }
+    const platform = PlatformInfo.current();
+    if (platform === undefined) {
+        throw new ProvisionError(`microsandbox has no build for ${process.platform}/${process.arch} — ` +
+            `use the docker backend (RIGHTSIZE_BACKEND=docker) or set MSB_PATH to a binary you provide`);
+    }
+    const installDir = path.join(cacheDir, "msb", MSB_VERSION);
+    const msbPath = path.join(installDir, "bin", PlatformInfo.msbBinaryName(platform));
+    // Installed under the canonical name msb resolves (`../lib/` next to its binary),
+    // not the release-asset name it is downloaded as — msb never probes the asset name.
+    const krunPath = path.join(installDir, "lib", PlatformInfo.krunInstallName(platform));
+    if (isInstalled(msbPath, krunPath)) {
+        return msbPath;
+    }
+    if (env["RIGHTSIZE_MSB_SKIP_DOWNLOAD"] === "true") {
+        throw new ProvisionError(`msb ${MSB_VERSION} not found at ${msbPath} and RIGHTSIZE_MSB_SKIP_DOWNLOAD=true — ` +
+            `pre-install it there or point MSB_PATH at an msb binary`);
+    }
+    await fsp.mkdir(installDir, { recursive: true });
+    await withInstallLock(path.join(installDir, ".lock"), async () => {
+        // Another process may have finished the install while we waited for the lock.
+        if (isInstalled(msbPath, krunPath)) {
+            return;
+        }
+        await downloadAndInstall(baseUrl, platform, installDir, msbPath, krunPath);
+    });
+    return msbPath;
+}
+/** Resolves (downloading and verifying if needed) a runnable `msb` binary path, using the real GitHub release base, `RIGHTSIZE_CACHE_DIR`, and `process.env`. */
+export function ensureInstalled() {
+    return ensureInstalledAt(DEFAULT_BASE, defaultCacheDir(), process.env);
+}
+/** Test-only access to the pure checksum-line parser, exercised against real-shape and malformed input. */
+export function _parseChecksumsForTests(text) {
+    return parseChecksums(text);
+}
+/**
+ * Test-only seam: `downloadAndInstall` parameterized over an injected
+ * `Platform` value, rather than the real `PlatformInfo.current()`. This is
+ * how the `.exe`/`.dll` install shape (Windows asset names, `bin\msb.exe`,
+ * unversioned `lib\libkrunfw.dll`) is exercised against the real
+ * download-verify-rename pipeline from a non-Windows CI/dev machine — the
+ * public `ensureInstalledAt` always resolves the platform from the real
+ * process, so it can only ever prove the CURRENT host's shape without this.
+ */
+export async function _downloadAndInstallForTests(baseUrl, platform, installDir, msbPath, krunPath) {
+    return downloadAndInstall(baseUrl, platform, installDir, msbPath, krunPath);
+}
+//# sourceMappingURL=provisioner.js.map

package/dist/backend-msb/provisioner.js.map

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

package/dist/backend-msb/reaper.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Every `rz-<runid>-<seq>` name mentioned in `msb ls`'s output that does NOT
+ * belong to `thisRunId` — leftovers from a run that crashed before its own
+ * cleanup ran. Filtering happens against the SAME `RunId.value` core used to
+ * name this run's own containers (imported from `rightsize`, never
+ * recomputed here) — a backend-local run id would either reap this run's own
+ * live sandboxes or fail to recognize a genuinely stale one.
+ */
+export declare function orphanNames(lsOutput: string, thisRunId: string): string[];
+//# sourceMappingURL=reaper.d.ts.map

package/dist/backend-msb/reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.d.ts","sourceRoot":"","sources":["../../src/backend-msb/reaper.ts"],"names":[],"mappings":"AA0DA;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CASzE"}

package/dist/backend-msb/reaper.js

@@ -0,0 +1,73 @@
+function isHexDigit(ch) {
+    return ch !== undefined && /^[0-9a-f]$/i.test(ch);
+}
+function isDigit(ch) {
+    return ch !== undefined && ch >= "0" && ch <= "9";
+}
+/** A character that continues an identifier token: alphanumeric, `-`, or `_`. */
+function isIdentContinue(ch) {
+    return ch !== undefined && /^[A-Za-z0-9_-]$/.test(ch);
+}
+/**
+ * Extracts every `rz-<8 hex>-<seq>`-shaped name appearing anywhere in `ls`
+ * output — a manual character scan rather than
+ * a `\b`-delimited regex. `\b` is a `\w` boundary and `\w` does not include
+ * `-`, so a naive `/\brz-[0-9a-f]{8}-\d+\b/` would treat `rz-deadbeef-1` as a
+ * complete match inside `rz-deadbeef-1-extra` (the `-` after the digits
+ * counts as a boundary) even though that's a glued-on continuation of a
+ * longer, different token — exactly the shape a second run's id could
+ * produce as a prefix of a name it doesn't own. Requiring the character
+ * immediately after the matched digits to NOT be an identifier-continue
+ * character keeps this a whole-token match instead of a false-positive
+ * prefix.
+ */
+function orphanCandidateNames(lsOutput) {
+    const names = [];
+    let i = 0;
+    const n = lsOutput.length;
+    while (i < n) {
+        if (lsOutput.startsWith("rz-", i)) {
+            const start = i;
+            let j = i + 3;
+            let hexLen = 0;
+            while (j < n && hexLen < 8 && isHexDigit(lsOutput[j])) {
+                j++;
+                hexLen++;
+            }
+            if (hexLen === 8 && lsOutput[j] === "-") {
+                let k = j + 1;
+                let digitLen = 0;
+                while (k < n && isDigit(lsOutput[k])) {
+                    k++;
+                    digitLen++;
+                }
+                if (digitLen > 0 && (k >= n || !isIdentContinue(lsOutput[k]))) {
+                    names.push(lsOutput.slice(start, k));
+                    i = k;
+                    continue;
+                }
+            }
+        }
+        i++;
+    }
+    return names;
+}
+/**
+ * Every `rz-<runid>-<seq>` name mentioned in `msb ls`'s output that does NOT
+ * belong to `thisRunId` — leftovers from a run that crashed before its own
+ * cleanup ran. Filtering happens against the SAME `RunId.value` core used to
+ * name this run's own containers (imported from `rightsize`, never
+ * recomputed here) — a backend-local run id would either reap this run's own
+ * live sandboxes or fail to recognize a genuinely stale one.
+ */
+export function orphanNames(lsOutput, thisRunId) {
+    const mine = `rz-${thisRunId}-`;
+    const seen = new Set();
+    for (const name of orphanCandidateNames(lsOutput)) {
+        if (!name.startsWith(mine)) {
+            seen.add(name);
+        }
+    }
+    return [...seen];
+}
+//# sourceMappingURL=reaper.js.map

package/dist/backend-msb/reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.js","sourceRoot":"","sources":["../../src/backend-msb/reaper.ts"],"names":[],"mappings":"AAAA,SAAS,UAAU,CAAC,EAAsB;IACxC,OAAO,EAAE,KAAK,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,OAAO,CAAC,EAAsB;IACrC,OAAO,EAAE,KAAK,SAAS,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,IAAI,GAAG,CAAC;AACpD,CAAC;AAED,iFAAiF;AACjF,SAAS,eAAe,CAAC,EAAsB;IAC7C,OAAO,EAAE,KAAK,SAAS,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC1B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,CAAC,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,CAAC,EAAE,CAAC;gBACJ,MAAM,EAAE,CAAC;YACX,CAAC;YACD,IAAI,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,IAAI,QAAQ,GAAG,CAAC,CAAC;gBACjB,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACrC,CAAC,EAAE,CAAC;oBACJ,QAAQ,EAAE,CAAC;gBACb,CAAC;gBACD,IAAI,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC9D,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;oBACrC,CAAC,GAAG,CAAC,CAAC;oBACN,SAAS;gBACX,CAAC;YACH,CAAC;QACH,CAAC;QACD,CAAC,EAAE,CAAC;IACN,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IAC7D,MAAM,IAAI,GAAG,MAAM,SAAS,GAAG,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC"}

package/dist/core/backend.d.ts

@@ -0,0 +1,98 @@
+import type { ContainerSpec, ExecResult } from "./model.js";
+/**
+ * One alias a container should be reachable under from a running sibling on
+ * the same `Network`, computed by `Network.linksForNewMember()`. A native
+ * backend (docker) ignores these — its bridge network already resolves
+ * aliases; an emulating backend (msb) uses them to wire up its tunnels.
+ */
+export interface NetworkLink {
+    /** The name the sibling should be reachable under. */
+    readonly alias: string;
+    /** The sibling's exposed guest port. */
+    readonly guestPort: number;
+    /** The sibling's host-side mapped port to tunnel/route traffic to. */
+    readonly targetHostPort: number;
+}
+/**
+ * Backend-native opaque container reference. Immutable id + spec; any
+ * mutable runtime state (attached child process, log tail, tunnels) lives
+ * backend-side keyed by `id`, never bolted onto this object.
+ */
+export interface SandboxHandle {
+    /** The backend-native container id (or name, for msb). */
+    readonly id: string;
+    /** The spec this container was created from. */
+    readonly spec: ContainerSpec;
+}
+/** Owns the close mechanism for a live followOutput stream: stop delivery, never flush. */
+export interface FollowHandle {
+    /** Stops delivering further lines. Never flushes a trailing fragment — that only happens on the workload's own natural end. */
+    close(): Promise<void>;
+}
+/**
+ * The one interface every container backend implements. Host ports arrive
+ * in `ContainerSpec.ports` already chosen (see `FreePorts`) — a backend
+ * binds them, it never allocates its own.
+ */
+export interface SandboxBackend {
+    /** The backend's own name (`"microsandbox"` or `"docker"`). */
+    readonly name: string;
+    /** `true` for docker (native bridge networks); `false` for msb, which emulates links over exec-stream tunnels instead. */
+    readonly supportsNativeNetworks: boolean;
+    /** Allocate the backend-native container without starting it. Must not bind ports or run the workload yet. */
+    create(spec: ContainerSpec): Promise<SandboxHandle>;
+    /** Boot the workload. On a bind conflict, throw (or wrap a cause chain ending in) `PortBindConflictError` so `GenericContainer`'s retry loop can classify it. */
+    start(handle: SandboxHandle): Promise<void>;
+    /** Best-effort stop; callers swallow failures during teardown. */
+    stop(handle: SandboxHandle): Promise<void>;
+    /** Best-effort removal of the backend-native resource; callers swallow failures during teardown. */
+    remove(handle: SandboxHandle): Promise<void>;
+    /** Run a one-shot command inside a running container and wait for it to exit. */
+    exec(handle: SandboxHandle, cmd: ReadonlyArray<string>): Promise<ExecResult>;
+    /** Fetch everything logged so far (bounded tail), for a one-shot read. */
+    logs(handle: SandboxHandle): Promise<string>;
+    /**
+     * Stream 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. Returns a handle whose `close()`
+     * stops delivery without flushing anything further.
+     */
+    followLogs(handle: SandboxHandle, consumer: (line: string) => void): Promise<FollowHandle>;
+    /** Idempotently ensure a network with this id exists. */
+    ensureNetwork(networkId: string): Promise<void>;
+    /** Best-effort removal of a network created by `ensureNetwork`. */
+    removeNetwork(networkId: string): Promise<void>;
+    /** Default no-op: docker relies on native networks. Only an emulating backend overrides it. */
+    installNetworkLinks(handle: SandboxHandle, links: ReadonlyArray<NetworkLink>): Promise<void>;
+    /** Best-effort teardown of backend-owned resources (sockets, child processes). */
+    close(): Promise<void>;
+    /**
+     * Synchronous, blocking teardown of ONE container, for the process-exit
+     * path only (`node:process`'s `"exit"` handler runs synchronously and
+     * cannot `await` the backend's normal async `stop`/`remove`). Every
+     * backend implements this with a blocking primitive of its own —
+     * `child_process.spawnSync` for msb, a blocking unix-socket call for
+     * docker — never by calling back into the async API. Best-effort: swallow
+     * failures, the process is exiting regardless.
+     */
+    cleanupSync(id: string): void;
+}
+/**
+ * The `ServiceLoader` analog: a backend subpath (`rightsize/backend-msb`,
+ * `rightsize/backend-docker`) registers one of these at import time via
+ * `registerBackend`. `Backends.resolve` picks the highest-priority supported
+ * provider, or honors `RIGHTSIZE_BACKEND` when set.
+ */
+export interface BackendProvider {
+    /** The provider's backend name, matched case-insensitively against `RIGHTSIZE_BACKEND`. */
+    readonly name: string;
+    /** Higher wins when multiple providers are supported (msb=20, docker=10). */
+    readonly priority: number;
+    /** MUST be synchronous — never return a Promise (a truthy Promise reads as "supported" to callers that don't await it). */
+    isSupported(): boolean;
+    /** Human-readable reason this provider isn't usable right now, surfaced when no supported provider exists. */
+    unsupportedReason(): string;
+    /** Construct the backend. Called once resolution has picked this provider. */
+    create(): SandboxBackend;
+}
+//# sourceMappingURL=backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,+HAA+H;IAC/H,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0HAA0H;IAC1H,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,8GAA8G;IAC9G,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpD,iKAAiK;IACjK,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,kEAAkE;IAClE,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,oGAAoG;IACpG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,iFAAiF;IACjF,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7E,0EAA0E;IAC1E,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3F,yDAAyD;IACzD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,mEAAmE;IACnE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,+FAA+F;IAC/F,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,kFAAkF;IAClF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2HAA2H;IAC3H,WAAW,IAAI,OAAO,CAAC;IACvB,8GAA8G;IAC9G,iBAAiB,IAAI,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,IAAI,cAAc,CAAC;CAC1B"}

package/dist/core/backend.js

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

package/dist/core/backend.js.map

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

package/dist/core/backends.d.ts

@@ -0,0 +1,37 @@
+import type { BackendProvider, SandboxBackend } from "./backend.js";
+/** Adds a provider to the process-global registry. Called once, at import time, by each backend subpath's `index.ts`. */
+export declare function registerBackend(provider: BackendProvider): void;
+/** Test seam: clears the process-global registry. Never call from library code. */
+export declare function _resetRegistryForTests(): void;
+/**
+ * Test seam: snapshot of the currently registered providers, so an impure
+ * suite that wipes the registry can put the real ones back when it finishes —
+ * under a single-process test runner, whatever it leaves behind is what every
+ * later-loaded test file sees.
+ */
+export declare function _providersSnapshotForTests(): BackendProvider[];
+/**
+ * Pure resolution: no I/O, no module-global registry access, so it is fully
+ * unit-testable with fake providers. `Backends.active()` is the impure
+ * caller that supplies the real registry and `process.env`.
+ */
+export declare function resolve(providers: readonly BackendProvider[], requested: string | undefined): SandboxBackend;
+/**
+ * Resolves once per process (memoized) against the real registry and
+ * `process.env.RIGHTSIZE_BACKEND`, then registers the best-effort exit-path
+ * cleanup (see `src/core/cleanup.ts`) the first time a backend is created.
+ */
+declare function active(): SandboxBackend;
+/** Test seam: forces the next `Backends.active()` call to re-resolve. */
+declare function _resetActiveForTests(): void;
+/** The library's single entry point for obtaining the active `SandboxBackend`. */
+export declare const Backends: {
+    /** Pure resolution against an explicit provider list — see `resolve` above. */
+    resolve: typeof resolve;
+    /** The memoized, per-process active backend — resolved from whatever's registered plus `RIGHTSIZE_BACKEND`. */
+    active: typeof active;
+    /** Test seam: forces the next `active()` call to re-resolve. Never call from library code. */
+    _resetActiveForTests: typeof _resetActiveForTests;
+};
+export {};
+//# sourceMappingURL=backends.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backends.d.ts","sourceRoot":"","sources":["../../src/core/backends.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQpE,yHAAyH;AACzH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,eAAe,EAAE,CAE9D;AAMD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CA2B5G;AAKD;;;;GAIG;AACH,iBAAS,MAAM,IAAI,cAAc,CAkDhC;AAED,yEAAyE;AACzE,iBAAS,oBAAoB,IAAI,IAAI,CAGpC;AAED,kFAAkF;AAClF,eAAO,MAAM,QAAQ;IACnB,+EAA+E;;IAE/E,+GAA+G;;IAE/G,8FAA8F;;CAE/F,CAAC"}