@huynle/hub 0.6.0 → 0.7.1

package/packages/protocol/src/preset.ts

@@ -0,0 +1,144 @@
+// Harness presets (design §1.2, preset tier): data-only descriptions of a harness the hub drives through a terminal
+// pane (Herdr/tmux) when it has no spoke of its own. A preset is data, never code: an argv list (no shell syntax,
+// nothing is run through a shell), an optional resume flag, where the harness's native session ID comes from, and
+// fixed delivery "paste" (messages are pasted into the pane, so a deliver is at most "queued") and evidence "screen"
+// (activity is sampled from the screen, which never counts as idle). Unknown fields are refused, so a typo or a field
+// from a newer schema is an error rather than silently ignored. The built-in harness names are reserved.
+//
+// Imports only from wire.ts: index.ts re-exports this module.
+
+import { isObj, nonEmpty, token, UNSAFE_CHARS } from "./wire.ts"
+
+/** Harnesses with their own spokes; a preset may not take their names. */
+export const RESERVED_HARNESS_NAMES = ["opencode", "claude-code", "codex"] as const
+
+/**
+ * Where a preset's native session ID comes from: nowhere (it cannot resume), a flag the hub passes a fresh ID with
+ * when it starts the harness (e.g. `--session-id <id>`), or the first capture group of a pattern on the screen.
+ */
+export type PresetNativeID =
+  | { readonly source: "none" }
+  | { readonly source: "argv"; readonly flag: string }
+  | { readonly source: "screen"; readonly pattern: string }
+
+export interface HarnessPreset {
+  /** The harness id (a lowercase token, as a hello's `harness`), not one of RESERVED_HARNESS_NAMES. */
+  readonly name: string
+  readonly description?: string
+  /** The argv that starts the harness: the program, then its arguments. Never run through a shell. */
+  readonly command: readonly string[]
+  /** The flag that resumes a session: the hub appends it and the native ID (`[...command, resumeFlag, id]`). */
+  readonly resumeFlag?: string
+  readonly nativeID: PresetNativeID
+  readonly delivery: "paste"
+  readonly evidence: "screen"
+}
+
+export const PRESET_FIELDS = ["name", "description", "command", "resumeFlag", "nativeID", "delivery", "evidence"] as const
+
+export const PRESET_DESCRIPTION_MAX = 300
+export const PRESET_ARGS_MAX = 64
+export const PRESET_ARG_MAX = 1000
+export const PRESET_PATTERN_MAX = 500
+export const PRESET_FLAG_MAX = 100
+
+/** Characters that mean shell syntax (substitution, chaining, redirection, quoting, escapes). */
+const SHELL_SYNTAX = /[`$;|&<>\\'"]/
+const FLAG = new RegExp(`^--?[A-Za-z0-9][A-Za-z0-9-]{0,${PRESET_FLAG_MAX - 3}}$`)
+const isFlag = (v: unknown): v is string => typeof v === "string" && FLAG.test(v)
+
+/** Why an argv element is not acceptable, or undefined. */
+function argProblem(v: unknown, i: number): string | undefined {
+  const label = `command[${i}]`
+  if (!nonEmpty(v) || v.length > PRESET_ARG_MAX) return `${label} must be 1–${PRESET_ARG_MAX} characters`
+  if (UNSAFE_CHARS.test(v)) return `${label} must not contain control characters or line breaks`
+  if (SHELL_SYNTAX.test(v)) return `${label} must not contain shell syntax (\` $ ; | & < > \\ ' "): command is an argv list, never run through a shell`
+  if (v.startsWith("~")) return `${label} must not start with ~ (no shell expansion)`
+  if (i === 0 && /\s/.test(v)) return "command[0] is the program alone: put its arguments in the next items"
+  if (i === 0 && v.startsWith("-")) return "command[0] must be the program, not a flag"
+  return undefined
+}
+
+/** The number of capture groups in `pattern`, or undefined when it does not compile. */
+function captureGroups(pattern: string): number | undefined {
+  try {
+    return new RegExp(`${pattern}|`).exec("")!.length - 1
+  } catch {
+    return undefined
+  }
+}
+
+function nativeIDProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "nativeID must be {source: none | argv | screen, …}"
+  const allowed: Record<string, readonly string[]> = { none: ["source"], argv: ["source", "flag"], screen: ["source", "pattern"] }
+  const keys = typeof v.source === "string" ? allowed[v.source] : undefined
+  if (!keys) return "nativeID.source must be none, argv or screen"
+  const unknown = Object.keys(v).find((k) => !keys.includes(k))
+  if (unknown) return `nativeID.${unknown} is not a field of a ${v.source} nativeID`
+  if (v.source === "argv" && !isFlag(v.flag)) return "nativeID.flag must be one flag, e.g. --session-id"
+  if (v.source === "screen") {
+    if (!nonEmpty(v.pattern) || v.pattern.length > PRESET_PATTERN_MAX) return `nativeID.pattern must be 1–${PRESET_PATTERN_MAX} characters`
+    const groups = captureGroups(v.pattern)
+    if (groups === undefined) return "nativeID.pattern must be a valid regular expression"
+    if (groups < 1) return "nativeID.pattern must capture the ID in a group"
+  }
+  return undefined
+}
+
+/** Why `v` is not an acceptable harness preset, or undefined when it is. */
+export function presetProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "a preset must be an object"
+  const unknown = Object.keys(v).find((k) => !(PRESET_FIELDS as readonly string[]).includes(k))
+  if (unknown) return `${unknown} is not a preset field (fields: ${PRESET_FIELDS.join(", ")})`
+  if (!token(v.name, 64)) return "name must be a lowercase token of 1–64 letters, digits and . _ -"
+  if ((RESERVED_HARNESS_NAMES as readonly string[]).includes(v.name)) return `name ${v.name} is reserved for a built-in harness`
+  if (v.description !== undefined && (typeof v.description !== "string" || v.description.length > PRESET_DESCRIPTION_MAX || UNSAFE_CHARS.test(v.description))) {
+    return `description must be at most ${PRESET_DESCRIPTION_MAX} printable characters`
+  }
+  if (!Array.isArray(v.command) || v.command.length === 0 || v.command.length > PRESET_ARGS_MAX) return `command must be a list of 1–${PRESET_ARGS_MAX} arguments (argv), not a string`
+  for (const [i, arg] of v.command.entries()) {
+    const problem = argProblem(arg, i)
+    if (problem) return problem
+  }
+  const native = nativeIDProblem(v.nativeID)
+  if (native) return native
+  if (v.resumeFlag !== undefined) {
+    if (!isFlag(v.resumeFlag)) return "resumeFlag must be one flag, e.g. --resume"
+    if ((v.nativeID as PresetNativeID).source === "none") return "resumeFlag needs a nativeID source (argv or screen) to resume by"
+  }
+  if (v.delivery !== "paste") return "delivery must be paste"
+  if (v.evidence !== "screen") return "evidence must be screen"
+  return undefined
+}
+
+/** Whether `v` is an acceptable harness preset (see presetProblem). */
+export const isHarnessPreset = (v: unknown): v is HarnessPreset => presetProblem(v) === undefined
+
+/** The preset schema as JSON Schema (draft 2020-12), for packs validated outside TypeScript. */
+export const PRESET_JSON_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "Hub harness preset",
+  type: "object",
+  additionalProperties: false,
+  required: ["name", "command", "nativeID", "delivery", "evidence"],
+  properties: {
+    name: { type: "string", pattern: "^[a-z0-9][a-z0-9._-]*$", maxLength: 64, not: { enum: [...RESERVED_HARNESS_NAMES] } },
+    description: { type: "string", maxLength: PRESET_DESCRIPTION_MAX },
+    command: {
+      type: "array",
+      minItems: 1,
+      maxItems: PRESET_ARGS_MAX,
+      items: { type: "string", minLength: 1, maxLength: PRESET_ARG_MAX, pattern: "^[^`$;|&<>\\\\'\"~][^`$;|&<>\\\\'\"]*$" },
+    },
+    resumeFlag: { type: "string", pattern: FLAG.source },
+    nativeID: {
+      oneOf: [
+        { type: "object", additionalProperties: false, required: ["source"], properties: { source: { const: "none" } } },
+        { type: "object", additionalProperties: false, required: ["source", "flag"], properties: { source: { const: "argv" }, flag: { type: "string", pattern: FLAG.source } } },
+        { type: "object", additionalProperties: false, required: ["source", "pattern"], properties: { source: { const: "screen" }, pattern: { type: "string", minLength: 1, maxLength: PRESET_PATTERN_MAX } } },
+      ],
+    },
+    delivery: { const: "paste" },
+    evidence: { const: "screen" },
+  },
+} as const

package/packages/protocol/src/webhook.ts

@@ -0,0 +1,62 @@
+// Webhook signatures (design §6.1; decision znbg8xa5 #8). Every webhook POST carries
+//   Hub-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the registration's secret>
+// plus Hub-Event (the event type) and Hub-Delivery (a delivery ID, the same on every retry, for deduplication).
+// While a secret rotates the header carries one v1 per secret; a receiver accepts any match. Receivers refuse a
+// timestamp outside WEBHOOK_TOLERANCE_SECONDS (replay) and compare signatures in constant time.
+// Only the format lives here (no crypto): the hub signs, the SDK verifies.
+
+export const WEBHOOK_SIGNATURE_HEADER = "Hub-Signature"
+export const WEBHOOK_EVENT_HEADER = "Hub-Event"
+export const WEBHOOK_DELIVERY_HEADER = "Hub-Delivery"
+export const WEBHOOK_SIGNATURE_SCHEME = "v1"
+/** The HMAC hash (node:crypto createHmac name). */
+export const WEBHOOK_SIGNATURE_ALGORITHM = "sha256"
+/** Largest gap, either way, between a signature's timestamp and the receiver's clock. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300
+/** Longest Hub-Signature header a receiver parses. */
+export const WEBHOOK_SIGNATURE_MAX = 2048
+
+export interface WebhookSignature {
+  /** Unix seconds. */
+  readonly t: number
+  /** Hex HMAC-SHA256 values, one per active secret. */
+  readonly v1: readonly string[]
+}
+
+const HEX_SHA256 = /^[0-9a-f]{64}$/
+
+/** The bytes the signature covers: `<t>.<raw body>`. */
+export function webhookSignedPayload(t: number, body: string): string {
+  return `${t}.${body}`
+}
+
+/** The Hub-Signature header value for timestamp `t` (unix seconds) and hex signatures. */
+export function formatWebhookSignature(t: number, signatures: readonly string[]): string {
+  return [`t=${t}`, ...signatures.map((s) => `${WEBHOOK_SIGNATURE_SCHEME}=${s}`)].join(",")
+}
+
+/** A Hub-Signature header's timestamp and v1 signatures, or undefined when it is malformed. Unknown schemes are ignored. */
+export function parseWebhookSignature(header: unknown): WebhookSignature | undefined {
+  if (typeof header !== "string" || header.length === 0 || header.length > WEBHOOK_SIGNATURE_MAX) return undefined
+  let t: number | undefined
+  const v1: string[] = []
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=")
+    if (eq < 0) return undefined
+    const key = part.slice(0, eq).trim()
+    const value = part.slice(eq + 1).trim()
+    if (key === "t") {
+      if (t !== undefined || !/^\d{1,12}$/.test(value)) return undefined
+      t = Number(value)
+    } else if (key === WEBHOOK_SIGNATURE_SCHEME) {
+      if (!HEX_SHA256.test(value)) return undefined
+      v1.push(value)
+    }
+  }
+  return t !== undefined && v1.length > 0 ? { t, v1 } : undefined
+}
+
+/** Whether timestamp `t` (unix seconds) is within `tolerance` seconds of `nowMs`. */
+export function webhookTimestampFresh(t: number, nowMs: number = Date.now(), tolerance: number = WEBHOOK_TOLERANCE_SECONDS): boolean {
+  return Math.abs(nowMs / 1000 - t) <= tolerance
+}

package/packages/protocol/src/wire.ts

@@ -0,0 +1,54 @@
+// Shared frame primitives for the spoke protocol (index.ts), the node protocol (node.ts) and launch checks
+// (launch.ts). Kept apart so those modules import values from here, never from each other in a cycle.
+
+/** Largest frame (in characters) either side accepts; a larger one is a protocol error. */
+export const MAX_FRAME = 1_000_000
+
+export const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+export const str = (v: unknown): v is string => typeof v === "string"
+export const nonEmpty = (v: unknown): v is string => typeof v === "string" && v.length > 0
+export const num = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
+/** A plain id: letters, digits and `_.:@/+~-`, 1–300 characters. */
+export const ID = /^[A-Za-z0-9_.:@/+~-]{1,300}$/
+/** A short lowercase token (harness id, evidence level, runtime kind). */
+export const token = (v: unknown, max: number): v is string => typeof v === "string" && v.length <= max && /^[a-z0-9][a-z0-9._-]*$/.test(v)
+/** A feature list: at most 64 names of 1–64 characters. */
+export const featureList = (v: unknown): v is string[] => Array.isArray(v) && v.length <= 64 && v.every((f) => nonEmpty(f) && f.length <= 64)
+/** Control (C0, C1), format (bidi, zero-width, BOM) and line/paragraph separator characters. */
+export const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\u2028\u2029]/u
+
+export const isResFrame = (v: Record<string, unknown>): boolean => nonEmpty(v.id) && typeof v.ok === "boolean" && (v.error === undefined || str(v.error))
+/** Longest reconnect delay a bye's retryAfterMs may ask for (5 minutes). */
+export const MAX_RETRY_AFTER_MS = 300_000
+/** A bye: a reason, and optionally (e.g. a draining hub) how soon to reconnect, in whole milliseconds. */
+export const isByeFrame = (v: Record<string, unknown>): boolean =>
+  str(v.reason) &&
+  (v.retryAfterMs === undefined || (Number.isInteger(v.retryAfterMs) && (v.retryAfterMs as number) >= 0 && (v.retryAfterMs as number) <= MAX_RETRY_AFTER_MS))
+export const isWelcomeFrame = (v: Record<string, unknown>): boolean =>
+  num(v.v) && nonEmpty(v.machineID) && str(v.publicURL) && (v.features === undefined || featureList(v.features))
+
+/** Longest hub URL a sessionTokens request or a start op carries. */
+export const HUB_URL_MAX_CHARS = 2048
+
+/** An http(s) URL of at most HUB_URL_MAX_CHARS characters. */
+export function isHubURL(v: unknown): v is string {
+  if (!nonEmpty(v) || v.length > HUB_URL_MAX_CHARS) return false
+  try {
+    const url = new URL(v)
+    return url.protocol === "http:" || url.protocol === "https:"
+  } catch {
+    return false
+  }
+}
+
+/** A frame's JSON object, or undefined when it is too large, not JSON or not an object. */
+export function parseFrame(raw: string | Buffer): Record<string, unknown> | undefined {
+  const text = typeof raw === "string" ? raw : raw.toString("utf8")
+  if (text.length > MAX_FRAME) return undefined
+  try {
+    const value = JSON.parse(text)
+    return isObj(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}

package/packages/runtime-openshell/image/Dockerfile

@@ -0,0 +1,36 @@
+# The hub sandbox image: what an OpenShell sandbox of `hub node` runs (packages/runtime-openshell; spike report
+# gut64rwq). Build it with build.ts, never from the repository root: the context is a staged directory holding
+#   bin/opencode            the pinned Linux OpenCode build (npm @opencode/cli-linux-<arch>@<OPENCODE_VERSION>)
+#   bin/hub-sandbox-start   bin/hub-sandbox-entry   (entry.sh, start.sh)
+#   lib/hub/node_modules/@huynle/hub               the hub plugin, installed from this repository's package
+#   bun packages/runtime-openshell/image/build.ts image [--arch arm64|x64] [--tag NAME:TAG]
+# The runtime creates the sandbox with no main command (it stays Ready) and execs /usr/local/bin/hub-sandbox-start,
+# which waits for /sandbox/.hub/config.json and .hub/ready and runs `opencode serve --service`. OpenShell runs it as
+# its own user (HOME=/sandbox, the only writable place with /tmp) and injects its proxy CA through the Node and
+# OpenSSL CA environment variables, which nothing here may set or clear.
+FROM debian:bookworm-slim
+
+ARG HUB_VERSION=dev
+ARG OPENCODE_VERSION=dev
+LABEL org.opencontainers.image.title="hub-sandbox" \
+      org.opencontainers.image.description="Hub sandbox: OpenCode with the hub plugin, for hub node's OpenShell runtime" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.source="https://github.com/huynle/hub" \
+      org.opencontainers.image.version="${HUB_VERSION}" \
+      io.github.huynle.hub.opencode-version="${OPENCODE_VERSION}"
+
+RUN apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends git bash ca-certificates curl procps \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY bin/ /usr/local/bin/
+COPY lib/hub/ /usr/local/lib/hub/
+RUN chmod 0755 /usr/local/bin/opencode /usr/local/bin/hub-sandbox-start /usr/local/bin/hub-sandbox-entry \
+ && chmod -R a+rX /usr/local/lib/hub
+
+# The harness stays offline but for the hub and its providers (decision lk6gn3u7 §7); the entry script sets them
+# again, so the bootstrap fallback on another image gets them too.
+ENV OPENCODE_DISABLE_MODELS_FETCH=1 \
+    OPENCODE_DISABLE_AUTOUPDATE=1 \
+    OPENCODE_DISABLE_PROJECT_CONFIG=1 \
+    HUB_SANDBOX_IMAGE=${HUB_VERSION}

package/packages/runtime-openshell/image/README.md

@@ -0,0 +1,78 @@
+# hub sandbox image
+
+What an OpenShell sandbox of `hub node` runs (design §6.4, decision lk6gn3u7, spike report gut64rwq): Debian
+bookworm-slim with git, bash, ca-certificates, curl and procps, the pinned Linux OpenCode
+(`@opencode/cli-linux-<arch>@OPENCODE_VERSION` from npm, checked against the registry's sha512), the hub plugin
+(this repository's package, installed with its production dependencies) and two scripts.
+
+| File | What |
+|---|---|
+| `image.ts` | Names, layout and the commands the runtime and `build.ts` run (pure) |
+| `build.ts` | Stages the layout, builds the image (`docker build`), or packs the bootstrap tarball |
+| `Dockerfile` | The image, built from the staged context only |
+| `start.sh` → `bin/hub-sandbox-start` | Starts the entry detached (`setsid nohup`, log `.hub/harness.log`) and returns |
+| `entry.sh` → `bin/hub-sandbox-entry` | Waits for the start op, runs and supervises `opencode serve --service` |
+
+## Layout
+
+The same under both roots, so one entry script serves both:
+
+```
+<root>/bin/opencode                       IMAGE_ROOT     = /usr/local          (the image)
+<root>/bin/hub-sandbox-start              BOOTSTRAP_ROOT = /sandbox/.hub/opt   (the upload fallback)
+<root>/bin/hub-sandbox-entry
+<root>/lib/hub/node_modules/@huynle/hub   the plugin
+```
+
+## Contract with the runtime
+
+1. Create the sandbox **without a main command** (it stays Ready; a main command that ends moves it to Completed and
+   exec is refused).
+2. Exec `startCommand(root)` (`/usr/local/bin/hub-sandbox-start`) at any point; it returns at once and a second call
+   does nothing while the entry runs.
+3. Upload `.hub/config.json` (`{hubURL, token, launchID}`, read by the plugin's spoke, never by the scripts),
+   optionally `.hub/env.json` (a JSON object of extra variables), then touch `.hub/ready`. The entry waits for both
+   `config.json` and `ready`.
+4. The entry sets `OPENCODE_DISABLE_MODELS_FETCH/AUTOUPDATE/PROJECT_CONFIG=1`, `XDG_*_HOME=/sandbox/.xdg/*`,
+   `HUB_LAUNCH_CONFIG`, a random `OPENCODE_PASSWORD` unless given, and writes the global OpenCode config loading the
+   plugin. `env.json` cannot override those, `PATH`, `HOME`, `BUN_*`/`LD_*` or OpenShell's CA variables
+   (`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, …), which are kept as OpenShell injected them: Bun trusts the proxy CA only
+   through them. An invalid `env.json` ends the entry with status 2.
+5. It runs `opencode serve --service --hostname 127.0.0.1 --port 4096` in `/sandbox/work` (else `/sandbox`) and sends
+   one authorized request so the server loads its instance and the plugin.
+6. `.hub/stop` holding `graceful` (SIGTERM, SIGKILL after `HUB_STOP_GRACE`, 10 s) or `kill` (SIGKILL) stops it;
+   `.hub/exited` then holds the exit code. `.hub/entry.pid` and `.hub/harness.pid` exist while they run.
+
+## Build
+
+```sh
+bun packages/runtime-openshell/image/build.ts image [--arch arm64|x64] [--tag NAME:TAG]   # docker build, never pushes
+bun packages/runtime-openshell/image/build.ts bootstrap [--arch arm64|x64] [--out FILE.tgz]
+bun packages/runtime-openshell/image/build.ts stage --out DIR [--arch arm64|x64]
+```
+
+The default tag is `hub-sandbox:<hub version>-opencode<OpenCode version>`; the architecture defaults to the host's.
+`HUB_IT_DOCKER=1 bun test packages/runtime-openshell/test/image-docker.it.test.ts` builds it under a throwaway tag,
+checks it and removes it.
+
+## Publishing (deliberate, not automated)
+
+OpenShell's vm driver does **not** use local Docker images: it pulls from an **HTTPS registry** (a plain-http local
+registry is refused, rootfs tarballs need the gateway's `allow_driver_config`, and local images only work when the
+gateway itself sees a container engine through `DOCKER_HOST` or `/var/run/docker.sock`, an operator choice). To use the
+image, publish it, for example:
+
+```sh
+bun packages/runtime-openshell/image/build.ts image --arch arm64 --tag ghcr.io/<owner>/hub-sandbox:<tag>
+docker push ghcr.io/<owner>/hub-sandbox:<tag>   # or a multi-arch manifest built per architecture
+```
+
+and point the node at it (`openshell.profiles.<name>.image` in node.json, or the runtime's default image).
+
+## Upload fallback (gateways that cannot pull the image)
+
+On the gateway's default image (`nvcr.io/nvidia/base/ubuntu:24.04`; `/usr` read-only), the runtime uploads the
+bootstrap tarball under `/sandbox/.hub/`, runs `bootstrapCommands(uploaded)` (unpack into `/sandbox/.hub/opt`, remove
+the tarball) and then `startCommand(BOOTSTRAP_ROOT)`. Two limits: the sandbox policy must allow
+`harnessBinary(BOOTSTRAP_ROOT)` (`/sandbox/.hub/opt/bin/opencode`) instead of `/usr/local/bin/opencode`, and that
+image has no git (the runtime's clone and collect need it), so the fallback needs git from elsewhere.

package/packages/runtime-openshell/image/build.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env bun
+// Builds the hub sandbox image, or the bootstrap tarball of the upload fallback (see README.md next to this file).
+//
+//   bun packages/runtime-openshell/image/build.ts image     [--arch arm64|x64] [--tag NAME:TAG]
+//   bun packages/runtime-openshell/image/build.ts bootstrap [--arch arm64|x64] [--out FILE.tgz]
+//   bun packages/runtime-openshell/image/build.ts stage     --out DIR [--arch arm64|x64]
+//
+// All three stage the same layout (image.ts): bin/opencode (the pinned Linux OpenCode from the npm registry, checked
+// against the registry's sha512 integrity), bin/hub-sandbox-start and bin/hub-sandbox-entry (start.sh, entry.sh) and
+// lib/hub/node_modules/@huynle/hub (this repository packed with `npm pack --ignore-scripts` and installed with its
+// production dependencies). `image` adds the Dockerfile and runs `docker build` for one platform; it never pushes
+// (OpenShell's vm driver pulls from an HTTPS registry, not from local Docker: publishing is a separate, deliberate
+// step, see README.md). `bootstrap` packs the layout as a .tgz for the runtime to upload into /sandbox/.hub/opt.
+import { createHash } from "node:crypto"
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import {
+  ENTRY_SCRIPT,
+  OPENCODE_VERSION,
+  PLUGIN_SUBPATH,
+  START_SCRIPT,
+  bootstrapTarballName,
+  dockerBuildArgs,
+  imageTag,
+  linuxArch,
+  opencodeMetadataURL,
+  opencodeTarballURL,
+  type LinuxArch,
+} from "./image.ts"
+
+/** Runs a command (argv, no shell) and returns its stdout; throws on a non-zero exit. */
+export type Run = (cmd: readonly string[], cwd?: string) => Promise<string>
+
+const HERE = import.meta.dir
+const REPO_ROOT = path.join(HERE, "..", "..", "..")
+const REGISTRY = "https://registry.npmjs.org/"
+
+export const run: Run = async (cmd, cwd) => {
+  // COPYFILE_DISABLE: macOS tar would add AppleDouble ._ files to the bootstrap tarball.
+  const p = Bun.spawn([...cmd], { cwd, env: { ...process.env, COPYFILE_DISABLE: "1" }, stdout: "pipe", stderr: "pipe" })
+  const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+  if (code !== 0) throw new Error(`${cmd.join(" ")} failed (exit ${code}): ${err.trim().split("\n").slice(-5).join("\n")}`)
+  return out
+}
+
+/** Throws unless `bytes` match an npm sha512 subresource-integrity string. */
+export function verifyIntegrity(bytes: Uint8Array, integrity: string): void {
+  const sha512 = integrity.split(/\s+/).find((s) => s.startsWith("sha512-"))
+  if (!sha512) throw new Error(`expected a sha512 integrity, got ${JSON.stringify(integrity)}`)
+  const actual = `sha512-${createHash("sha512").update(bytes).digest("base64")}`
+  if (actual !== sha512) throw new Error(`integrity mismatch: expected ${sha512}, got ${actual}`)
+}
+
+export interface BuildOptions {
+  readonly arch: LinuxArch
+  /** This repository (default: three levels up from this file). */
+  readonly repoRoot?: string
+  readonly opencodeVersion?: string
+  readonly fetch?: typeof fetch
+  readonly run?: Run
+  readonly log?: (line: string) => void
+}
+
+export interface StageOptions extends BuildOptions {
+  /** The context directory: created, or empty. */
+  readonly dir: string
+  /** Copy the Dockerfile too (default true). */
+  readonly dockerfile?: boolean
+}
+
+/** Stages the layout into `dir`; returns the hub version packed. */
+export async function stage(o: StageOptions): Promise<{ dir: string; hubVersion: string }> {
+  const exec = o.run ?? run
+  const get = o.fetch ?? fetch
+  const log = o.log ?? (() => {})
+  const repoRoot = o.repoRoot ?? REPO_ROOT
+  const version = o.opencodeVersion ?? OPENCODE_VERSION
+  if (existsSync(o.dir) && readdirSync(o.dir).length > 0) throw new Error(`the context directory ${o.dir} is not empty`)
+  const bin = path.join(o.dir, "bin")
+  mkdirSync(bin, { recursive: true })
+  const work = mkdtempSync(path.join(process.env.TMPDIR ?? tmpdir(), "hub-sandbox-stage-"))
+  try {
+    // The Linux OpenCode build, checked against the registry's integrity.
+    log(`fetching OpenCode ${version} for linux-${o.arch}`)
+    const meta = await get(opencodeMetadataURL(o.arch, version))
+    if (!meta.ok) throw new Error(`npm registry: ${meta.status} for ${opencodeMetadataURL(o.arch, version)}`)
+    const dist = ((await meta.json()) as { dist?: { tarball?: unknown; integrity?: unknown } }).dist
+    if (typeof dist?.tarball !== "string" || typeof dist.integrity !== "string") throw new Error("npm registry: no dist.tarball/dist.integrity")
+    if (!dist.tarball.startsWith(REGISTRY)) throw new Error(`refusing an OpenCode tarball outside the npm registry: ${dist.tarball}`)
+    const res = await get(dist.tarball)
+    if (!res.ok) throw new Error(`npm registry: ${res.status} for ${dist.tarball}`)
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    verifyIntegrity(bytes, dist.integrity)
+    const tgz = path.join(work, "opencode.tgz")
+    writeFileSync(tgz, bytes)
+    await exec(["tar", "-xzf", tgz, "-C", work, "package/bin/opencode"])
+    copyFileSync(path.join(work, "package/bin/opencode"), path.join(bin, "opencode"))
+    chmodSync(path.join(bin, "opencode"), 0o755)
+
+    // The scripts.
+    for (const [name, src] of [
+      [START_SCRIPT, "start.sh"],
+      [ENTRY_SCRIPT, "entry.sh"],
+    ] as const) {
+      copyFileSync(path.join(HERE, src), path.join(bin, name))
+      chmodSync(path.join(bin, name), 0o755)
+    }
+
+    // The hub plugin: this repository as its npm package, with production dependencies.
+    log("packing the hub plugin")
+    const packed = JSON.parse(await exec(["npm", "pack", "--ignore-scripts", "--json", "--pack-destination", work], repoRoot)) as Array<{ filename: string }>
+    const file = packed[0]?.filename
+    if (!file) throw new Error("npm pack reported no file")
+    const prefix = path.join(o.dir, "lib/hub")
+    mkdirSync(prefix, { recursive: true })
+    await exec(["npm", "install", "--prefix", prefix, "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund", "--no-package-lock", path.join(work, path.basename(file))], work)
+    if (!existsSync(path.join(o.dir, PLUGIN_SUBPATH, "server.ts"))) throw new Error(`the plugin was not installed at ${PLUGIN_SUBPATH}`)
+    // The prefix's package.json only names the temporary tarball.
+    rmSync(path.join(prefix, "package.json"), { force: true })
+
+    if (o.dockerfile !== false) copyFileSync(path.join(HERE, "Dockerfile"), path.join(o.dir, "Dockerfile"))
+  } finally {
+    rmSync(work, { recursive: true, force: true })
+  }
+  const hubVersion = (JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8")) as { version: string }).version
+  return { dir: o.dir, hubVersion }
+}
+
+function tempDir(prefix: string): string {
+  return mkdtempSync(path.join(process.env.TMPDIR ?? tmpdir(), prefix))
+}
+
+/** Builds the image locally (docker build); never pushes. */
+export async function buildImage(o: BuildOptions & { tag?: string }): Promise<{ tag: string }> {
+  const exec = o.run ?? run
+  const dir = tempDir("hub-sandbox-image-")
+  try {
+    const { hubVersion } = await stage({ ...o, dir })
+    const tag = o.tag ?? imageTag(hubVersion, o.opencodeVersion)
+    o.log?.(`docker build ${tag}`)
+    await exec(["docker", ...dockerBuildArgs({ tag, arch: o.arch, context: dir, hubVersion, ...(o.opencodeVersion ? { opencodeVersion: o.opencodeVersion } : {}) })])
+    return { tag }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/** Packs the layout as the bootstrap tarball (default name in the current directory). */
+export async function buildBootstrap(o: BuildOptions & { out?: string }): Promise<{ out: string }> {
+  const exec = o.run ?? run
+  const dir = tempDir("hub-sandbox-bootstrap-")
+  try {
+    const { hubVersion } = await stage({ ...o, dir, dockerfile: false })
+    const out = path.resolve(o.out ?? bootstrapTarballName(hubVersion, o.arch, o.opencodeVersion))
+    await exec(["tar", "-czf", out, "--no-xattrs", "-C", dir, "bin", "lib"])
+    return { out }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+export interface Args {
+  readonly command: "image" | "bootstrap" | "stage"
+  readonly arch: LinuxArch
+  readonly tag?: string
+  readonly out?: string
+}
+
+const USAGE = "usage: build.ts image [--arch arm64|x64] [--tag NAME:TAG] | bootstrap [--arch arm64|x64] [--out FILE.tgz] | stage --out DIR [--arch arm64|x64]"
+
+export function parseArgs(argv: readonly string[]): Args {
+  const [command, ...rest] = argv
+  if (command !== "image" && command !== "bootstrap" && command !== "stage") throw new Error(USAGE)
+  let arch: LinuxArch = linuxArch(process.arch)
+  let tag: string | undefined
+  let out: string | undefined
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i]!
+    const allowed = flag === "--arch" || (flag === "--tag" && command === "image") || (flag === "--out" && command !== "image")
+    if (!allowed) throw new Error(`unknown option ${flag}\n${USAGE}`)
+    const value = rest[++i]
+    if (value === undefined || value.startsWith("--")) throw new Error(`${flag} needs a value`)
+    if (flag === "--arch") arch = linuxArch(value)
+    else if (flag === "--tag") tag = value
+    else out = value
+  }
+  if (command === "stage" && !out) throw new Error(`stage needs --out DIR\n${USAGE}`)
+  return { command, arch, ...(tag ? { tag } : {}), ...(out ? { out } : {}) }
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseArgs(process.argv.slice(2))
+    const log = (line: string) => console.error(`[build] ${line}`)
+    if (args.command === "image") console.log((await buildImage({ arch: args.arch, log, ...(args.tag ? { tag: args.tag } : {}) })).tag)
+    else if (args.command === "bootstrap") console.log((await buildBootstrap({ arch: args.arch, log, ...(args.out ? { out: args.out } : {}) })).out)
+    else console.log((await stage({ arch: args.arch, log, dir: path.resolve(args.out!) })).dir)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exit(1)
+  }
+}