@zenera/sandbox 1.1.56 → 1.1.57

package/README.md

@@ -17,7 +17,8 @@ await sandbox.close();
 
 ## The contract
 
-- **`Sandbox`** - `exec`, background jobs (`startJob`, `readJob`, `stopJob`),
+- **`Sandbox`** - `prepare` (pull the image, or build it from `build:`),
+  `exec`, background jobs (`startJob`, `readJob`, `stopJob`),
   `close` at the end of a turn, and the files: `fs` (an `FsDriver`) and
   `files(view)`, which maps the host's workspace and mounts to the paths `fs`
   finds them at. The invariant: **a file written through `fs` is the file
@@ -27,10 +28,23 @@ await sandbox.close();
 - **`FsDriver`** - the filesystem seam, usable without a sandbox. `localFs` is
   this machine's disk; `InMemoryFs` keeps a tree in memory.
 
+## The image
+
+A spec names an `image` to pull, or a `build` (`{ dockerfile, context, args }`)
+to build. Getting it there is the sandbox's job, in `prepare()`: podman builds
+on this machine, a sandbox service on its own builders. What every backend
+shares is the build's identity, `buildIdentity(build)` - the context's files
+and the hash of them - so a project names the same image everywhere.
+`prepare({ onProgress, slow, force, allowBuild: false })` reports progress,
+rebuilds, or refuses to build at all; `start` does whatever of it is still
+needed. A failed build is an `ImageBuildError` (`isImageBuildError` checks it
+by name, across copies of this package).
+
 ## Implementations
 
 - **`PodmanSandbox`** / `podmanSandbox` - a podman container on this machine,
-  binding host directories, with `fs = localFs`.
+  binding host directories, with `fs = localFs`. `ensurePodmanImage` is its
+  image step on its own.
 - A sandbox that keeps its files with the container (a sandbox service) serves
   `fs` itself and returns `inSandboxPaths(view, fs)` from `files()`.
 

package/dist/contract.d.ts

@@ -10,6 +10,12 @@ export declare const DEFAULT_SANDBOX_IMAGE = "docker.io/library/python:3.14-slim
 export interface SandboxSpec {
     /** the base image commands run in */
     image?: string;
+    /**
+     * A Dockerfile to build instead of an image to pull. The sandbox builds it
+     * where it runs — podman on this machine, a service on its own builders —
+     * under a tag derived from its content; `image` is then ignored.
+     */
+    build?: BuildSpec;
     /** fractional cores, as podman's `--cpus` */
     cpus?: number;
     /** MiB, as podman's `--memory` */
@@ -40,6 +46,29 @@ export interface SandboxSpec {
     secrets?: readonly string[];
 }
 export type SandboxNetwork = 'bridge' | 'none' | 'host';
+/** A Dockerfile and what it may see. Paths are absolute and already checked by the host. */
+export interface BuildSpec {
+    dockerfile: string;
+    /** the build context: what `COPY` can reach */
+    context: string;
+    /** `--build-arg`s; part of the image's identity */
+    args?: Record<string, string>;
+}
+/** How a sandbox gets its image ready. */
+export interface PrepareOptions {
+    /** lines worth showing a person: what is being pulled or built, and how it ended */
+    onProgress?(line: string): void;
+    /** wraps a slow step — a pull, a build — so a host can show it is still going */
+    slow?<T>(label: string, work: Promise<T>): Promise<T>;
+    /** pull or build again even when the image is there; `zen sandbox pull` */
+    force?: boolean;
+    /**
+     * false: an image that would have to be built is a `SandboxError` instead —
+     * for a host whose images are built somewhere else, ahead of time.
+     */
+    allowBuild?: boolean;
+    signal?: AbortSignal;
+}
 /**
  * Two postures, because they cannot both be the default.
  *
@@ -114,6 +143,13 @@ export interface Sandbox {
     files(opts: FilesView): FilesView;
     /** whether anything was actually started — `close` is free when not */
     readonly started: boolean;
+    /**
+     * Makes the image available — pulled, or built from `build` — without
+     * starting anything, so a host can do the slow part before the first turn
+     * and show it. Idempotent and single-flight unless `force`; `start` does
+     * whatever of it is still needed.
+     */
+    prepare(opts?: PrepareOptions): Promise<void>;
     /** idempotent and single-flight; every other call starts the sandbox itself */
     start(): Promise<void>;
     exec(command: string, opts?: ExecOptions): Promise<ExecResult>;

package/dist/image.d.ts

@@ -0,0 +1,62 @@
+import { SandboxError, type BuildSpec, type PrepareOptions } from './contract.ts';
+import { type Runner } from './process.ts';
+/** Where locally built images are tagged. Not scoped: a `/` or an `@` is not a legal tag. */
+export declare const LOCAL_IMAGE_REPO = "localhost/zenera-sandbox";
+/**
+ * A build context is meant to be small — a Dockerfile and whatever it copies.
+ * Hashing a directory someone pointed at their whole home folder would hang
+ * before it was wrong, so it stops and says which key to narrow.
+ */
+export declare const MAX_CONTEXT_FILES = 2000;
+/** What a build is made of: the address every backend agrees on. */
+export interface BuildIdentity {
+    /** 12 hex characters; the tag a build is known by */
+    hash: string;
+    /** every file in the context, relative and sorted — exactly what was hashed */
+    files: readonly string[];
+}
+/**
+ * The content address of a build: the Dockerfile, then every file the build can
+ * see, by path and by content, then its arguments.
+ *
+ * `.dockerignore` is not read. The engine honours it and this does not, so an
+ * ignored file that changes yields a new tag and a build that produces the same
+ * image — wasteful, never wrong, and the alternative is reimplementing a match
+ * syntax whose disagreements would be silent.
+ */
+export declare function buildIdentity(spec: BuildSpec): BuildIdentity;
+/** The tag a build is run under on this machine. */
+export declare function localImageTag(build: BuildSpec | BuildIdentity): string;
+/**
+ * A build that ran and failed, rather than an engine that could not be asked.
+ * Both stop a run, but only one of them is the project's fault: `zen check`
+ * reports a Dockerfile that does not build as an error, and a laptop without
+ * podman as a warning.
+ */
+export declare class ImageBuildError extends SandboxError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Whether `err` is a failed build, by name rather than by class: a plugin
+ * that provides the sandbox may bring its own copy of this package, and its
+ * `ImageBuildError` is then a different class that means the same thing.
+ */
+export declare function isImageBuildError(err: unknown): err is ImageBuildError;
+/**
+ * Puts the image on this machine's engine: nothing when it is already there,
+ * a build when the spec names a Dockerfile, a pull otherwise.
+ *
+ * Skipping a present build is safe in a way it would not be for an ordinary
+ * tag, because this one is a hash of the Dockerfile and its context: the image
+ * existing *means* the content is unchanged. What it does not cover is a moved
+ * base image — `podman build` reuses whatever `FROM node:24` resolved to last
+ * time — which is what `force` is for.
+ */
+export declare function ensurePodmanImage(target: {
+    image: string;
+    build?: BuildSpec;
+}, host?: {
+    engine?: string;
+    exec?: Runner;
+}, opts?: PrepareOptions): Promise<void>;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { SandboxError } from "./contract.js";
+import { runProcess } from "./process.js";
+// ---------------------------------------------------------------------------
+// The sandbox image
+//
+// `image:` names something to pull; `build:` names a Dockerfile to build. Both
+// end as an image a sandbox runs, and getting it there is the sandbox's job:
+// podman builds on this machine, a sandbox service builds wherever it builds.
+// What they share is the *identity* of a build — which files go in and what
+// they hash to — so a project names the same image on every backend.
+//
+// The tag is a function of what goes into the image, and it has to be: a
+// container's name hashes its image, so a tag that stayed put while the
+// Dockerfile changed would leave a `persist: true` container running last
+// week's filesystem, with nothing anywhere saying so. Hashing the context as
+// well as the Dockerfile means an edit to either yields a new tag, a new
+// container name, and a build — which is the only honest answer.
+// ---------------------------------------------------------------------------
+/** Where locally built images are tagged. Not scoped: a `/` or an `@` is not a legal tag. */
+export const LOCAL_IMAGE_REPO = 'localhost/zenera-sandbox';
+/**
+ * A build context is meant to be small — a Dockerfile and whatever it copies.
+ * Hashing a directory someone pointed at their whole home folder would hang
+ * before it was wrong, so it stops and says which key to narrow.
+ */
+export const MAX_CONTEXT_FILES = 2_000;
+/**
+ * The content address of a build: the Dockerfile, then every file the build can
+ * see, by path and by content, then its arguments.
+ *
+ * `.dockerignore` is not read. The engine honours it and this does not, so an
+ * ignored file that changes yields a new tag and a build that produces the same
+ * image — wasteful, never wrong, and the alternative is reimplementing a match
+ * syntax whose disagreements would be silent.
+ */
+export function buildIdentity(spec) {
+    const hash = createHash('sha256');
+    hash.update(readFileSync(spec.dockerfile));
+    const files = walk(spec.context);
+    for (const rel of files) {
+        // The separator is hashed as posix so the same tree tags the same on
+        // any host.
+        hash.update(`\0${rel.split(sep).join('/')}\0`);
+        hash.update(readFileSync(join(spec.context, rel)));
+    }
+    // Only when there are any, so a build without arguments keeps the tag it
+    // had before arguments existed.
+    const args = Object.entries(spec.args ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    if (args.length > 0) {
+        hash.update(`\0args\0${JSON.stringify(args)}`);
+    }
+    return { hash: hash.digest('hex').slice(0, 12), files };
+}
+/** The tag a build is run under on this machine. */
+export function localImageTag(build) {
+    const id = 'hash' in build ? build : buildIdentity(build);
+    return `${LOCAL_IMAGE_REPO}:${id.hash}`;
+}
+/** Every file under `dir`, relative and sorted, so the digest is stable. */
+function walk(dir) {
+    const found = [];
+    const pending = [dir];
+    while (pending.length > 0) {
+        const at = pending.pop();
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(path);
+            }
+            else if (entry.isFile()) {
+                found.push(relative(dir, path));
+            }
+        }
+        if (found.length > MAX_CONTEXT_FILES) {
+            throw new SandboxError(`sandbox.build.context: ${dir} holds more than ${MAX_CONTEXT_FILES} files`, 'point `context:` at the directory the build actually copies from');
+        }
+    }
+    return found.sort();
+}
+// ---------------------------------------------------------------------------
+// On this machine
+// ---------------------------------------------------------------------------
+/**
+ * A build that ran and failed, rather than an engine that could not be asked.
+ * Both stop a run, but only one of them is the project's fault: `zen check`
+ * reports a Dockerfile that does not build as an error, and a laptop without
+ * podman as a warning.
+ */
+export class ImageBuildError extends SandboxError {
+    constructor(message, hint) {
+        super(message, hint);
+        this.name = 'ImageBuildError';
+    }
+}
+/**
+ * Whether `err` is a failed build, by name rather than by class: a plugin
+ * that provides the sandbox may bring its own copy of this package, and its
+ * `ImageBuildError` is then a different class that means the same thing.
+ */
+export function isImageBuildError(err) {
+    return err instanceof Error && err.name === 'ImageBuildError';
+}
+/** Pulling is slow on purpose... */
+const PULL_MS = 600_000;
+/** ...and a build from a cold cache is slower still. */
+const BUILD_MS = 900_000;
+/**
+ * Images this process has already settled, per runner and per engine. A batch
+ * opens the same project dozens of times at once, and without this each one
+ * asks podman and the concurrent copies race each other to pull or build the
+ * very same image. Keyed by runner too, so a test's fake engine never inherits
+ * an answer the real one gave.
+ */
+const settled = new WeakMap();
+/**
+ * Puts the image on this machine's engine: nothing when it is already there,
+ * a build when the spec names a Dockerfile, a pull otherwise.
+ *
+ * Skipping a present build is safe in a way it would not be for an ordinary
+ * tag, because this one is a hash of the Dockerfile and its context: the image
+ * existing *means* the content is unchanged. What it does not cover is a moved
+ * base image — `podman build` reuses whatever `FROM node:24` resolved to last
+ * time — which is what `force` is for.
+ */
+export function ensurePodmanImage(target, host = {}, opts = {}) {
+    const engine = host.engine ?? 'podman';
+    const run = host.exec ?? runProcess;
+    let byKey = settled.get(run);
+    if (!byKey) {
+        byKey = new Map();
+        settled.set(run, byKey);
+    }
+    const key = `${engine}::${target.image}`;
+    const pending = byKey.get(key);
+    if (pending && !opts.force) {
+        return pending;
+    }
+    const attempt = obtain(engine, run, target, opts).catch((err) => {
+        // A failure is not a settled answer: the user may fix the Dockerfile
+        // and try again in the same process.
+        byKey.delete(key);
+        throw err;
+    });
+    byKey.set(key, attempt);
+    return attempt;
+}
+async function obtain(engine, run, target, opts) {
+    const say = (line) => opts.onProgress?.(line);
+    const slow = (label, work) => opts.slow ? opts.slow(label, work) : work;
+    const tail = (res) => {
+        for (const line of res.stderr.split('\n').slice(-3)) {
+            if (line.trim()) {
+                say(`  ${line.trim()}`);
+            }
+        }
+    };
+    if (!opts.force) {
+        const present = await run(engine, ['image', 'exists', target.image], {
+            timeoutMs: 30_000,
+        });
+        if (present.code === 0) {
+            return;
+        }
+    }
+    const build = target.build;
+    if (build) {
+        if (opts.allowBuild === false) {
+            throw new SandboxError(`the sandbox image ${target.image} is not built`, 'build it before running: `zen sandbox up` builds it on this machine');
+        }
+        say(`${opts.force ? 'rebuilding' : 'building'} the sandbox image from ${build.dockerfile}`);
+        say('  the agent runs its commands inside a container, so the image is needed first');
+        say('  this takes a few minutes; later runs reuse it');
+        const args = Object.entries(build.args ?? {}).flatMap(([k, v]) => [
+            '--build-arg',
+            `${k}=${v}`,
+        ]);
+        const built = await slow('building the sandbox image', run(engine, [
+            'build',
+            '--tag',
+            target.image,
+            '--file',
+            build.dockerfile,
+            ...args,
+            build.context,
+        ], { timeoutMs: BUILD_MS, signal: opts.signal }));
+        tail(built);
+        if (built.code !== 0) {
+            throw new ImageBuildError(`could not build ${build.dockerfile}`, last(built) || 'run the build by hand to see what the engine says');
+        }
+        return;
+    }
+    say(`pulling ${target.image} — this happens once`);
+    const pulled = await slow('pulling', run(engine, ['pull', target.image], { timeoutMs: PULL_MS, signal: opts.signal }));
+    tail(pulled);
+    if (pulled.code !== 0) {
+        throw new SandboxError(`could not pull ${target.image}`, first(pulled) || 'check the image name and your network');
+    }
+}
+function first(res) {
+    return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
+}
+/** A build says what went wrong on its last line, not its first. */
+function last(res) {
+    const lines = (res.stderr.trim() || res.stdout.trim()).split('\n').filter((l) => l.trim());
+    return lines.slice(-2).join(' — ');
+}
+//# sourceMappingURL=image.js.map

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './contract.ts';
 export * from './fs.ts';
+export * from './image.ts';
 export * from './in-memory-fs.ts';
 export * from './limits.ts';
 export * from './mounts.ts';

package/dist/index.js

@@ -3,6 +3,7 @@
 // can all stand on the same contract. Contract tests: `@zenera/sandbox/testing`.
 export * from "./contract.js";
 export * from "./fs.js";
+export * from "./image.js";
 export * from "./in-memory-fs.js";
 export * from "./limits.js";
 export * from "./mounts.js";

package/dist/podman.d.ts

@@ -1,7 +1,7 @@
 import { type FsDriver } from './fs.ts';
 import { type FilesView, type Mount } from './mounts.ts';
 import { type Runner } from './process.ts';
-import { type Sandbox, type SandboxFactory, type ExecOptions, type ExecResult, type JobOutput, type JobStopped, type SandboxOptions, type SandboxSpec } from './contract.ts';
+import { type BuildSpec, type PrepareOptions, type Sandbox, type SandboxFactory, type ExecOptions, type ExecResult, type JobOutput, type JobStopped, type SandboxOptions, type SandboxSpec } from './contract.ts';
 /** What only a podman sandbox needs: which binary to drive, and how to spawn it. */
 export interface PodmanHost {
     /** the container engine binary; `podman` when unset */
@@ -9,8 +9,10 @@ export interface PodmanHost {
     /** how processes are spawned — the seam tests replace */
     exec?: Runner;
 }
-interface Resolved extends Required<Omit<SandboxSpec, 'user'>> {
+interface Resolved extends Required<Omit<SandboxSpec, 'user' | 'build'>> {
     user?: string;
+    /** the Dockerfile `image` is built from, when it is */
+    build?: BuildSpec;
     root: string;
     key: string;
     readOnly: boolean;
@@ -37,6 +39,8 @@ export declare class PodmanSandbox implements Sandbox {
     get started(): boolean;
     /** The host paths, as they are: the container binds exactly these. */
     files(opts: FilesView): FilesView;
+    /** Pulls the image, or builds it from the Dockerfile, unless the engine already has it. */
+    prepare(opts?: PrepareOptions): Promise<void>;
     /**
      * Idempotent, and single-flight: several tool calls in one batch all await
      * the same start rather than racing to create the same container.

package/dist/podman.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
+import { ensurePodmanImage, localImageTag } from "./image.js";
 import { localFs } from "./fs.js";
 import { sandboxLimits } from "./limits.js";
 import { WORKSPACE_MOUNT } from "./mounts.js";
@@ -51,15 +52,18 @@ export class PodmanSandbox {
     spec;
     engine;
     #run;
+    #spawn;
     #jobs = new Map();
     #ready;
+    #prepared;
     #created = false;
     /** kills counted in this container's cgroup as of the last probe */
     #kills;
     constructor(opts, host = {}) {
         this.spec = resolveSpec(opts);
         this.engine = host.engine ?? 'podman';
-        this.#run = resilient(host.exec ?? runProcess);
+        this.#spawn = host.exec ?? runProcess;
+        this.#run = resilient(this.#spawn);
         this.name = containerName(this.spec);
     }
     /** Whether anything was actually started — `close` is free when not. */
@@ -70,6 +74,17 @@ export class PodmanSandbox {
     files(opts) {
         return { ...opts, fs: this.fs };
     }
+    /** Pulls the image, or builds it from the Dockerfile, unless the engine already has it. */
+    prepare(opts = {}) {
+        if (this.#prepared && !opts.force) {
+            return this.#prepared;
+        }
+        this.#prepared = ensurePodmanImage({ image: this.spec.image, build: this.spec.build }, { engine: this.engine, exec: this.#spawn }, opts).catch((err) => {
+            this.#prepared = undefined;
+            throw err;
+        });
+        return this.#prepared;
+    }
     /**
      * Idempotent, and single-flight: several tool calls in one batch all await
      * the same start rather than racing to create the same container.
@@ -99,6 +114,10 @@ export class PodmanSandbox {
             this.#created = true;
             return;
         }
+        // `run` pulls a registry image by itself; a built one has to exist first.
+        if (this.spec.build) {
+            await this.prepare();
+        }
         const made = await this.#podman(this.#createArgs());
         if (made.code !== 0) {
             throw new SandboxError(`could not create container ${this.name}: ${message(made)}`, LOCKS.test(made.stderr) ? locksHint(this.engine) : undefined);
@@ -489,7 +508,8 @@ function resolveSpec(opts) {
     return {
         root: opts.root,
         key: opts.key,
-        image: opts.image ?? DEFAULT_SANDBOX_IMAGE,
+        image: opts.build ? localImageTag(opts.build) : (opts.image ?? DEFAULT_SANDBOX_IMAGE),
+        build: opts.build,
         cpus: limits.cpus,
         memory: limits.memory,
         explicitCpus: opts.cpus !== undefined,

package/dist/testing.js

@@ -102,6 +102,12 @@ export function describeSandbox(name, make, opts = {}) {
             expect(await sandbox.stopJob(id)).toMatchObject({ job_id: id, stopped: true });
             await expect(sandbox.readJob('job-unknown')).rejects.toBeInstanceOf(SandboxError);
         }), timeout);
+        it('prepares its image without starting, once however often it is asked', withSandbox(async ({ sandbox }) => {
+            await Promise.all([sandbox.prepare(), sandbox.prepare()]);
+            await sandbox.prepare();
+            expect(sandbox.started).toBe(false);
+            expect((await sandbox.exec('echo ready')).stdout).toBe('ready\n');
+        }), timeout);
         it('is free to close, and closes once', withSandbox(async ({ sandbox }) => {
             await sandbox.exec('true');
             await sandbox.close();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/sandbox",
-    "version": "1.1.56",
+    "version": "1.1.57",
     "description": "Where an agent's commands run and the files they see: the Sandbox contract, a podman implementation, filesystem drivers and a contract test suite for other implementations.",
     "keywords": [
         "sandbox",