rightsize 0.1.0

package/dist/backend-docker/frames.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The Docker daemon's log-stream multiplexing frame format, present whenever
+ * a container is created without a TTY — this backend never allocates one,
+ * so this is the only shape `exec`/`logs`/`followLogs` ever see:
+ *
+ *   frame   = header ++ payload
+ *   header  = [ streamType: u8, 0u8, 0u8, 0u8, len: u32_be ]   (8 bytes)
+ *   payload = [u8; len]
+ *   streamType: 0 = stdin, 1 = stdout, 2 = stderr
+ *
+ * `FrameDemuxer` accepts arbitrary Buffer chunks — frames straddle chunk
+ * boundaries with no relationship to how the daemon happened to flush its
+ * write buffer — and buffers a partial header/payload across `push()` calls,
+ * yielding only the frames a given chunk completes.
+ */
+export type StreamType = "stdin" | "stdout" | "stderr";
+export interface Frame {
+    readonly streamType: StreamType;
+    readonly payload: Buffer;
+}
+/** Stateful frame reassembler: feed it raw bytes as they arrive, get back every frame a call completes. */
+export declare class FrameDemuxer {
+    private buffered;
+    /** Appends `chunk` to the pending buffer and returns every frame now fully available. */
+    push(chunk: Buffer): Frame[];
+}
+/**
+ * Reassembles complete lines out of a stream of text chunks whose
+ * boundaries are a chunking artifact, not a line break. A single log line
+ * can straddle two (or more) frames or Buffer reads with no relationship to
+ * where the actual `\n` falls; `feed` buffers a trailing partial line across
+ * calls and returns only the lines a given call completes. `flush` hands
+ * back that trailing fragment once at stream end — idempotent, since a
+ * terminal stream event (`end`/`close`) can legitimately fire more than once
+ * for the same close.
+ */
+export declare class LineAssembler {
+    private pending;
+    private flushedOnce;
+    feed(text: string): string[];
+    /** Returns the trailing unterminated fragment exactly once, or undefined if there was none (or this was already called). */
+    flush(): string | undefined;
+}
+//# sourceMappingURL=frames.d.ts.map

package/dist/backend-docker/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/backend-docker/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiBD,2GAA2G;AAC3G,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAA2B;IAE3C,yFAAyF;IACzF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE;CAwB7B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,WAAW,CAAS;IAE5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAqB5B,4HAA4H;IAC5H,KAAK,IAAI,MAAM,GAAG,SAAS;CAY5B"}

package/dist/backend-docker/frames.js

@@ -0,0 +1,105 @@
+/**
+ * The Docker daemon's log-stream multiplexing frame format, present whenever
+ * a container is created without a TTY — this backend never allocates one,
+ * so this is the only shape `exec`/`logs`/`followLogs` ever see:
+ *
+ *   frame   = header ++ payload
+ *   header  = [ streamType: u8, 0u8, 0u8, 0u8, len: u32_be ]   (8 bytes)
+ *   payload = [u8; len]
+ *   streamType: 0 = stdin, 1 = stdout, 2 = stderr
+ *
+ * `FrameDemuxer` accepts arbitrary Buffer chunks — frames straddle chunk
+ * boundaries with no relationship to how the daemon happened to flush its
+ * write buffer — and buffers a partial header/payload across `push()` calls,
+ * yielding only the frames a given chunk completes.
+ */
+function streamTypeFromByte(b) {
+    switch (b) {
+        case 0:
+            return "stdin";
+        case 1:
+            return "stdout";
+        case 2:
+            return "stderr";
+        default:
+            return undefined;
+    }
+}
+const HEADER_LEN = 8;
+/** Stateful frame reassembler: feed it raw bytes as they arrive, get back every frame a call completes. */
+export class FrameDemuxer {
+    buffered = Buffer.alloc(0);
+    /** Appends `chunk` to the pending buffer and returns every frame now fully available. */
+    push(chunk) {
+        this.buffered = this.buffered.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buffered, chunk]);
+        const frames = [];
+        for (;;) {
+            if (this.buffered.length < HEADER_LEN) {
+                break;
+            }
+            const len = this.buffered.readUInt32BE(4);
+            if (this.buffered.length < HEADER_LEN + len) {
+                break;
+            }
+            const streamType = streamTypeFromByte(this.buffered.readUInt8(0));
+            const payload = this.buffered.subarray(HEADER_LEN, HEADER_LEN + len);
+            if (streamType !== undefined) {
+                frames.push({ streamType, payload: Buffer.from(payload) });
+            }
+            // An unrecognized stream-type byte is dropped rather than throwing —
+            // the frame's length prefix is still trustworthy, so skipping past it
+            // cleanly (instead of aborting the whole stream) is the same
+            // tolerant-of-drift posture as the msb ls-json scanner.
+            this.buffered = this.buffered.subarray(HEADER_LEN + len);
+        }
+        return frames;
+    }
+}
+/**
+ * Reassembles complete lines out of a stream of text chunks whose
+ * boundaries are a chunking artifact, not a line break. A single log line
+ * can straddle two (or more) frames or Buffer reads with no relationship to
+ * where the actual `\n` falls; `feed` buffers a trailing partial line across
+ * calls and returns only the lines a given call completes. `flush` hands
+ * back that trailing fragment once at stream end — idempotent, since a
+ * terminal stream event (`end`/`close`) can legitimately fire more than once
+ * for the same close.
+ */
+export class LineAssembler {
+    pending = "";
+    flushedOnce = false;
+    feed(text) {
+        this.pending += text;
+        if (!this.pending.includes("\n")) {
+            return [];
+        }
+        const endsWithNewline = this.pending.endsWith("\n");
+        const parts = this.pending.split("\n");
+        // split("a\nb\n", "\n") => ["a","b",""] — the trailing "" is the
+        // "nothing pending" marker when the chunk ended exactly on a newline;
+        // split("a\nb", "\n") => ["a","b"], where "b" is genuinely pending.
+        // Either way the last element is never a completed line.
+        const tail = parts.pop() ?? "";
+        this.pending = endsWithNewline ? "" : tail;
+        // A genuinely-empty interior line (a blank line the workload printed) is
+        // real output and must be delivered — do not filter it out. Only the
+        // trailing "nothing pending" marker popped above is ever dropped; that's
+        // handled by the pop(), not by filtering here. Mirrors msb's replay
+        // contract in follow-replay.ts, so both backends agree on blank lines.
+        return parts;
+    }
+    /** Returns the trailing unterminated fragment exactly once, or undefined if there was none (or this was already called). */
+    flush() {
+        if (this.flushedOnce) {
+            return undefined;
+        }
+        this.flushedOnce = true;
+        if (this.pending.length === 0) {
+            return undefined;
+        }
+        const tail = this.pending;
+        this.pending = "";
+        return tail;
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/backend-docker/frames.js.map

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

package/dist/backend-docker/index.d.ts

@@ -0,0 +1,5 @@
+export { DockerBackend } from "./backend.js";
+export { DockerBackendProvider } from "./provider.js";
+export { DockerClient, socketPathFromDockerHost } from "./client.js";
+export type { DockerResponse, DockerStreamResponse } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/backend-docker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend-docker/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/backend-docker/index.js

@@ -0,0 +1,20 @@
+/**
+ * `rightsize/backend-docker` — the Docker daemon backend.
+ *
+ * Importing this module registers `DockerBackendProvider` with the core
+ * registry as a side effect (`priority: 10` — used when msb isn't supported,
+ * or when `RIGHTSIZE_BACKEND=docker` is set). Talks to the daemon over a
+ * hand-rolled unix-socket HTTP client (`node:http` with `socketPath`) rather
+ * than a general-purpose Docker SDK, so this backend can only ever dial the
+ * daemon's real unix socket — never a TCP host a dependency bump elsewhere
+ * could misroute it onto.
+ *
+ * @packageDocumentation
+ */
+import { registerBackend } from "../core/backends.js";
+import { DockerBackendProvider } from "./provider.js";
+registerBackend(new DockerBackendProvider());
+export { DockerBackend } from "./backend.js";
+export { DockerBackendProvider } from "./provider.js";
+export { DockerClient, socketPathFromDockerHost } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/backend-docker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend-docker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,eAAe,CAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}

package/dist/backend-docker/json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tolerant field extraction for daemon response bodies. Request bodies in
+ * this backend are fixed-shape and built with `JSON.stringify` — no need for
+ * tolerance there. Responses go through `JSON.parse` too, but wrapped so a
+ * daemon-version field addition or a genuinely malformed body degrades to
+ * "field not found" instead of throwing, matching the msb `ls` parser's own
+ * tolerance of schema drift (see `../backend-msb/ls-json.ts`).
+ */
+export declare function extractString(body: string, field: string): string | undefined;
+export declare function extractNumber(body: string, field: string): number | undefined;
+/** Every `Id` field from a JSON array of objects — used for the container/network list endpoints. */
+export declare function extractIds(body: string): string[];
+//# sourceMappingURL=json.d.ts.map

package/dist/backend-docker/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/backend-docker/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7E;AAED,qGAAqG;AACrG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYjD"}

package/dist/backend-docker/json.js

@@ -0,0 +1,47 @@
+/**
+ * Tolerant field extraction for daemon response bodies. Request bodies in
+ * this backend are fixed-shape and built with `JSON.stringify` — no need for
+ * tolerance there. Responses go through `JSON.parse` too, but wrapped so a
+ * daemon-version field addition or a genuinely malformed body degrades to
+ * "field not found" instead of throwing, matching the msb `ls` parser's own
+ * tolerance of schema drift (see `../backend-msb/ls-json.ts`).
+ */
+function parseOrUndefined(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractString(body, field) {
+    const parsed = parseOrUndefined(body);
+    if (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const value = parsed[field];
+    return typeof value === "string" ? value : undefined;
+}
+export function extractNumber(body, field) {
+    const parsed = parseOrUndefined(body);
+    if (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const value = parsed[field];
+    return typeof value === "number" ? value : undefined;
+}
+/** Every `Id` field from a JSON array of objects — used for the container/network list endpoints. */
+export function extractIds(body) {
+    const parsed = parseOrUndefined(body);
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const ids = [];
+    for (const entry of parsed) {
+        if (entry !== null && typeof entry === "object" && typeof entry["Id"] === "string") {
+            ids.push(entry["Id"]);
+        }
+    }
+    return ids;
+}
+//# sourceMappingURL=json.js.map

package/dist/backend-docker/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/backend-docker/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,KAAa;IACvD,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAI,MAAkC,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,KAAa;IACvD,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAI,MAAkC,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAiC,CAAC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YAChH,GAAG,CAAC,IAAI,CAAE,KAAiC,CAAC,IAAI,CAAW,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/backend-docker/labels.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The label key every container this backend creates carries, so `close()`
+ * and the reaper can find exactly this run's containers without touching
+ * anyone else's. The literal wire-format string is part of the library's
+ * external contract: any tool or process that filters on this label sees
+ * consistent labels regardless of which rightsize release created them.
+ */
+export declare const RUN_ID_LABEL_KEY = "dev.rightsize.runId";
+/** The `filters` query-string value for `GET /containers/json?filters=...`, scoped to one run id's label. */
+export declare function labelFilterQuery(runId: string): string;
+//# sourceMappingURL=labels.d.ts.map

package/dist/backend-docker/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/backend-docker/labels.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/backend-docker/labels.js

@@ -0,0 +1,13 @@
+/**
+ * The label key every container this backend creates carries, so `close()`
+ * and the reaper can find exactly this run's containers without touching
+ * anyone else's. The literal wire-format string is part of the library's
+ * external contract: any tool or process that filters on this label sees
+ * consistent labels regardless of which rightsize release created them.
+ */
+export const RUN_ID_LABEL_KEY = "dev.rightsize.runId";
+/** The `filters` query-string value for `GET /containers/json?filters=...`, scoped to one run id's label. */
+export function labelFilterQuery(runId) {
+    return JSON.stringify({ label: [`${RUN_ID_LABEL_KEY}=${runId}`] });
+}
+//# sourceMappingURL=labels.js.map

package/dist/backend-docker/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../src/backend-docker/labels.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAEtD,6GAA6G;AAC7G,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,IAAI,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/backend-docker/port-conflict.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The daemon has no distinct exception type for a host-port bind conflict —
+ * only free-text in a 500 response body, such as "driver failed programming
+ * external connectivity: ... address already in use" or "Bind for
+ * 0.0.0.0:PORT failed: port is already allocated". Classify by message,
+ * case-insensitively.
+ */
+export declare function isPortBindConflictMessage(message: string): boolean;
+//# sourceMappingURL=port-conflict.d.ts.map

package/dist/backend-docker/port-conflict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-conflict.d.ts","sourceRoot":"","sources":["../../src/backend-docker/port-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGlE"}

package/dist/backend-docker/port-conflict.js

@@ -0,0 +1,12 @@
+/**
+ * The daemon has no distinct exception type for a host-port bind conflict —
+ * only free-text in a 500 response body, such as "driver failed programming
+ * external connectivity: ... address already in use" or "Bind for
+ * 0.0.0.0:PORT failed: port is already allocated". Classify by message,
+ * case-insensitively.
+ */
+export function isPortBindConflictMessage(message) {
+    const m = message.toLowerCase();
+    return m.includes("already in use") || m.includes("already allocated");
+}
+//# sourceMappingURL=port-conflict.js.map

package/dist/backend-docker/port-conflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-conflict.js","sourceRoot":"","sources":["../../src/backend-docker/port-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAe;IACvD,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAChC,OAAO,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AACzE,CAAC"}

package/dist/backend-docker/provider.d.ts

@@ -0,0 +1,22 @@
+import type { BackendProvider, SandboxBackend } from "../core/backend.js";
+/**
+ * `isSupported()` must be synchronous (the interface's contract — see
+ * `../core/backend.ts`), but the daemon's real reachability probe
+ * (`GET /_ping`) is inherently async over `node:http`. Rather than fake a
+ * synchronous HTTP round trip, this resolves to "the socket path exists and
+ * is a socket" via `fs.statSync().isSocket()`, deferring true reachability
+ * to first use — an existing-but-dead daemon surfaces a clear error the
+ * moment a real call is made. A blocking `/_ping` here would be the
+ * stronger check, but JS has no synchronous socket I/O to do it with, and
+ * the stat is behaviorally equivalent for backend resolution since a socket
+ * file present but genuinely unreachable is vanishingly rare.
+ */
+export declare class DockerBackendProvider implements BackendProvider {
+    /** `"docker"` — matched case-insensitively against `RIGHTSIZE_BACKEND`. */
+    readonly name = "docker";
+    readonly priority = 10;
+    isSupported(): boolean;
+    unsupportedReason(): string;
+    create(): SandboxBackend;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/backend-docker/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/backend-docker/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAI1E;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,QAAQ,MAAM;IAEvB,WAAW,IAAI,OAAO;IAStB,iBAAiB,IAAI,MAAM;IAI3B,MAAM,IAAI,cAAc;CAGzB"}

package/dist/backend-docker/provider.js

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import { DockerBackend } from "./backend.js";
+import { DockerClient, socketPathFromDockerHost } from "./client.js";
+/**
+ * `isSupported()` must be synchronous (the interface's contract — see
+ * `../core/backend.ts`), but the daemon's real reachability probe
+ * (`GET /_ping`) is inherently async over `node:http`. Rather than fake a
+ * synchronous HTTP round trip, this resolves to "the socket path exists and
+ * is a socket" via `fs.statSync().isSocket()`, deferring true reachability
+ * to first use — an existing-but-dead daemon surfaces a clear error the
+ * moment a real call is made. A blocking `/_ping` here would be the
+ * stronger check, but JS has no synchronous socket I/O to do it with, and
+ * the stat is behaviorally equivalent for backend resolution since a socket
+ * file present but genuinely unreachable is vanishingly rare.
+ */
+export class DockerBackendProvider {
+    /** `"docker"` — matched case-insensitively against `RIGHTSIZE_BACKEND`. */
+    name = "docker";
+    priority = 10;
+    isSupported() {
+        const socketPath = socketPathFromDockerHost(process.env["DOCKER_HOST"]);
+        try {
+            return fs.statSync(socketPath).isSocket();
+        }
+        catch {
+            return false;
+        }
+    }
+    unsupportedReason() {
+        return "no reachable Docker-API socket (Docker/Podman/Colima not running?)";
+    }
+    create() {
+        return new DockerBackend(DockerClient.fromEnv());
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/backend-docker/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/backend-docker/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,qBAAqB;IAChC,2EAA2E;IAClE,IAAI,GAAG,QAAQ,CAAC;IAChB,QAAQ,GAAG,EAAE,CAAC;IAEvB,WAAW;QACT,MAAM,UAAU,GAAG,wBAAwB,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACxE,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,iBAAiB;QACf,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,aAAa,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;CACF"}

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

@@ -0,0 +1,169 @@
+import type { SandboxBackend, SandboxHandle, FollowHandle, NetworkLink } from "../core/backend.js";
+import type { ContainerSpec, ExecResult } from "../core/model.js";
+/**
+ * The attached-mode CLI driver: every sandbox this backend starts runs as a
+ * held child process (`msb run`, no `-d`) because detached mode never
+ * executes the image's own ENTRYPOINT/CMD — only attached mode does.
+ * Readiness is never inferred from that child's own output; it comes from
+ * polling `msb ls --format json` until the name shows `"Running"`. The
+ * attached child's stdout/stderr carries msb's own boot diagnostics and is
+ * kept only for pre-Running failure messages — it is not a dependable
+ * workload-log source (on Windows it does not relay guest stdout at all);
+ * workload logs are always fetched through the `msb logs` channel.
+ *
+ * `create()` on the `BackendProvider` interface is synchronous, but locating
+ * (and possibly downloading) the pinned `msb` binary is inherently async.
+ * The seam: this backend holds a memoized `ensureInstalled()` promise and
+ * every method awaits it once before doing anything else, so construction
+ * stays cheap and the actual provisioning happens lazily on first use.
+ */
+export declare class MsbCliBackend implements SandboxBackend {
+    private readonly msbPathPromise;
+    /** `"microsandbox"` — matched against `RIGHTSIZE_BACKEND` and used in `dev.rightsize.runId`-style diagnostics. */
+    readonly name = "microsandbox";
+    readonly supportsNativeNetworks = false;
+    private readonly handles;
+    private readonly startedNames;
+    private resolvedMsbPath;
+    constructor(msbPathPromise: Promise<string>);
+    private msbPath;
+    create(spec: ContainerSpec): Promise<SandboxHandle>;
+    /**
+     * Boots via `bootOnce`; on a first failure carrying msb's image-cache-
+     * corruption signature (see `isImageCacheCorruption`), heals by removing
+     * just the affected image's cache entry (`msb image remove <image>`, result
+     * ignored — including "image not found", since the real signal is whether
+     * the retried boot succeeds, not whether removal reported success) and
+     * retries the boot exactly once. A second identical failure surfaces an
+     * error naming the image and the attempted heal instead of retrying
+     * further. The heal is scoped to the one image reference — never the whole
+     * cache directory, and never any sandbox state.
+     *
+     * The failed first attempt never reached Running, so `state.attached` and
+     * `startedNames` (both populated only on success, inside `bootOnce`) carry
+     * no state from it to double-register, and its child has already been
+     * reaped there.
+     *
+     * Two corruption shapes were found empirically and the same one command
+     * heals both: the failing image's manifest was never committed to msb's
+     * cache database (a concurrent pull lost the race for a shared base layer
+     * before its own manifest write landed) — `image remove` reports "image not
+     * found" and the retry succeeds anyway, because by then the concurrent
+     * winner has finished materializing the shared layer — or the manifest IS
+     * committed but the cache file backing one of its layers is gone, where
+     * `image remove` clears the stale entry and the retry re-pulls from
+     * scratch.
+     */
+    start(handle: SandboxHandle): Promise<void>;
+    /**
+     * One boot attempt: spawns the attached `msb run` child and polls until the
+     * sandbox reaches Running. `state.attached` and `startedNames` are
+     * populated only on success; on any failure the child is reaped here (for
+     * the classified early-exit failures it has already exited; a readiness
+     * timeout leaves it alive and it is hard-killed) so a failed attempt leaves
+     * no live process or registered cleanup state behind — the caller owns
+     * retry policy, never cleanup. An early exit is classified from the child's
+     * combined output: the image-cache-corruption signature throws
+     * `ImageCacheCorruptionError` (the one failure `start()` heals and
+     * retries), a host-port bind conflict throws `PortBindConflictError`, and
+     * anything else surfaces the raw output.
+     */
+    private bootOnce;
+    stop(handle: SandboxHandle): Promise<void>;
+    remove(handle: SandboxHandle): Promise<void>;
+    private runningSandboxNames;
+    exec(handle: SandboxHandle, cmd: ReadonlyArray<string>): Promise<ExecResult>;
+    /**
+     * A fresh `msb logs <name> --tail 1000` invocation, same on every platform.
+     * This is the workload's own output, as distinct from the attached
+     * `msb run` child's pipe (drained in start() into a tail kept only for
+     * pre-Running crash diagnostics): on Windows the attached process does not
+     * relay guest stdout at all, while `msb logs` does everywhere, so this is
+     * the only channel this method can source from. Never rejects on a
+     * missing/removed sandbox — invoke() only rejects on spawn failure or
+     * timeout, never on exit code, so a failing `msb logs` call resolves with
+     * whatever (possibly empty) stdout it produced.
+     */
+    logs(handle: SandboxHandle): Promise<string>;
+    /**
+     * `msb logs -f` never exits once the sandbox stops (confirmed against the
+     * real msb binary — it blocks on read forever instead of the documented
+     * clean exit). A watchdog polls `msb ls` in the background; the instant
+     * the sandbox leaves Running it quiesces the stuck follow child FIRST
+     * (kill it, wait for the reader to finish draining whatever was already
+     * buffered) so `delivered` reflects everything the live stream will ever
+     * produce, THEN does one authoritative non-follow `msb logs` fetch and
+     * replays only the lines after `delivered` — guarded so that replay can
+     * only ever happen once. An explicit `close()` never triggers a replay:
+     * closing means the caller asked delivery to stop, not "catch me up."
+     *
+     * On Windows hosts this routes to `followLogsByPolling` instead: there,
+     * `msb logs -f` stays alive for the sandbox's whole run but never relays a
+     * single line to its stdout pipe while the sandbox is Running (confirmed
+     * against the real binary on a hosted windows-2025 runner — the same lines
+     * are retrievable through non-follow `msb logs` the whole time), so a
+     * pipe-reading follow child can never deliver a live line on Windows.
+     */
+    followLogs(handle: SandboxHandle, consumer: (line: string) => void): Promise<FollowHandle>;
+    /**
+     * Windows follow-logs path: no follow child at all. One async loop polls
+     * the non-follow `msb logs` fetch and delivers each fetch's not-yet-
+     * delivered lines, tracked by a monotonic `delivered` index — the same
+     * index-based diffing the POSIX watchdog's one-shot replay uses, made
+     * continuous. Delivery contract is identical to the POSIX path: in order,
+     * each line at most once, nothing after `close()`.
+     *
+     * A fetch's last line is held back only while the sandbox is Running AND
+     * the fetched text does not end with a newline: an unterminated tail may
+     * have been read mid-write, and delivering it early would split one
+     * workload line into two deliveries (the next fetch's index-diff would then
+     * skip its completed form). A newline-terminated tail is complete and
+     * delivers immediately — a workload that trickles complete lines while
+     * staying alive must see each line arrive live, not stall behind a
+     * holdback. Once the sandbox leaves Running, a final fetch (see
+     * `deliverTerminalTail`) delivers everything outstanding, including a
+     * trailing unterminated line.
+     *
+     * Every msb invocation this poller makes runs to completion strictly before
+     * the next one starts — exactly one in-flight child at a time from this
+     * code path. A failed `msb ls`/`msb logs` invocation — spawn error,
+     * timeout, or msb exiting non-zero (msb's own internal errors print to
+     * stderr and exit non-zero with EMPTY stdout, indistinguishable from a
+     * genuinely-empty response unless the exit code is checked) — is never read
+     * as "the sandbox stopped" or "the log is empty"; it retries.
+     */
+    private followLogsByPolling;
+    /**
+     * Delivers everything outstanding once the sandbox is confirmed no longer
+     * Running: retries the `msb logs` fetch only while it keeps failing to
+     * invoke at all (bounded by `TERMINAL_FETCH_FAILURE_BUDGET_MS`), and
+     * delivers from the very first successful fetch — withholding nothing,
+     * since a stopped sandbox's log cannot grow, so there is no more mid-write
+     * risk. This is the one place a trailing unterminated line reaches the
+     * consumer on Windows.
+     */
+    private deliverTerminalTail;
+    ensureNetwork(_networkId: string): Promise<void>;
+    removeNetwork(_networkId: string): Promise<void>;
+    /**
+     * Networks are emulated because there is no bridge/subnet the current
+     * msb exposes on macOS — the only data path into a running sandbox is the
+     * exec channel. Four concerns, each its own guard: reject duplicate guest
+     * ports, validate every alias (they get shell-interpolated), probe for
+     * `nc`, then install `/etc/hosts` aliases and spawn one tunnel per link.
+     */
+    installNetworkLinks(handle: SandboxHandle, links: ReadonlyArray<NetworkLink>): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Synchronous, blocking teardown for the process-exit path, where the
+     * event loop is not available to await this backend's normal async
+     * stop/remove. `spawnSync` is the one primitive Node offers that actually
+     * blocks the process here; failures are swallowed because the process is
+     * exiting regardless and there is no caller left to report them to.
+     */
+    cleanupSync(id: string): void;
+    /** Remove leftover `rz-<other-runid>-*` sandboxes from a crashed prior run — never this run's own. */
+    sweepOrphans(): Promise<void>;
+    private silently;
+}
+//# sourceMappingURL=backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/backend-msb/backend.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACnG,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAwJlE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAatC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAZ3C,kHAAkH;IAClH,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,sBAAsB,SAAS;IAExC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAKlD,OAAO,CAAC,eAAe,CAAqB;gBAEf,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC;YAa9C,OAAO;IAIf,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAKzD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjD;;;;;;;;;;;;OAYG;YACW,QAAQ;IAyDhB,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAiD1C,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;YAOpC,mBAAmB;IAK3B,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAKlF;;;;;;;;;;OAUG;IACG,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlD;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IA+DhG;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,mBAAmB;IAyE3B;;;;;;;;OAQG;YACW,mBAAmB;IAmC3B,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;;OAMG;IACG,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B5F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAsB7B,sGAAsG;IAChG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;YAQrB,QAAQ;CAIvB"}