@molecule/api-code-sandbox-docker 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -26,7 +26,50 @@
  * container/volume size (it needs specific storage drivers — e.g. overlay2 on xfs
  * with `pquota` — and errors on the common overlay2/ext4 host), so this provider
  * enforces none. The core `resources.diskMB` is accepted but not applied here; cap
- * disk at the host / volume level instead.
+ * disk at the host / volume level instead. `setResources({ diskMB })` THROWS
+ * rather than accepting a ceiling it cannot enforce.
+ *
+ * **Templates are not `commit` alone, and that is not an optimization.**
+ * `commitTemplate` copies the caller-named `capturePaths` into a throwaway,
+ * volume-less container and commits THAT. A sandbox keeps the project on a
+ * volume, and a volume is not part of a container's writable layer — so
+ * committing a sandbox directly yields an image that builds, tags, and boots
+ * with an empty workspace, with no error anywhere. The throwaway container
+ * handles tenant-authored bytes and is committed into something other tenants
+ * boot, so it runs with `--network none`, `CapDrop: ALL` plus the three
+ * capabilities extraction needs, a memory cap and a process cap, and setuid/setgid
+ * bits are stripped from the extracted tree afterwards.
+ *
+ * Templates live in their OWN repository (`templateRepository`, default
+ * `molecule-sandbox-template`) rather than sharing the base image's, so nothing
+ * written to sweep templates can reach the base image. `publishTemplate` /
+ * `fetchTemplate` use a Docker registry and require `templateRegistry`; without
+ * it they THROW rather than returning "not found", because "there is no shared
+ * store" and "the shared store does not have it" are different answers.
+ *
+ * **`hibernate()`/`resume()` report which mechanism ran.** A CRIU checkpoint
+ * preserves the process tree; a stop does not, and whether CRIU is available is a
+ * property of the host (the daemon's experimental flag plus the `criu` package),
+ * discovered at runtime. A sandbox that runs its dev servers as detached exec
+ * processes comes back from a stop-style wake alive and serving nothing, so
+ * callers must branch on `processesPreserved` — never on `status`, which says
+ * `running` either way. The first response that shows CRIU is unavailable
+ * disables it for the rest of the process.
+ *
+ * **`find()` costs one request per match.** Docker's container LIST omits
+ * `State.StartedAt`, which is the only field distinguishing an interrupted
+ * creation (`startedAt: null` — holds storage forever, will never run) from an
+ * ordinary stopped sandbox, so each match is then inspected. Narrow with
+ * `labels`; an unfiltered query on a busy host inspects every container.
+ *
+ * **`capacity()` measures THIS host, so it reports nothing for a TCP daemon.**
+ * Over a `tcp://` endpoint the daemon writes to a different machine's storage,
+ * and returning this machine's numbers would be a confident wrong answer — so it
+ * returns empty `headroom` and says why. On a local socket it reports free bytes
+ * and free inodes on the daemon's `DockerRootDir` plus `MemAvailable`. Inodes are
+ * omitted (not reported as zero) on filesystems with dynamic inode allocation.
+ * `admits` is always `null`: Docker has no quota of its own to consult, so the
+ * floors and the refusal stay with the caller.
  *
  * @module
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -26,7 +26,50 @@
  * container/volume size (it needs specific storage drivers — e.g. overlay2 on xfs
  * with `pquota` — and errors on the common overlay2/ext4 host), so this provider
  * enforces none. The core `resources.diskMB` is accepted but not applied here; cap
- * disk at the host / volume level instead.
+ * disk at the host / volume level instead. `setResources({ diskMB })` THROWS
+ * rather than accepting a ceiling it cannot enforce.
+ *
+ * **Templates are not `commit` alone, and that is not an optimization.**
+ * `commitTemplate` copies the caller-named `capturePaths` into a throwaway,
+ * volume-less container and commits THAT. A sandbox keeps the project on a
+ * volume, and a volume is not part of a container's writable layer — so
+ * committing a sandbox directly yields an image that builds, tags, and boots
+ * with an empty workspace, with no error anywhere. The throwaway container
+ * handles tenant-authored bytes and is committed into something other tenants
+ * boot, so it runs with `--network none`, `CapDrop: ALL` plus the three
+ * capabilities extraction needs, a memory cap and a process cap, and setuid/setgid
+ * bits are stripped from the extracted tree afterwards.
+ *
+ * Templates live in their OWN repository (`templateRepository`, default
+ * `molecule-sandbox-template`) rather than sharing the base image's, so nothing
+ * written to sweep templates can reach the base image. `publishTemplate` /
+ * `fetchTemplate` use a Docker registry and require `templateRegistry`; without
+ * it they THROW rather than returning "not found", because "there is no shared
+ * store" and "the shared store does not have it" are different answers.
+ *
+ * **`hibernate()`/`resume()` report which mechanism ran.** A CRIU checkpoint
+ * preserves the process tree; a stop does not, and whether CRIU is available is a
+ * property of the host (the daemon's experimental flag plus the `criu` package),
+ * discovered at runtime. A sandbox that runs its dev servers as detached exec
+ * processes comes back from a stop-style wake alive and serving nothing, so
+ * callers must branch on `processesPreserved` — never on `status`, which says
+ * `running` either way. The first response that shows CRIU is unavailable
+ * disables it for the rest of the process.
+ *
+ * **`find()` costs one request per match.** Docker's container LIST omits
+ * `State.StartedAt`, which is the only field distinguishing an interrupted
+ * creation (`startedAt: null` — holds storage forever, will never run) from an
+ * ordinary stopped sandbox, so each match is then inspected. Narrow with
+ * `labels`; an unfiltered query on a busy host inspects every container.
+ *
+ * **`capacity()` measures THIS host, so it reports nothing for a TCP daemon.**
+ * Over a `tcp://` endpoint the daemon writes to a different machine's storage,
+ * and returning this machine's numbers would be a confident wrong answer — so it
+ * returns empty `headroom` and says why. On a local socket it reports free bytes
+ * and free inodes on the daemon's `DockerRootDir` plus `MemAvailable`. Inodes are
+ * omitted (not reported as zero) on filesystems with dynamic inode allocation.
+ * `admits` is always `null`: Docker has no quota of its own to consult, so the
+ * floors and the refusal stay with the caller.
  *
  * @module
  */

package/dist/inspect.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Reading back what already exists — descriptors, queries, volumes, and live
+ * resource changes.
+ *
+ * These are the operations a control plane needs when it is NOT using a sandbox:
+ * reconciling its own records against the daemon, finding what leaked, applying
+ * an entitlement to a sandbox it just adopted. molecule.dev wrote all of them
+ * directly against the Docker socket precisely because the provider interface
+ * stopped at "make me a sandbox and let me run things in it".
+ *
+ * Two rules run through the whole module.
+ *
+ * **An empty list means "looked, found none".** Every enumeration here lets its
+ * failure propagate rather than degrading to `[]`. The caller of a sweep DELETES
+ * what it is told about, so "I could not enumerate" and "there is nothing" must
+ * never arrive as the same value.
+ *
+ * **When in doubt, claim the resource is in use.** Attachment and usage decide
+ * whether something gets deleted, so an unreadable answer resolves to the safe
+ * side, loudly, rather than to the convenient one.
+ *
+ * @module
+ */
+import type { ListVolumesOptions, SandboxDescriptor, SandboxQuery, SandboxResources, VolumeInfo } from '@molecule/api-code-sandbox';
+import type { DockerRequest } from './request.js';
+/** What the inspection capabilities need from the provider. */
+export interface InspectContext {
+    request: DockerRequest;
+    /** Label namespace the provider stamps on the sandboxes it creates. */
+    labelPrefix: string;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Shape of the fields this module reads from `GET /containers/{id}/json`. */
+interface ContainerInspect {
+    Id: string;
+    Created?: string;
+    Image?: string;
+    State?: {
+        Running?: boolean;
+        StartedAt?: string;
+    };
+    Config?: {
+        Labels?: Record<string, string>;
+        Image?: string;
+    };
+    Mounts?: Array<{
+        Type?: string;
+        Name?: string;
+    }>;
+    NetworkSettings?: {
+        Ports?: Record<string, Array<{
+            HostIp?: string;
+            HostPort?: string;
+        }> | null> | null;
+    };
+}
+/**
+ * Turn a Docker inspect payload into a provider-agnostic descriptor.
+ *
+ * The status mapping is deliberately the SAME coarse one `get()` uses
+ * (running / stopped) rather than a finer one. Two views of the same sandbox
+ * that disagree about its state is a bug generator, and the case a finer mapping
+ * would have served — never-started wreckage — is carried honestly by
+ * `startedAt: null` instead.
+ *
+ * @param ctx - Inspection context.
+ * @param info - The daemon's inspect payload.
+ * @returns The descriptor.
+ */
+export declare function toDescriptor(ctx: InspectContext, info: ContainerInspect): SandboxDescriptor;
+/**
+ * Describe one sandbox without building a handle for it.
+ *
+ * @param ctx - Inspection context.
+ * @param id - The sandbox id.
+ * @returns The descriptor, or `null` when no such sandbox exists.
+ */
+export declare function describeContainer(ctx: InspectContext, id: string): Promise<SandboxDescriptor | null>;
+/**
+ * Find sandboxes by the labels the caller put on them.
+ *
+ * Two passes on purpose. The list endpoint answers cheaply but omits
+ * `State.StartedAt`, which is the one field that distinguishes wreckage from a
+ * sandbox that is merely stopped — so each match is then inspected. The label
+ * filter is what keeps that bounded; an unfiltered query over a busy host is
+ * one request per container and the caller should narrow it.
+ *
+ * A container that disappears between the two passes is skipped, not failed:
+ * that is a real answer (it is gone), and reconciliation loops race removals
+ * constantly.
+ *
+ * @param ctx - Inspection context.
+ * @param query - Narrowing by label, status and project.
+ * @returns Descriptors for every match.
+ */
+export declare function findContainers(ctx: InspectContext, query?: SandboxQuery): Promise<SandboxDescriptor[]>;
+/**
+ * Enumerate named volumes and whether anything still has them attached.
+ *
+ * Attachment comes from Docker's `dangling` filter, which means "not used by any
+ * container, including stopped ones" — exactly the question a reclaim sweep is
+ * asking. When that second query fails, every volume is reported as ATTACHED and
+ * a warning is logged: an unreadable answer must not authorize deletion, and a
+ * volume is the only copy of a user's work.
+ *
+ * @param ctx - Inspection context.
+ * @param options - Narrowing by name prefix and attachment.
+ * @returns Every matching volume.
+ */
+export declare function listDockerVolumes(ctx: InspectContext, options?: ListVolumesOptions): Promise<VolumeInfo[]>;
+/**
+ * Change a running sandbox's resource ceilings.
+ *
+ * `Memory` and `MemorySwap` are always sent together, and swap is always twice
+ * RAM. Docker treats them as one setting — updating `Memory` alone leaves the old
+ * swap ceiling, and this call is the LAST writer on the adoption path, so a swap
+ * value that is not recomputed here silently strips the headroom the creation
+ * path granted. That is not hypothetical; it happened to every claimed sandbox.
+ *
+ * `diskMB` throws. A provider that cannot enforce a ceiling must say so, because
+ * the caller's alternative — believing the quota is applied — is worse than a
+ * visible failure.
+ *
+ * @param ctx - Inspection context.
+ * @param containerId - The sandbox to update.
+ * @param resources - The ceilings to change; omitted fields keep their value.
+ */
+export declare function updateContainerResources(ctx: InspectContext, containerId: string, resources: Partial<SandboxResources>): Promise<void>;
+export {};
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAA;IACtB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAChE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAClE;AASD,8EAA8E;AAC9E,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChD,eAAe,CAAC,EAAE;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAA;KACpF,CAAA;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,CA2B3F;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAYnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,cAAc,EACnB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAwB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CAkCvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/inspect.js

@@ -0,0 +1,212 @@
+/**
+ * Reading back what already exists — descriptors, queries, volumes, and live
+ * resource changes.
+ *
+ * These are the operations a control plane needs when it is NOT using a sandbox:
+ * reconciling its own records against the daemon, finding what leaked, applying
+ * an entitlement to a sandbox it just adopted. molecule.dev wrote all of them
+ * directly against the Docker socket precisely because the provider interface
+ * stopped at "make me a sandbox and let me run things in it".
+ *
+ * Two rules run through the whole module.
+ *
+ * **An empty list means "looked, found none".** Every enumeration here lets its
+ * failure propagate rather than degrading to `[]`. The caller of a sweep DELETES
+ * what it is told about, so "I could not enumerate" and "there is nothing" must
+ * never arrive as the same value.
+ *
+ * **When in doubt, claim the resource is in use.** Attachment and usage decide
+ * whether something gets deleted, so an unreadable answer resolves to the safe
+ * side, loudly, rather than to the convenient one.
+ *
+ * @module
+ */
+/**
+ * Docker's zero time. `State.StartedAt` holds it for a container that has been
+ * created and never started — the shape of an interrupted creation, which owns
+ * storage forever and will never run.
+ */
+const NEVER_STARTED = '0001-01-01T00:00:00Z';
+/**
+ * Turn a Docker inspect payload into a provider-agnostic descriptor.
+ *
+ * The status mapping is deliberately the SAME coarse one `get()` uses
+ * (running / stopped) rather than a finer one. Two views of the same sandbox
+ * that disagree about its state is a bug generator, and the case a finer mapping
+ * would have served — never-started wreckage — is carried honestly by
+ * `startedAt: null` instead.
+ *
+ * @param ctx - Inspection context.
+ * @param info - The daemon's inspect payload.
+ * @returns The descriptor.
+ */
+export function toDescriptor(ctx, info) {
+    const labels = info.Config?.Labels ?? {};
+    const startedAt = info.State?.StartedAt;
+    const volumeFromMount = (info.Mounts ?? []).find((mount) => mount.Type === 'volume')?.Name;
+    const ports = [];
+    for (const [spec, bindings] of Object.entries(info.NetworkSettings?.Ports ?? {})) {
+        const sandboxPort = Number.parseInt(spec.split('/')[0] ?? '', 10);
+        if (!Number.isInteger(sandboxPort))
+            continue;
+        for (const binding of bindings ?? []) {
+            const port = Number.parseInt(binding.HostPort ?? '', 10);
+            if (!Number.isInteger(port) || port <= 0)
+                continue;
+            ports.push({ sandboxPort, host: binding.HostIp || '127.0.0.1', port });
+        }
+    }
+    return {
+        id: info.Id,
+        projectId: labels[`${ctx.labelPrefix}.projectId`] ?? null,
+        status: info.State?.Running ? 'running' : 'stopped',
+        labels,
+        createdAt: info.Created ?? null,
+        startedAt: !startedAt || startedAt === NEVER_STARTED ? null : startedAt,
+        templateRef: info.Config?.Image ?? info.Image ?? null,
+        volumeName: labels[`${ctx.labelPrefix}.volumeName`] ?? volumeFromMount ?? null,
+        ports,
+    };
+}
+/**
+ * Describe one sandbox without building a handle for it.
+ *
+ * @param ctx - Inspection context.
+ * @param id - The sandbox id.
+ * @returns The descriptor, or `null` when no such sandbox exists.
+ */
+export async function describeContainer(ctx, id) {
+    try {
+        const info = (await ctx.request(`/containers/${id}/json`));
+        return toDescriptor(ctx, info);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // 404 is the answer "no such sandbox". Every other failure is a failure to
+        // look, and a caller that reads it as absence will happily "clean up" a
+        // sandbox that is alive and busy.
+        if (/\b404\b|no such container/i.test(message))
+            return null;
+        throw error;
+    }
+}
+/**
+ * Find sandboxes by the labels the caller put on them.
+ *
+ * Two passes on purpose. The list endpoint answers cheaply but omits
+ * `State.StartedAt`, which is the one field that distinguishes wreckage from a
+ * sandbox that is merely stopped — so each match is then inspected. The label
+ * filter is what keeps that bounded; an unfiltered query over a busy host is
+ * one request per container and the caller should narrow it.
+ *
+ * A container that disappears between the two passes is skipped, not failed:
+ * that is a real answer (it is gone), and reconciliation loops race removals
+ * constantly.
+ *
+ * @param ctx - Inspection context.
+ * @param query - Narrowing by label, status and project.
+ * @returns Descriptors for every match.
+ */
+export async function findContainers(ctx, query) {
+    const labelFilters = Object.entries(query?.labels ?? {}).map(([key, value]) => `${key}=${value}`);
+    if (query?.projectId)
+        labelFilters.push(`${ctx.labelPrefix}.projectId=${query.projectId}`);
+    const path = labelFilters.length > 0
+        ? `/containers/json?all=true&filters=${encodeURIComponent(JSON.stringify({ label: labelFilters }))}`
+        : '/containers/json?all=true';
+    // Not wrapped: a failed listing must reach the caller. A recovery loop that
+    // reads "nothing to recover" from a broken query silently stops recovering.
+    const listed = (await ctx.request(path));
+    const descriptors = [];
+    for (const entry of Array.isArray(listed) ? listed : []) {
+        const descriptor = await describeContainer(ctx, entry.Id);
+        if (!descriptor) {
+            ctx.debug?.('Sandbox vanished between listing and inspection', { id: entry.Id });
+            continue;
+        }
+        if (query?.statuses && !query.statuses.includes(descriptor.status))
+            continue;
+        descriptors.push(descriptor);
+    }
+    return descriptors;
+}
+/**
+ * Enumerate named volumes and whether anything still has them attached.
+ *
+ * Attachment comes from Docker's `dangling` filter, which means "not used by any
+ * container, including stopped ones" — exactly the question a reclaim sweep is
+ * asking. When that second query fails, every volume is reported as ATTACHED and
+ * a warning is logged: an unreadable answer must not authorize deletion, and a
+ * volume is the only copy of a user's work.
+ *
+ * @param ctx - Inspection context.
+ * @param options - Narrowing by name prefix and attachment.
+ * @returns Every matching volume.
+ */
+export async function listDockerVolumes(ctx, options) {
+    const listed = (await ctx.request('/volumes'));
+    let unattached = null;
+    try {
+        const dangling = (await ctx.request(`/volumes?filters=${encodeURIComponent(JSON.stringify({ dangling: ['true'] }))}`));
+        unattached = new Set((dangling.Volumes ?? []).map((volume) => volume.Name));
+    }
+    catch (error) {
+        ctx.warn?.('Could not determine volume attachment — reporting every volume as attached so nothing is reclaimed on a guess', { error });
+    }
+    const volumes = [];
+    for (const volume of listed.Volumes ?? []) {
+        if (options?.namePrefix && !volume.Name.startsWith(options.namePrefix))
+            continue;
+        const attached = unattached === null ? true : !unattached.has(volume.Name);
+        if (options?.attached !== undefined && options.attached !== attached)
+            continue;
+        const size = volume.UsageData?.Size;
+        volumes.push({
+            name: volume.Name,
+            attached,
+            createdAt: volume.CreatedAt ?? null,
+            // Docker reports -1 when it has not computed usage (that needs a
+            // system-wide scan), which is "unknown", not "empty".
+            sizeBytes: typeof size === 'number' && size >= 0 ? size : null,
+        });
+    }
+    return volumes;
+}
+/**
+ * Change a running sandbox's resource ceilings.
+ *
+ * `Memory` and `MemorySwap` are always sent together, and swap is always twice
+ * RAM. Docker treats them as one setting — updating `Memory` alone leaves the old
+ * swap ceiling, and this call is the LAST writer on the adoption path, so a swap
+ * value that is not recomputed here silently strips the headroom the creation
+ * path granted. That is not hypothetical; it happened to every claimed sandbox.
+ *
+ * `diskMB` throws. A provider that cannot enforce a ceiling must say so, because
+ * the caller's alternative — believing the quota is applied — is worse than a
+ * visible failure.
+ *
+ * @param ctx - Inspection context.
+ * @param containerId - The sandbox to update.
+ * @param resources - The ceilings to change; omitted fields keep their value.
+ */
+export async function updateContainerResources(ctx, containerId, resources) {
+    if (resources.diskMB !== undefined) {
+        throw new Error('The Docker sandbox provider cannot cap a container or volume size portably ' +
+            '(it needs a specific storage driver, e.g. overlay2 on xfs with pquota, and ' +
+            'errors on the common overlay2/ext4 host), so `diskMB` cannot be applied. ' +
+            'Cap disk at the host or volume level instead.');
+    }
+    const update = {};
+    if (resources.cpu !== undefined)
+        update.NanoCPUs = Math.round(resources.cpu * 1e9);
+    if (resources.memoryMB !== undefined) {
+        const memoryBytes = Math.round(resources.memoryMB * 1024 * 1024);
+        update.Memory = memoryBytes;
+        update.MemorySwap = memoryBytes * 2;
+    }
+    if (resources.pidsLimit !== undefined)
+        update.PidsLimit = resources.pidsLimit;
+    if (Object.keys(update).length === 0)
+        return;
+    await ctx.request(`/containers/${containerId}/update`, 'POST', update);
+}

package/dist/provider.d.ts

@@ -8,6 +8,20 @@
  */
 import type { SandboxProvider } from '@molecule/api-code-sandbox';
 import type { DockerConfig } from './types.js';
+/**
+ * Validate the ports a caller asked to publish, falling back to this provider's
+ * historical API + Vite pair when it named none.
+ *
+ * Rejects rather than filters: a caller that asked for a port it cannot have
+ * needs to hear so, because the alternative is a dev server running inside a
+ * sandbox that nothing on the outside can ever reach — which looks like a broken
+ * application, not a bad argument.
+ *
+ * @param ports - Ports inside the sandbox the caller wants reachable.
+ * @returns The ports to expose and bind.
+ * @throws {Error} When a port is not a valid TCP port number.
+ */
+export declare function resolvePublishPorts(ports?: number[]): number[];
 /**
  * Retry a Docker API operation that failed with a TRANSIENT fault — a request
  * timeout or a connection-level reset, i.e. the daemon was momentarily overwhelmed,

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAOV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAOnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA8I9C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAo3BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA6J9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AA21CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}