@stixxert/pi-docker-sandbox 1.0.1 → 1.1.1

package/template/README.md

@@ -0,0 +1,92 @@
+# Lightweight sandbox template
+
+A minimal base image for sandboxes, built automatically. **Measured**, not
+estimated — `docker build` + `du` on this machine:
+
+| Profile | On disk | docker reports | What's in it |
+|---|---|---|---|
+| `core` | **383 MB** | 547 MB | git, curl, ripgrep, jq, node 22, pnpm, vim-tiny |
+| `core + build` *(default)* | **648 MB** | 920 MB | the above **+** `build-essential`, `python3` (native node modules) |
+| *the existing pi template* | ~2.2 GB `/usr` | — | that, **plus** pi, a global `opencode-ai`, JVM, Go, Python, Rust |
+
+So the default profile is **~3× smaller**, and the two ingredients that account
+for most of the difference are simply *not installing pi* (136 MB) and *not
+shipping a second coding agent* (353 MB, `opencode-ai`), a JVM (332 MB), Go
+(72 MB), Python (49 MB) and Rust (11 MB).
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `install.sh` | the recipe. Contains **no `sbx` commands**, so the exact same script runs in a docker build (for measuring/CI) and inside a sandbox (for the real template) |
+| `Dockerfile` | `install.sh` in docker-buildable form: `docker build -f template/Dockerfile -t sbx-lite .` |
+| `build.sh` | builds the sbx template from `install.sh`, hashes the recipe into the tag, saves, **verifies**, and records the ref |
+
+## The user does nothing
+
+That is a hard requirement, and it drives the design:
+
+1. **The tag is a hash of the recipe.** Editing `install.sh` produces a *new*
+   template tag. A stale snapshot can never be silently reused, and no version
+   bookkeeping is needed.
+2. **`build.sh` is idempotent and cheap when current** — one `sbx template ls`
+   decides whether there is any work, so it is safe to call on every launch
+   (`bash template/build.sh`, or a launcher doing it for you). No-op: ~1 s.
+3. **The builder records the ref** in
+   `${XDG_CACHE_HOME:-~/.cache}/pi-sbx-lite/template-ref`.
+4. **The extension adopts it automatically** — it reads that file at session
+   start, *verifies the template still exists*, and uses it. No configuration.
+5. **Nothing about this can fail a session.** Missing file, unreadable file,
+   template deleted since it was recorded, sbx not answering, the build itself
+   failing — every one of those degrades to the stock base image. The sandbox
+   still works; it is simply bigger. The user is never blocked and never sees an
+   error they have to act on.
+6. **An explicit `DOCKER_SANDBOX_TEMPLATE` always wins**, so this is an opinion,
+   not a policy.
+
+```
+first launch   → stock base (works, bigger)          [no template recorded yet]
+build.sh runs  → builds + verifies, records the ref   [once, ~2 min]
+later launches → lightweight template, automatically
+```
+
+## Build it
+
+```bash
+npm run template            # build if missing/stale, else no-op
+npm run template:check      # report status, change nothing
+bash template/build.sh --force
+```
+
+Tunables: `SBX_LITE_BASE` (base image), `SBX_LITE_TAG` (override the tag),
+`NODE_VERSION`, `SBX_LITE_BUILD=off` (drop `build-essential`+`python3`, −265 MB),
+`SBX_LITE_PNPM=off`.
+
+## Verifying without `sbx`
+
+`build.sh` needs a host that can run `sbx`. The recipe does not: it is plain
+apt + curl + npm, so it can be built and **measured** anywhere docker runs.
+
+```bash
+docker build -f template/Dockerfile -t sbx-lite .
+docker run --rm sbx-lite sh -c 'node -v; pnpm -v; git --version; rg --version'
+docker run --rm sbx-lite du -sh /
+```
+
+## What is deliberately not here
+
+- **pi.** With the sandbox execution backend, pi runs on the host and routes its
+  tools in. Baking it into the template was 136 MB *and* a maintenance
+  treadmill: every pi release invalidated the template for every project.
+- **A browser.** Playwright's Chromium headless shell is ~270 MB. It is genuinely
+  needed for UI work and genuinely wasted for everything else, so it belongs in a
+  separate `webdev` variant, not in every sandbox.
+- **Language toolchains nobody asked for.** The default profile is what an
+  ordinary project needs; `build-essential` + `python3` are the one concession,
+  because a failing `pnpm install` of a native module would break the
+  "user does nothing" guarantee. Turn them off if your projects don't need them.
+
+## See also
+
+`sandbox/README.md` for the execution backend, and the repo README for how this
+fits the two modes.

package/template/build.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+#
+# build.sh — build the LIGHTWEIGHT sandbox template, automatically.
+#
+#   bash template/build.sh            # build if missing/stale, else no-op (fast)
+#   bash template/build.sh --check    # report status, change nothing
+#   bash template/build.sh --ref      # print the template ref, or nothing
+#   bash template/build.sh --force    # rebuild even if the current one exists
+#
+# Design goal: **the user never runs anything and never sees a failure.**
+#
+#   * Idempotent and cheap when current: a single `sbx template ls` decides
+#     whether to do anything, so it is safe to call on every launch.
+#   * The tag embeds a hash of the recipe, so editing install.sh produces a NEW
+#     template instead of silently reusing a stale snapshot.
+#   * Self-verifying, like the pi template builder it replaces: after saving, it
+#     boots a throwaway sandbox FROM THE SAVED TEMPLATE and asserts the tools are
+#     really there. A template that silently lacks node/pnpm/git can't be
+#     produced.
+#   * Records the resolved ref where the extension looks for it, so the sandbox
+#     starts using it with no configuration. If that file is missing or the
+#     template is gone, the extension simply creates sandboxes from the stock
+#     base — degraded, never broken.
+#
+# What it does NOT contain: pi (pi runs on the HOST now and routes its tools in),
+# editors for pi, or language toolchains nobody asked for. See install.sh.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+BASE="${SBX_LITE_BASE:-docker.io/docker/sandbox-templates:shell}"
+
+# Portability: macOS has shasum, Linux has sha256sum.
+if command -v sha256sum >/dev/null 2>&1; then
+	HASHER="sha256sum"
+else
+	HASHER="shasum -a 256"
+fi
+
+# NOTE the braces: `cat f; echo x | hash` would pipe ONLY the echo and let the
+# cat output leak into the captured value (giving a tag containing the entire
+# recipe). The whole group must be the pipeline's input.
+RECIPE_HASH="$( { cat "$HERE/install.sh"; printf 'base=%s\n' "$BASE"; } | $HASHER | cut -c1-8 )"
+
+# A malformed tag would produce a template nobody can ever match, so fail loudly
+# here rather than writing a nonsense ref that the extension then ignores.
+case "$RECIPE_HASH" in
+[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]) ;;
+*)
+	echo "build: could not compute a recipe hash (got '${RECIPE_HASH:0:40}…')" >&2
+	exit 1
+	;;
+esac
+
+TAG="${SBX_LITE_TAG:-pi-sbx-lite:${RECIPE_HASH}}"
+REF="docker.io/library/${TAG}"
+STATE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/pi-sbx-lite"
+STATE_FILE="$STATE_DIR/template-ref"
+
+TPL_SANDBOX="pi-sbx-lite-build-$$"
+VERIFY_SANDBOX="pi-sbx-lite-verify-$$"
+# Build in a scratch dir, never the caller's cwd: mounting the caller's project
+# into the snapshot would bake project files into the shared image.
+SCRATCH="$(mktemp -d "${TMPDIR:-/tmp}/pi-sbx-lite.XXXXXX")"
+
+MODE="ensure"
+case "${1:-}" in
+--check) MODE="check" ;;
+--ref) MODE="ref" ;;
+--force) MODE="force" ;;
+"") ;;
+*)
+	echo "usage: $0 [--check|--ref|--force]" >&2
+	exit 2
+	;;
+esac
+
+cleanup() {
+	rm -rf "$SCRATCH"
+	sbx rm --force "$TPL_SANDBOX" >/dev/null 2>&1 || true
+	sbx rm --force "$VERIFY_SANDBOX" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+# `sbx template ls` differs between sbx versions (table vs flat), so match on the
+# repository basename + version rather than on a column position — the same
+# approach the existing pi-template detector needed.
+template_present() {
+	sbx template ls 2>/dev/null | awk -v tag="${TAG}" '
+		{
+			sub(/^[[:space:]]+/, "")
+			if ($0 == "" || $0 ~ /^REPOSITORY/) next
+			r = $1; sub(/^.*\//, "", r)
+			if (r == tag && $2 != "") found = 1      # table row: <repo> <version>
+			if ($1 == "docker.io/library/" tag) found = 1
+			if (r == tag) found = 1
+		}
+		END { exit(found ? 0 : 1) }'
+}
+
+record_ref() {
+	mkdir -p "$STATE_DIR"
+	printf '%s\n' "$REF" >"$STATE_FILE"
+}
+
+case "$MODE" in
+ref)
+	[ -f "$STATE_FILE" ] && cat "$STATE_FILE"
+	exit 0
+	;;
+check)
+	if template_present; then
+		echo "current: $REF"
+		exit 0
+	fi
+	echo "missing: $REF (would build from $BASE)"
+	exit 1
+	;;
+ensure)
+	if template_present; then
+		record_ref
+		echo "template up to date: $REF"
+		exit 0
+	fi
+	;;
+force) : ;;
+esac
+
+echo "building lightweight sandbox template"
+echo "  base:   $BASE"
+echo "  tag:    $TAG  (recipe hash ${RECIPE_HASH})"
+echo "  recipe: $HERE/install.sh"
+echo
+
+# Leftovers from an interrupted build would make `sbx create` fail.
+sbx rm --force "$TPL_SANDBOX" >/dev/null 2>&1 || true
+sbx template rm "$TAG" >/dev/null 2>&1 || true
+
+echo "creating throwaway sandbox…"
+sbx create -q --name "$TPL_SANDBOX" -t "$BASE" shell "$SCRATCH"
+
+# The recipe is passed as a single argv element; no output-masking pipe, so a
+# failure inside the install surfaces as a non-zero exit and `set -e` aborts.
+echo "installing baseline (this is the part that takes a couple of minutes)…"
+sbx exec "$TPL_SANDBOX" -- bash -lc "$(cat "$HERE/install.sh")"
+
+echo "saving template…"
+sbx template save "$TPL_SANDBOX" "$TAG" # no `|| true` — a failed save must abort
+sbx rm --force "$TPL_SANDBOX" >/dev/null 2>&1 || true
+
+# The definitive check: boot FROM THE SAVED TEMPLATE and assert the toolchain.
+# Asserting in the build sandbox would prove nothing about the saved image.
+echo "verifying the saved template boots with a working toolchain…"
+sbx create -q --name "$VERIFY_SANDBOX" -t "$REF" shell "$SCRATCH"
+sbx exec "$VERIFY_SANDBOX" -- bash -lc '
+	set -e
+	for c in node pnpm git rg; do
+		command -v "$c" >/dev/null || { echo "verify: missing $c" >&2; exit 1; }
+	done
+	node -e "require(\"child_process\")" 2>/dev/null || { echo "verify: node is broken" >&2; exit 1; }
+	printf "verify: node %s, pnpm %s, git %s, rg %s\n" \
+		"$(node -v)" "$(pnpm -v)" "$(git --version | awk "{print \$3}")" "$(rg --version | head -1 | awk "{print \$2}")"'
+sbx rm --force "$VERIFY_SANDBOX" >/dev/null 2>&1 || true
+
+record_ref
+echo
+echo "done. recorded $REF in $STATE_FILE"
+echo "the sandbox extension picks this up automatically; override with DOCKER_SANDBOX_TEMPLATE."

package/template/install.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# install.sh — the lightweight sandbox baseline.
+#
+# Runs INSIDE the sandbox (or inside a docker build). Deliberately contains no
+# `sbx` commands so the exact same recipe can be validated with plain docker
+# (`docker build -f template/Dockerfile …`) on machines where sbx cannot run.
+#
+# What it is: a general Linux + git + node/pnpm + search box. That is all a
+# sandbox needs once pi runs on the HOST and merely routes its tools here —
+# pi itself, an editor stack for pi, and every language toolchain somebody
+# might want are all gone.
+#
+# Tunables (env):
+#   NODE_VERSION=22.22.1     node LTS to install
+#   SBX_LITE_BUILD=off       drop build-essential + python3 (~250 MB, needed
+#                            for native node modules / node-gyp)
+#   SBX_LITE_PNPM=off        drop the pnpm global install
+
+set -euo pipefail
+
+NODE_VERSION="${NODE_VERSION:-22.22.1}"
+export DEBIAN_FRONTEND=noninteractive
+
+SUDO=""
+if [ "$(id -u)" != "0" ]; then SUDO="sudo"; fi
+
+# ── base packages ─────────────────────────────────────────────────────────
+# git/curl/ca-certificates: cloning and fetching over TLS.
+# ripgrep: the agent's search tool, and much faster than grep -r.
+# build-essential + python3: native node modules (node-gyp) — without these a
+#   `pnpm install` in an ordinary project can fail, which would break the
+#   "the user does nothing" guarantee. Opt out with SBX_LITE_BUILD=off.
+CORE="ca-certificates curl git gnupg ripgrep jq unzip xz-utils procps less vim-tiny"
+EXTRA=""
+if [ "${SBX_LITE_BUILD:-on}" != "off" ]; then EXTRA="build-essential python3"; fi
+
+echo "install: apt packages (core${EXTRA:+ + $EXTRA})"
+# shellcheck disable=SC2086
+$SUDO apt-get update -qq
+# shellcheck disable=SC2086
+$SUDO apt-get install -y -qq --no-install-recommends $CORE $EXTRA
+
+# ── apt hygiene ───────────────────────────────────────────────────────────
+# ~55 MB in a typical Ubuntu image, and pure waste in a snapshot: the lists are
+# stale the moment the image is saved and every sandbox re-downloads them.
+$SUDO rm -rf /var/lib/apt/lists/* /usr/share/doc/* /usr/share/man/* /var/cache/apt/*
+
+# ── node + pnpm ───────────────────────────────────────────────────────────
+# The official tarball into /usr/local rather than a distro/node image layer:
+# no apt repository to configure, no extra base layers to carry.
+case "$(uname -m)" in
+	aarch64 | arm64) NODE_ARCH="arm64" ;;
+	x86_64 | amd64) NODE_ARCH="x64" ;;
+	*)
+		echo "install: unsupported architecture $(uname -m)" >&2
+		exit 1
+		;;
+esac
+
+echo "install: node v${NODE_VERSION} (${NODE_ARCH})"
+curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz" -o /tmp/node.tar.xz
+$SUDO tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1
+rm -f /tmp/node.tar.xz
+
+# The tarball also ships node's C++ headers (~65 MB). node-gyp fetches its own
+# headers into a cache, so these are dead weight in a snapshot.
+$SUDO rm -rf /usr/local/include/node
+
+if [ "${SBX_LITE_PNPM:-on}" != "off" ]; then
+	echo "install: pnpm"
+	$SUDO npm install -g --no-audit --no-fund --loglevel=error pnpm
+fi
+# The npm cache is ~30-60 MB of tarballs that a snapshot never needs again.
+$SUDO npm cache clean --force >/dev/null 2>&1 || true
+
+echo "install: done — node $(node -v), pnpm $(pnpm -v 2>/dev/null || echo absent)"

package/test-loader.mjs

@@ -0,0 +1,53 @@
+/**
+ * Load a TypeScript module from a plain Node script.
+ *
+ * Node >= 23.6 strips types natively and can import `.ts` directly. Older
+ * Node (22.x) cannot (`ERR_NO_TYPESCRIPT`) or does not know the extension at
+ * all (`ERR_UNKNOWN_FILE_EXTENSION`), so fall back to `jiti` — the same
+ * loader pi itself uses for extensions. jiti is resolved from pi's own
+ * dependency tree so no extra dependency is needed.
+ *
+ * Shared by smoke-test.mjs and sandbox/e2e.mjs.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const repoRoot = path.dirname(fileURLToPath(import.meta.url));
+
+let jiti;
+
+function makeJiti() {
+	if (jiti) return jiti;
+	for (const candidate of [
+		path.join(repoRoot, "node_modules/@earendil-works/pi-coding-agent/node_modules/jiti"),
+		"jiti",
+	]) {
+		try {
+			const mod = require(candidate);
+			const createJiti = mod.createJiti ?? mod.default?.createJiti;
+			if (createJiti) {
+				jiti = createJiti(repoRoot + path.sep);
+				return jiti;
+			}
+		} catch {
+			/* try the next candidate */
+		}
+	}
+	throw new Error("could not load jiti (needed to import .ts on Node < 23.6)");
+}
+
+/** Import a `.ts` (or `.mjs`) module, by repo-relative or absolute path. */
+export async function loadTs(relativeOrAbsolute) {
+	const absolute = path.isAbsolute(relativeOrAbsolute)
+		? relativeOrAbsolute
+		: path.join(repoRoot, relativeOrAbsolute);
+	try {
+		return await import(absolute);
+	} catch (err) {
+		if (err?.code !== "ERR_UNKNOWN_FILE_EXTENSION" && err?.code !== "ERR_NO_TYPESCRIPT") throw err;
+		return makeJiti()(absolute);
+	}
+}