bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/presets/providers/e2b.ts

@@ -1,130 +0,0 @@
-// E2B: Firecracker sandboxes over the e2b SDK. The default "base" template is Debian with bash, git, curl,
-// node and gh, run as a user with a writable $HOME.
-//
-// template() builds an E2B template from the Dockerfile; the E2B builder ignores SHELL, and COPY or ADD from a local context does not work since spec Dockerfiles have none.
-//
-// options: { apiKey? (secret source, else E2B_API_KEY), template? (default "base"), timeoutMinutes? (default 60) }
-import { PassThrough, Writable } from "node:stream";
-import type { BoxStream, ExecResult, ProviderFactory } from "../../src/types.ts";
-import type { CommandResult, Sandbox as SandboxT } from "e2b";
-
-const e2b: ProviderFactory = async ({ options, secret, log }) => {
-  const { Sandbox, Template, ApiClient, ConnectionConfig, CommandExitError, NotFoundError } = await import("e2b");
-  const apiKey: string | undefined = options.apiKey ? secret(options.apiKey) : undefined;
-  // ponytail: a box dies this long after bottleship last touched it, and E2B caps a box's whole life at 1h (Hobby) or 24h (Pro); pause/resume lifecycle if agents run longer
-  const timeoutMs = (options.timeoutMinutes ?? 60) * 60_000;
-
-  // connecting also extends the box's timeout, so every exec and status keeps a box someone checks on alive
-  const boxes = new Map<string, { sbx: SandboxT; at: number }>();
-  async function box(id: string): Promise<SandboxT> {
-    const hit = boxes.get(id);
-    if (hit && Date.now() - hit.at < 60_000) return hit.sbx;
-    const sbx = await Sandbox.connect(id, { apiKey, timeoutMs });
-    boxes.set(id, { sbx, at: Date.now() });
-    return sbx;
-  }
-
-  const result = (r: CommandResult): ExecResult => ({ code: r.exitCode, stdout: r.stdout, stderr: r.stderr });
-  // a non-zero exit is a result, not an error
-  const settle = (p: Promise<CommandResult>) => p.then(result, (e) => {
-    if (e instanceof CommandExitError) return result(e);
-    throw e;
-  });
-
-  // the id of this team's template named name with a finished build; a bare name can also resolve to another team's public template, so names are never handed to create
-  async function ownTemplate(name: string): Promise<string | undefined> {
-    const { api } = new ApiClient(new ConnectionConfig({ apiKey }));
-    let nextToken: string | undefined;
-    do {
-      const res = await api.GET("/v2/templates", { params: { query: { limit: 100, nextToken } } });
-      if (!res.data) throw new Error(`e2b could not list templates: ${res.response.status} ${JSON.stringify(res.error)}`);
-      const hit = res.data.find((t) => !t.isDefault && t.buildStatus === "ready" && t.names.some((n) => n === name || n.endsWith(`/${name}`)));
-      if (hit) return hit.templateID;
-      nextToken = res.response.headers.get("X-Next-Token") || undefined;
-    } while (nextToken);
-  }
-
-  return {
-    // ponytail: two inits racing on one name both build, E2B keeps the later build; fine since both come from the same Dockerfile
-    async template({ name, dockerfile }) {
-      const found = await ownTemplate(name);
-      if (found) return found;
-      const built = await Template.build(Template().fromDockerfile(dockerfile), name, { apiKey, onBuildLogs: (e) => log(String(e)) });
-      return built.templateId;
-    },
-
-    // the bottleship id goes into metadata; E2B picks the sandbox id
-    async create({ id, template }) {
-      const sbx = await Sandbox.create(template ?? options.template ?? "base", { apiKey, timeoutMs, metadata: { bottleship: id } });
-      await sbx.commands.run("true");
-      boxes.set(sbx.sandboxId, { sbx, at: Date.now() });
-      return { id: sbx.sandboxId };
-    },
-
-    // the SDK runs `bash -l -c <script>`; timeoutMs 0 lifts its 60 second command limit
-    async exec(id, script, { stdin } = {}) {
-      const sbx = await box(id);
-      if (stdin === undefined) return settle(sbx.commands.run(script, { timeoutMs: 0 }));
-      const h = await sbx.commands.run(script, { background: true, stdin: true, timeoutMs: 0 });
-      if (stdin.length) await h.sendStdin(stdin);
-      await h.closeStdin();
-      return settle(h.wait());
-    },
-
-    // ponytail: the SDK hands output over as UTF-8 text, so binary stdout gets mangled; fine for text protocols
-    async openStream(id, script): Promise<BoxStream> {
-      const sbx = await box(id);
-      const stdout = new PassThrough();
-      const stderr = new PassThrough();
-      const h = await sbx.commands.run(script, {
-        background: true,
-        stdin: true,
-        timeoutMs: 0,
-        onStdout: (d) => void stdout.write(d),
-        onStderr: (d) => void stderr.write(d),
-      });
-      let code: number | null | undefined;
-      const closers: ((code?: number | null) => void)[] = [];
-      const done = h.wait().then(
-        (r) => r.exitCode,
-        (e) => (e instanceof CommandExitError ? e.exitCode : null),
-      );
-      void done.then((c) => {
-        code = c;
-        stdout.end();
-        stderr.end();
-        closers.splice(0).forEach((cb) => cb(c));
-      });
-      // Writable runs one write at a time, so stdin arrives in order
-      const stdin = new Writable({
-        write: (chunk: Buffer, _enc, cb) => void h.sendStdin(chunk).then(() => cb(), cb),
-        final: (cb) => void h.closeStdin().then(() => cb(), cb),
-      });
-      stdin.on("error", () => {});
-      return {
-        stdin,
-        stdout,
-        stderr,
-        close: () => void h.kill().catch(() => {}),
-        onClose: (cb) => (code === undefined ? closers.push(cb) : cb(code)),
-      };
-    },
-
-    async status(id) {
-      boxes.delete(id);
-      try {
-        await box(id);
-        return "running";
-      } catch (e) {
-        if (e instanceof NotFoundError) return "gone";
-        throw e;
-      }
-    },
-
-    async destroy(id) {
-      boxes.delete(id);
-      return Sandbox.kill(id, { apiKey });
-    },
-  };
-};
-export default e2b;

package/presets/providers/exe.ts

@@ -1,35 +0,0 @@
-// exe.dev: VMs over ssh. Needs `ssh exe.dev` working on this machine (your exe.dev ssh key).
-//
-// options: { tag? (default "bottleship") }
-//
-// No template(): exe.dev boots VMs only from registry images (`new --image`), and bottleship has no registry to push a built image to.
-// `cp` clones a VM, but a VM built by running the Dockerfile over ssh keeps root as its ssh login user, so it would not match the spec.
-import { run, shq, spawnStream } from "./util.ts";
-import type { ProviderFactory } from "../../src/types.ts";
-
-const SSH = ["-o", "StrictHostKeyChecking=accept-new", "-o", "BatchMode=yes", "-o", "ServerAliveInterval=15"];
-const host = (id: string) => `${id}.exe.xyz`;
-const remote = (id: string, script: string) => [...SSH, "-T", host(id), `bash -c ${shq(script)}`];
-const reachable = async (id: string, timeout: number) =>
-  (await run("ssh", [...SSH, "-o", `ConnectTimeout=${timeout}`, host(id), "true"], { check: false })).code === 0;
-
-const exe: ProviderFactory = ({ options }) => ({
-  async create({ id }) {
-    await run("ssh", [...SSH, "exe.dev", "new", `--name=${id}`, `--tag=${options.tag ?? "bottleship"}`, "--no-email", "--json"]);
-    // ponytail: fixed 2 minute poll for sshd; make it an option if VMs boot slower
-    for (let i = 0; i < 60; i++) {
-      if (await reachable(id, 5)) return { id };
-      await new Promise((res) => setTimeout(res, 2000));
-    }
-    throw new Error(`exe VM ${id} never answered ssh`);
-  },
-
-  exec: (id, script, { stdin } = {}) => run("ssh", remote(id, script), { stdin, check: false }),
-
-  openStream: (id, script) => spawnStream("ssh", remote(id, script)),
-
-  status: async (id) => ((await reachable(id, 8)) ? "running" : "gone"),
-
-  destroy: (id) => run("ssh", [...SSH, "exe.dev", "rm", id], { check: false }),
-});
-export default exe;

package/presets/providers/http.example.ts

@@ -1,64 +0,0 @@
-// TEMPLATE for a sandbox system with an HTTP API (no CLI). Copy it to
-// ~/.bottleship/providers/<name>.ts and replace every TODO with the real API.
-// Node runs it directly (types are stripped); the `import type` below is erased,
-// so it doesn't need to resolve at runtime. Plain .mjs works too.
-// The endpoints below are made up; they show the shape, not a real service.
-//
-// config.json:
-//   "providers": { "corp": { "module": "providers/corp.ts", "baseUrl": "https://sandboxes.corp.example/api",
-//                            "apiKey": { "store": "corp-sandbox" } } }
-// `bottleship init` asks for the apiKey once and stores it; it never goes into a box.
-//
-// Required: create, exec, destroy. Recommended: status. Optional: openStream (for `bottleship exec -i`).
-// The full contract is the Provider interface in bottleship's src/types.ts.
-import type { ProviderFactory } from "../../src/types.ts"; // in ~/.bottleship/providers: from "bottleship"
-
-const corp: ProviderFactory = ({ options, secret, kit }) => {
-  const base: string = options.baseUrl;
-  const headers = () => ({ authorization: `Bearer ${secret(options.apiKey)}`, "content-type": "application/json" });
-  const api = async (method: string, path: string, body?: unknown): Promise<any> => {
-    const res = await fetch(`${base}${path}`, { method, headers: headers(), body: body ? JSON.stringify(body) : undefined });
-    if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);
-    return res.status === 204 ? null : res.json();
-  };
-
-  return {
-    async create({ id }) {
-      // TODO: real create call. Wait until the box can run commands before returning.
-      // Boxes must stay up until destroy(): the agent runs in the background between bottleship calls.
-      const box = await api("POST", "/sandboxes", { name: id, template: options.template });
-      for (let i = 0; i < 60; i++) {
-        const s = await api("GET", `/sandboxes/${box.id}`);
-        if (s.state === "running") return { id: box.id };
-        await new Promise((r) => setTimeout(r, 2000));
-      }
-      throw new Error(`sandbox ${box.id} did not start`);
-    },
-
-    async exec(id, script, { stdin } = {}) {
-      // TODO: one-shot command. Must run `bash -c <script>` and feed `stdin` if given.
-      const r = await api("POST", `/sandboxes/${id}/exec`, { cmd: ["bash", "-c", script], stdin: stdin?.toString() ?? "" });
-      return { code: r.exitCode, stdout: r.stdout, stderr: r.stderr };
-    },
-
-    // TODO: if the API has a streaming exec (websocket/attach), wire it here; it must be binary-clean.
-    // Delete this method if it doesn't; only `bottleship exec -i` needs it.
-    openStream(id, script) {
-      return kit.wsStream(`${base.replace(/^http/, "ws")}/sandboxes/${id}/exec/stream?cmd=${encodeURIComponent(script)}`, headers());
-    },
-
-    async status(id) {
-      try {
-        const s = await api("GET", `/sandboxes/${id}`);
-        return s.state === "running" ? "running" : "gone";
-      } catch {
-        return "gone";
-      }
-    },
-
-    async destroy(id) {
-      await api("DELETE", `/sandboxes/${id}`).catch(() => {});
-    },
-  };
-};
-export default corp;

package/presets/providers/local.ts

@@ -1,56 +0,0 @@
-// Boxes on this machine: each box is a directory used as $HOME, and its ~/workspace is a git worktree
-// of your local repo on branch bottleship/<id> (a plain directory when the task has no local repo).
-// No isolation: box scripts run as you, with your PATH and network, so only use it with agents you trust.
-// Boxes stop when the machine sleeps.
-//
-// options: { root? (default /tmp/bottleship-local) }
-import { appendFileSync, existsSync, mkdirSync, rmSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { killBoxScript, run, shq, spawnStream } from "./util.ts";
-import type { ProviderFactory } from "../../src/types.ts";
-
-const local: ProviderFactory = ({ options }) => {
-  const root = resolve(options.root ?? "/tmp/bottleship-local");
-  const dir = (id: string) => {
-    // ids become directory names under root, and destroy rm -rf's them
-    if (!id || basename(id) !== id || id.startsWith(".")) throw new Error(`local provider: bad box id ${JSON.stringify(id)}`);
-    return join(root, id);
-  };
-  // every exec is marked as the box's and runs in its own process group, recorded next to the box, so destroy finds what it left behind
-  const groups = (id: string) => join(root, `.${id}.pgids`);
-  const box = (id: string) => ({ cwd: dir(id), env: { HOME: dir(id), BOTTLESHIP_BOX: dir(id) }, detached: true, onSpawn: (pid: number) => appendFileSync(groups(id), `${pid}\n`) });
-
-  // a worktree's .git is a file pointing into the source repo; removing it there keeps the branch
-  async function removeWorktree(ws: string) {
-    if (!existsSync(join(ws, ".git")) || !statSync(join(ws, ".git")).isFile()) return;
-    const common = (await run("git", ["-C", ws, "rev-parse", "--path-format=absolute", "--git-common-dir"], { check: false })).stdout.trim();
-    if (!common) return;
-    await run("git", ["--git-dir", common, "worktree", "remove", "--force", ws], { check: false });
-    rmSync(ws, { recursive: true, force: true });
-    await run("git", ["--git-dir", common, "worktree", "prune"], { check: false });
-  }
-
-  return {
-    async create({ id, source }) {
-      mkdirSync(dir(id), { recursive: true });
-      // ponytail: branches from the source's HEAD commit, so uncommitted changes stay behind; stash-and-apply if users expect them
-      if (source) await run("git", ["-C", source, "worktree", "add", "-q", "-b", `bottleship/${id}`, join(dir(id), "workspace"), "HEAD"]);
-      return { id };
-    },
-
-    // a destroyed box has no cwd, so spawn rejects with ENOENT like an unreachable box would
-    exec: (id, script, { stdin } = {}) => run("bash", ["-c", script], { ...box(id), stdin, check: false }),
-
-    openStream: (id, script) => spawnStream("bash", ["-c", script], box(id)),
-
-    status: async (id) => (existsSync(dir(id)) ? "running" : "gone"),
-
-    async destroy(id) {
-      await run("bash", ["-c", killBoxScript(shq(dir(id)), shq(groups(id)))]);
-      rmSync(groups(id), { force: true });
-      await removeWorktree(join(dir(id), "workspace"));
-      rmSync(dir(id), { recursive: true, force: true });
-    },
-  };
-};
-export default local;

package/presets/providers/modal.ts

@@ -1,121 +0,0 @@
-// Modal Sandboxes (modal.com) as a provider, through the `modal` JS SDK. A box is a sandbox that sleeps until its timeout.
-//
-// options: { tokenId?, tokenSecret? (secret sources; without them the SDK reads ~/.modal.toml or MODAL_TOKEN_*),
-//            app? (default "bottleship"), image? (registry tag, default node:22-bookworm), timeoutMinutes? (default 120, max 1440) }
-//
-// template() builds the Dockerfile as Modal image layers and publishes it as a named image in the workspace.
-// Modal ignores USER, so template boxes run as root (like the default image) with the box user's ENV and files; one FROM only, no COPY from a local context.
-import { Readable, Writable } from "node:stream";
-import type { ReadableStream as WebReadable, WritableStream as WebWritable } from "node:stream/web";
-import type { ModalClient, Sandbox } from "modal";
-import type { BoxStream, ExecResult, ProviderFactory } from "../../src/types.ts";
-
-// errors that mean the sandbox id names nothing that runs
-const isGone = (e: unknown) => {
-  const err = e as { name?: string; code?: number };
-  // nice-grpc NOT_FOUND (5) and INVALID_ARGUMENT (3) for unknown or malformed ids
-  return err?.name === "NotFoundError" || err?.code === 5 || err?.code === 3;
-};
-
-// the FROM image and the instructions after it; Modal builds the rest as one layer on that image
-function splitDockerfile(dockerfile: string): { from: string; commands: string[] } {
-  const lines = dockerfile.split("\n");
-  const froms = lines.flatMap((l, i) => (/^\s*FROM\s/i.test(l) ? [i] : []));
-  if (froms.length !== 1) throw new Error(`modal templates take a Dockerfile with exactly one FROM, this one has ${froms.length}`);
-  const before = lines.slice(0, froms[0]).filter((l) => l.trim() && !l.trim().startsWith("#"));
-  if (before.length) throw new Error(`modal templates take nothing but comments before FROM, got: ${before[0]}`);
-  const m = /^\s*FROM\s+(\S+)(\s+AS\s+\S+)?\s*$/i.exec(lines[froms[0]]!);
-  if (!m || m[1]!.startsWith("--")) throw new Error(`modal templates take a plain FROM <image>, got: ${lines[froms[0]]}`);
-  return { from: m[1]!, commands: lines.slice(froms[0] + 1) };
-}
-
-const modal: ProviderFactory = ({ options, secret }) => {
-  const appName: string = options.app ?? "bottleship";
-  // debian based, runs as root with HOME=/root, has bash, git, curl, xz and node already
-  const imageTag: string = options.image ?? "node:22-bookworm";
-  // ponytail: a box dies at its timeout (Modal caps it at 24h) even if the agent still runs; snapshot and restore to go longer
-  const timeoutMs = Math.min(Number(options.timeoutMinutes ?? 120), 24 * 60) * 60_000;
-
-  let client: Promise<ModalClient> | undefined;
-  const getClient = () =>
-    (client ??= import("modal").then(({ ModalClient }) => new ModalClient({
-      tokenId: options.tokenId ? secret(options.tokenId) : undefined,
-      tokenSecret: options.tokenSecret ? secret(options.tokenSecret) : undefined,
-    })));
-  const sandbox = async (id: string): Promise<Sandbox> => (await getClient()).sandboxes.fromId(id);
-  const spawn = async (id: string, script: string) => (await sandbox(id)).exec(["bash", "-c", script], { mode: "binary" });
-
-  return {
-    // a named image is scoped to the Modal workspace, so the name cannot resolve to someone else's image
-    // ponytail: two inits racing on one name both build and publish; harmless, since Modal caches layers by content and both are the same image
-    async template({ name, dockerfile }) {
-      const mc = await getClient();
-      try {
-        await mc.images.fromName(name);
-        return name;
-      } catch (e) {
-        if ((e as Error)?.name !== "NotFoundError") throw e;
-      }
-      const { from, commands } = splitDockerfile(dockerfile);
-      const app = await mc.apps.fromName(appName, { createIfMissing: true });
-      const image = await mc.images.fromRegistry(from).dockerfileCommands(commands).build(app);
-      await image.publish(name);
-      return name;
-    },
-
-    async create({ template }) {
-      const mc = await getClient();
-      const app = await mc.apps.fromName(appName, { createIfMissing: true });
-      const image = template ? await mc.images.fromName(template) : mc.images.fromRegistry(imageTag);
-      // no idleTimeoutMs: the detached agent runs no exec, so Modal would count it as idle
-      const sb = await mc.sandboxes.create(app, image, { timeoutMs, tags: { bottleship: "1" } });
-      // the first exec waits until the sandbox is scheduled and its command router answers
-      await (await sb.exec(["true"])).wait();
-      return { id: sb.sandboxId };
-    },
-
-    async exec(id, script, { stdin } = {}): Promise<ExecResult> {
-      const p = await spawn(id, script);
-      const w = p.stdin.getWriter();
-      if (stdin !== undefined && stdin.length) await w.write(typeof stdin === "string" ? Buffer.from(stdin) : stdin);
-      await w.close();
-      const [out, err, code] = await Promise.all([p.stdout.readBytes(), p.stderr.readBytes(), p.wait()]);
-      return { code, stdout: Buffer.from(out).toString(), stderr: Buffer.from(err).toString() };
-    },
-
-    async openStream(id, script): Promise<BoxStream> {
-      const p = await spawn(id, script);
-      const stdin = Writable.fromWeb(p.stdin as unknown as WebWritable);
-      const stdout = Readable.fromWeb(p.stdout as unknown as WebReadable);
-      const stderr = Readable.fromWeb(p.stderr as unknown as WebReadable);
-      stdin.on("error", () => {});
-      const done = p.wait().catch(() => null);
-      return {
-        stdin,
-        stdout,
-        stderr,
-        // ponytail: the SDK cannot kill an exec, so close only drops our end; the remote process runs on until it reads EOF or exits
-        close: () => [stdin, stdout, stderr].forEach((s) => s.destroy()),
-        onClose: (cb) => void done.then(cb),
-      };
-    },
-
-    async status(id) {
-      try {
-        return (await (await sandbox(id)).poll()) === null ? "running" : "gone";
-      } catch (e) {
-        if (isGone(e)) return "gone";
-        throw e;
-      }
-    },
-
-    async destroy(id) {
-      try {
-        await (await sandbox(id)).terminate();
-      } catch (e) {
-        if (!isGone(e)) throw e;
-      }
-    },
-  };
-};
-export default modal;

package/presets/providers/ssh.ts

@@ -1,54 +0,0 @@
-// Boxes on any machine you can ssh into: each box is a directory <root>/<id> on that host, used as $HOME.
-// Needs `ssh <host>` working non-interactively (keys, no password prompt). Boxes share the host, its user and network.
-//
-// options: { host (anything ssh accepts, e.g. a ~/.ssh/config alias), root? (default ~/bottleship-boxes) }
-import { basename } from "node:path";
-import { killBoxScript, run, shq, spawnStream } from "./util.ts";
-import type { ProviderFactory } from "../../src/types.ts";
-
-const SSH = ["-o", "BatchMode=yes", "-o", "ServerAliveInterval=15"];
-
-const ssh: ProviderFactory = ({ options }) => {
-  const host: string = options.host;
-  if (!host) throw new Error('ssh provider: missing "host" option');
-  const root: string = options.root ?? "~/bottleship-boxes";
-  // the remote shell expands a leading ~ through $HOME; the rest stays quoted
-  const rootSh = root === "~" ? '"$HOME"' : root.startsWith("~/") ? `"$HOME"/${shq(root.slice(2))}` : shq(root);
-  const dir = (id: string) => {
-    if (!id || basename(id) !== id || id.startsWith(".")) throw new Error(`ssh provider: bad box id ${JSON.stringify(id)}`);
-    return `${rootSh}/${shq(id)}`;
-  };
-  const groups = (id: string) => `${rootSh}/${shq(`.${id}.pgids`)}`;
-  const args = (script: string) => [...SSH, "-T", host, `bash -c ${shq(script)}`];
-  const sh = (script: string, stdin?: string | Buffer) => run("ssh", args(script), { stdin, check: false });
-  // ssh itself exits 255 when it cannot reach the host
-  const reached = <T extends { code: number | null; stderr: string }>(r: T) => {
-    if (r.code === 255) throw new Error(`ssh ${host} failed: ${r.stderr.trim().slice(-500)}`);
-    return r;
-  };
-  // sshd starts each session in its own process group; the group and the BOTTLESHIP_BOX mark let destroy find what the box left running
-  const inBox = (id: string, script: string) =>
-    `cd ${dir(id)} 2>/dev/null || { echo ${shq(`no box ${id} on ${host}`)} >&2; exit 1; }
-ps -o pgid= -p $$ | tr -d ' ' >> ${groups(id)}
-export BOTTLESHIP_BOX=${dir(id)}
-export HOME="$PWD"
-exec bash -c ${shq(script)}`;
-
-  return {
-    async create({ id }) {
-      const r = reached(await sh(`mkdir -p ${dir(id)}`));
-      if (r.code !== 0) throw new Error(`ssh ${host}: could not create box ${id}: ${r.stderr.trim()}`);
-      return { id };
-    },
-
-    exec: async (id, script, { stdin } = {}) => sh(inBox(id, script), stdin),
-
-    openStream: (id, script) => spawnStream("ssh", args(inBox(id, script))),
-
-    status: async (id) => (reached(await sh(`test -d ${dir(id)} && echo running || echo gone`)).stdout.trim() === "running" ? "running" : "gone"),
-
-    destroy: async (id) => reached(await sh(`(${killBoxScript(dir(id), groups(id))})
-rm -rf ${dir(id)} ${groups(id)}`)),
-  };
-};
-export default ssh;

package/presets/providers/util.ts

@@ -1,112 +0,0 @@
-// Helpers for provider modules, handed to them as ctx.kit.
-import { spawn } from "node:child_process";
-import { PassThrough, Writable } from "node:stream";
-import type { BoxStream, ExecResult, RunOptions } from "../../src/types.ts";
-
-export interface SpawnOptions {
-  env?: Record<string, string>;
-  cwd?: string;
-  // own process group, so killBoxScript can tell its processes apart
-  detached?: boolean;
-  onSpawn?: (pid: number) => void;
-}
-
-function spawnPiped(cmd: string, args: string[], { env, cwd, detached, onSpawn }: SpawnOptions = {}) {
-  const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], cwd, detached, env: env ? { ...process.env, ...env } : process.env });
-  if (child.pid) onSpawn?.(child.pid);
-  return child;
-}
-
-// resolves { code, stdout, stderr }; with check (default true) a non-zero exit rejects
-export function run(cmd: string, args: string[], opts: RunOptions & SpawnOptions = {}): Promise<ExecResult> {
-  const { stdin, check = true } = opts;
-  return new Promise((resolve, reject) => {
-    const child = spawnPiped(cmd, args, opts);
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => (stdout += d));
-    child.stderr.on("data", (d) => (stderr += d));
-    child.on("error", reject);
-    child.on("close", (code) => {
-      if (check && code !== 0) reject(new Error(`${cmd} ${args.slice(0, 3).join(" ")}... exited ${code}: ${stderr.trim().slice(-500)}`));
-      else resolve({ code, stdout, stderr });
-    });
-    child.stdin.on("error", () => {});
-    child.stdin.end(stdin ?? "");
-  });
-}
-
-// kills each process that is verifiably the box's, never a whole recorded group (its id may be reused): marked BOTTLESHIP_BOX=<dir> (Linux /proc, macOS ps -E), or on macOS, where ps hides the env of Apple's binaries, in a recorded group with its cwd in the box
-export const killBoxScript = (d: string, groups: string) => `d=${d}
-g=${groups}
-[ -d "$d" ] || exit 0
-p=$(cd "$d" && pwd -P)
-cd /
-mine() {
-  if [ -d /proc/self ]; then
-    for e in /proc/[0-9]*; do
-      if tr '\\0' '\\n' < "$e/environ" 2>/dev/null | grep -qxF "BOTTLESHIP_BOX=$d"; then echo "\${e#/proc/}"; fi
-    done
-  else
-    ps -A -E -ww -o pid=,command= 2>/dev/null | awk -v d="$d" 'index($0 " ", " BOTTLESHIP_" "BOX=" d " ") { print $1 }'
-    [ -f "$g" ] || return 0
-    ingroup=$(ps -A -o pid=,pgid= | awk 'NR == FNR { g[$1] = 1; next } ($2 in g) { printf "%s,", $1 }' "$g" -)
-    [ -n "$ingroup" ] && lsof -nP -a -d cwd -p "\${ingroup%,}" -Fpn 2>/dev/null | awk -v p="$p/" '/^p/ { pid = substr($0, 2) } /^n/ && index(substr($0, 2) "/", p) == 1 { print pid }'
-  fi
-}
-for i in 1 2 3 4 5; do
-  pids=$(mine | grep -vxF -e $$ -e $PPID | sort -u)
-  [ -z "$pids" ] && break
-  kill -9 $pids 2>/dev/null
-  sleep 0.2
-done
-true`;
-
-// single-quote for sh
-export const shq = (s: unknown): string => `'${String(s).replace(/'/g, `'\\''`)}'`;
-
-// fills {name} with the shell-quoted value, {name!} with the raw value, missing values with ""
-export function fill(template: string, values: Record<string, unknown>): string {
-  return template.replace(/\{(\w+)(!?)\}/g, (_, k: string, raw: string) => {
-    const v = values[k];
-    if (v === undefined || v === null) return "";
-    return raw ? String(v) : shq(v);
-  });
-}
-
-// a long-lived child process as a BoxStream, for openStream over a CLI
-export function spawnStream(cmd: string, args: string[], opts?: SpawnOptions): BoxStream {
-  const child = spawnPiped(cmd, args, opts);
-  child.stdin.on("error", () => {});
-  return { stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, close: () => child.kill(), onClose: (cb) => child.on("close", (code) => cb(code)) };
-}
-
-// a binary-clean BoxStream over a WebSocket (Node's global undici WebSocket, which accepts { headers })
-export function wsStream(url: string, headers: Record<string, string> = {}): BoxStream {
-  const stdout = new PassThrough();
-  const stderr = new PassThrough();
-  const ws = new WebSocket(url, { headers } as unknown as string[]);
-  ws.binaryType = "arraybuffer";
-  const queue: Buffer[] = [];
-  const closers: (() => void)[] = [];
-  ws.addEventListener("open", () => queue.splice(0).forEach((b) => ws.send(b)));
-  ws.addEventListener("message", (e) => stdout.write(Buffer.from(e.data as ArrayBuffer)));
-  ws.addEventListener("close", () => {
-    stdout.end();
-    stderr.end();
-    closers.forEach((cb) => cb());
-  });
-  ws.addEventListener("error", () => {});
-  const stdin = new Writable({
-    write(chunk: Buffer, _enc, cb) {
-      if (ws.readyState === WebSocket.OPEN) ws.send(chunk);
-      else queue.push(chunk);
-      cb();
-    },
-    final(cb) {
-      ws.close();
-      cb();
-    },
-  });
-  return { stdin, stdout, stderr, close: () => ws.close(), onClose: (cb) => closers.push(cb) };
-}