@specific.dev/spectest 0.78.0 → 0.79.1

package/src/components/expo.ts

@@ -2,32 +2,96 @@
 // to the web, built for `ctx.mobile(...)`.
 //
 // Serving model: STATIC EXPORT. The image runs `expo export -p web` at build
-// time (producing `dist/`) and the container just serves those static files
-// with a tiny Node server. No Metro at runtime — so the ready-check is fast
-// and deterministic and the bundle rides the image-layer cache, instead of
-// paying a non-deterministic first-request bundle on every boot.
+// time (which makes `dist/`) and the container serves those files with a
+// small Node server. There is no Metro at runtime, so the ready check is fast
+// and the bundle rides the image-layer cache.
+//
+// The generated Dockerfile is written for the cache. It installs the
+// dependencies from the manifests BEFORE it copies the source, so a source
+// edit does not install them again. The package manager comes from the app
+// itself (its `packageManager` field, else its lockfile), and it installs
+// from the lockfile when there is one. Its download store and Metro's
+// transform cache are BuildKit cache mounts, so each build starts from the
+// work of the build before it.
+//
+// An app with its own Dockerfile gives `dockerfile` instead. The contract is
+// then small and it is written down: the image must hold the web export at
+// `staticDir` (default `/app/dist`), and it must have `node` on the PATH.
+// The server names the directory and stops if the export is not there.
 //
 // The service's `helpers` factory returns a `MobileApp` handle (the resolved
 // in-VM URL), so a test drives it with `ctx.mobile(ctx.svc.app)` — no URL, no
 // `navigate`.
 
-import type { ServiceDefinition } from "../index.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ServiceDefinition, ServiceImage } from "../index.js";
 import { mobileApp } from "../mobile.js";
 import type { MobileApp } from "../mobile.js";
 
+/** The package managers the generated Dockerfile can install with. */
+export type ExpoPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
 export interface ExpoOptions {
   /** Port the static server listens on. Default `8081`. */
   port?: number;
   /**
-   * App directory inside the project, relative to the build context root.
+   * App directory inside the project, relative to the project root.
    * Default `"."` (the project root is the Expo app). Set this when the
-   * Expo app lives in a subdirectory of a larger repo.
+   * Expo app lives in a subdirectory of a larger repo. It is also the
+   * build context, so the image can only copy files from below it.
    */
   appDir?: string;
-  /** Node base image tag. Default `"20-bookworm-slim"`. */
+  /**
+   * Node base image tag for the generated Dockerfile. The default comes
+   * from the app: `engines.node` in its `package.json`, else `.nvmrc` or
+   * `.node-version`, else `"22-bookworm-slim"`. A declared version becomes
+   * the tag `<major>-bookworm-slim`.
+   */
   nodeVersion?: string;
+  /**
+   * Package manager for the generated Dockerfile. The default comes from
+   * the app: its `packageManager` field, else its lockfile
+   * (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `package-lock.json`), else
+   * npm. With a lockfile the install is a locked one (`npm ci`,
+   * `pnpm install --frozen-lockfile`, …), so a lockfile that does not agree
+   * with `package.json` fails the build instead of installing something
+   * else.
+   */
+  packageManager?: ExpoPackageManager;
   /** Output dir `expo export` writes to (relative to the app dir). Default `"dist"`. */
   outputDir?: string;
+  /**
+   * Build the image from a Dockerfile in your repo instead of the generated
+   * one. The path is relative to the project root. Two rules apply to that
+   * image, and nothing else does: it must hold the web export at
+   * {@link staticDir} (default `/app/dist`), and it must have `node` on the
+   * PATH, because the container command is the static server this component
+   * mounts into it.
+   *
+   * The options that describe the generated Dockerfile — `nodeVersion`,
+   * `packageManager`, `outputDir`, and `EXPO_PUBLIC_*` entries in `env` —
+   * do not apply to your file, so naming them together is an error rather
+   * than a setting that does nothing.
+   */
+  dockerfile?: string;
+  /**
+   * Build context for {@link dockerfile}, relative to the project root.
+   * Default {@link appDir}. Use it when the Dockerfile builds from a
+   * directory above itself, as in a monorepo.
+   */
+  context?: string;
+  /** Stage to build, as `docker build --target <stage>`. */
+  target?: string;
+  /** Build args, as `--build-arg NAME=value`. */
+  buildArgs?: Record<string, string>;
+  /**
+   * Directory INSIDE the image that holds the web export. Default
+   * `/app/<outputDir>`, which is where the generated Dockerfile writes it.
+   * Set it when your own Dockerfile exports somewhere else.
+   */
+  staticDir?: string;
   /**
    * Extra environment variables. `EXPO_PUBLIC_*` keys are additionally baked
    * into the image build so `expo export` inlines them into the bundle —
@@ -49,9 +113,17 @@ export type ExpoHelpers = MobileApp;
 
 // A dependency-free static file server with SPA fallback. Bind-mounted into
 // the container (so it isn't baked into the image build) and run as the
-// container command. Serves `dist/`, falling back to index.html for client
-// routes. Embedded as a file rather than `npx serve` so the container needs
-// no extra install at runtime.
+// container command. Serves the export directory, falling back to index.html
+// for client routes. Embedded as a file rather than `npx serve` so the
+// container needs no extra install at runtime.
+//
+// Landmine: this is a `String.raw` template, so a backtick or a `${` in it
+// ends the string. Write the text without them.
+//
+// It reads the export directory before it listens. An image that holds no
+// export answers nothing, so without this check the only report is a ready
+// check that times out 60 seconds later. That is the one part of the
+// `dockerfile` contract a machine can test, so it tests it.
 const STATIC_SERVER = String.raw`import { createServer } from "node:http";
 import { stat, readFile } from "node:fs/promises";
 import { join, extname, normalize, resolve } from "node:path";
@@ -71,6 +143,18 @@ const TYPES = {
   ".ttf": "font/ttf", ".otf": "font/otf", ".wasm": "application/wasm",
 };
 
+try {
+  await stat(join(root, "index.html"));
+} catch {
+  console.error(
+    "[expo-static] " + root + " holds no index.html.\n" +
+      "expo() serves the web export from that directory in the image.\n" +
+      "Make the image build write the 'expo export --platform web' output there,\n" +
+      "or point expo({ staticDir }) at the directory that holds it.",
+  );
+  process.exit(1);
+}
+
 async function send(res, fp) {
   const body = await readFile(fp);
   res.writeHead(200, { "content-type": TYPES[extname(fp)] || "application/octet-stream" });
@@ -98,6 +182,274 @@ createServer(async (req, res) => {
 }).listen(port, "0.0.0.0", () => console.log("[expo-static] serving " + root + " on :" + port));
 `;
 
+/** Where Metro keeps its transform cache. It is `os.tmpdir()/metro-cache`,
+ *  which is what `@expo/metro-config` sets. A cache mount there keeps the
+ *  transforms of the build before this one. */
+const METRO_CACHE_DIR = "/tmp/metro-cache";
+
+/** The project root inside the VM. Read at call time, like `supabase()`
+ *  reads it: a component is loaded before a hook context exists. */
+function projectRootPath(): string {
+  return process.env.SPECTEST_WORKSPACE ?? "/workspace";
+}
+
+/** What the app dir tells us about itself, read once at load. */
+interface AppFacts {
+  /** Absolute path of the app dir in the VM. */
+  dir: string;
+  /** Parsed `package.json`, or `null` if it could not be parsed. */
+  pkg: Record<string, unknown> | null;
+  /** Is there such a file or directory in the app dir? */
+  has(name: string): boolean;
+}
+
+function readAppFacts(appDir: string): AppFacts {
+  const dir = join(projectRootPath(), appDir);
+  if (!existsSync(dir)) {
+    throw new Error(`expo(): appDir ${JSON.stringify(appDir)} is not in the project`);
+  }
+  if (!statSync(dir).isDirectory()) {
+    throw new Error(`expo(): appDir ${JSON.stringify(appDir)} is not a directory`);
+  }
+  const has = (name: string): boolean => existsSync(join(dir, name));
+  let pkg: Record<string, unknown> | null = null;
+  if (has("package.json")) {
+    try {
+      pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as Record<string, unknown>;
+    } catch (e) {
+      throw new Error(`expo(): ${appDir}/package.json is not valid JSON: ${String(e)}`);
+    }
+  }
+  return { dir, pkg, has };
+}
+
+/** First line of a version file, without a `v` prefix. */
+function readVersionFile(facts: AppFacts, name: string): string | null {
+  if (!facts.has(name)) return null;
+  const text = readFileSync(join(facts.dir, name), "utf8").split("\n")[0]!.trim();
+  return text === "" ? null : text.replace(/^v/, "");
+}
+
+/**
+ * The Node major version a range asks for. Clauses with an exclusive upper
+ * bound (`<21`) name a version the app must NOT run, so they are dropped
+ * first; of the rest the highest wins, because a range like `18 || 20 || 22`
+ * lists what the app supports and the newest is the one to build on.
+ *
+ * Exported for the unit test; it is not part of the component's surface.
+ */
+export function nodeMajorFromRange(range: string): number | null {
+  // A version is one token, so only its first number is a major: `18.20.4`
+  // asks for Node 18, not Node 20.
+  const kept = range.replace(/<=?\s*\d+(?:\.[\dx*]+)*/gi, " ");
+  const majors = [...kept.matchAll(/(\d+)(?:\.[\dx*]+)*/gi)].map((m) => Number(m[1]));
+  const usable = majors.filter((n) => n >= 12 && n <= 99);
+  return usable.length === 0 ? null : Math.max(...usable);
+}
+
+/** The Node the app declares, and where it said so. */
+function declaredNode(facts: AppFacts): { tag: string; source: string } | null {
+  const engines = facts.pkg?.engines as { node?: unknown } | undefined;
+  const candidates: Array<[string, string | null]> = [
+    ["engines.node", typeof engines?.node === "string" ? engines.node : null],
+    [".nvmrc", readVersionFile(facts, ".nvmrc")],
+    [".node-version", readVersionFile(facts, ".node-version")],
+  ];
+  for (const [source, value] of candidates) {
+    if (value === null) continue;
+    const major = nodeMajorFromRange(value);
+    // `lts/*` and other names carry no number. Say nothing and use the default.
+    if (major === null) continue;
+    return { tag: `${major}-bookworm-slim`, source: `${source} ${JSON.stringify(value)}` };
+  }
+  return null;
+}
+
+/** Node to build on when the app declares none. */
+const DEFAULT_NODE = "22-bookworm-slim";
+
+/** A lockfile per package manager. `bun.lockb` is the older binary one. */
+const LOCKFILES: Record<ExpoPackageManager, readonly string[]> = {
+  pnpm: ["pnpm-lock.yaml"],
+  yarn: ["yarn.lock"],
+  bun: ["bun.lock", "bun.lockb"],
+  npm: ["package-lock.json", "npm-shrinkwrap.json"],
+};
+
+/** The package manager the app uses, and where it said so. */
+function declaredPackageManager(facts: AppFacts): { pm: ExpoPackageManager; source: string } | null {
+  // `packageManager` is the one the app pins for Corepack, so it wins.
+  const field = facts.pkg?.packageManager;
+  if (typeof field === "string") {
+    const name = field.split("@")[0] as ExpoPackageManager;
+    if (name in LOCKFILES) return { pm: name, source: `packageManager ${JSON.stringify(field)}` };
+  }
+  // Order matters only for an app that holds two lockfiles. The one that is
+  // not npm's is the deliberate one, because npm writes its own on any
+  // `npm install` a tool ran by accident.
+  for (const pm of ["pnpm", "yarn", "bun", "npm"] as const) {
+    const found = LOCKFILES[pm].find((f) => facts.has(f));
+    if (found !== undefined) return { pm, source: found };
+  }
+  return null;
+}
+
+/** Everything the Dockerfile needs to install with one package manager. */
+interface InstallPlan {
+  /** Files and directories to copy before the install step. */
+  manifests: string[];
+  /** `ENV` lines the package manager needs. */
+  env: string[];
+  /** `RUN` lines that make the package manager available. */
+  bootstrap: string[];
+  /** Directory the download store lives in — the cache mount target. */
+  cacheDir: string;
+  /** The install command. */
+  install: string;
+  /** How to run the local `expo` binary. */
+  exec: string;
+  /** Is this install locked to the lockfile? */
+  locked: boolean;
+}
+
+/**
+ * The install step for one package manager.
+ *
+ * Only the files an install reads are copied before it, so a source edit
+ * keeps the installed layer. `patches` is one of them: patch-package and
+ * pnpm's `patchedDependencies` both apply patches during the install, and an
+ * install that cannot see them applies none and says so in a line nobody
+ * reads.
+ */
+function installPlan(facts: AppFacts, pm: ExpoPackageManager): InstallPlan {
+  const lock = LOCKFILES[pm].find((f) => facts.has(f));
+  const shared = ["package.json", ...(lock === undefined ? [] : [lock])];
+  const optional = (names: string[]): string[] => names.filter((n) => facts.has(n));
+  const patches = optional(["patches"]);
+  const pinned = typeof facts.pkg?.packageManager === "string";
+
+  switch (pm) {
+    case "npm":
+      return {
+        manifests: [...shared, ...optional([".npmrc"]), ...patches],
+        env: [],
+        bootstrap: [],
+        cacheDir: "/root/.npm",
+        // `npm ci` needs the lockfile and installs exactly it.
+        install: lock === undefined ? "npm install" : "npm ci",
+        exec: "npx expo",
+        locked: lock !== undefined,
+      };
+    case "pnpm":
+      return {
+        manifests: [...shared, ...optional([".npmrc", "pnpm-workspace.yaml", ".pnpmfile.cjs"]), ...patches],
+        // Corepack asks before it downloads a package manager. Answer first.
+        env: ["ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0"],
+        bootstrap: ["corepack enable pnpm"],
+        // The store is a cache mount, so it is not on the same filesystem as
+        // node_modules. pnpm then copies where it usually links, which costs
+        // disk in the image but keeps the download.
+        cacheDir: "/pnpm-store",
+        install: `pnpm install --store-dir /pnpm-store${lock === undefined ? "" : " --frozen-lockfile"}`,
+        exec: "pnpm exec expo",
+        locked: lock !== undefined,
+      };
+    case "yarn": {
+      // Yarn 1 comes with the Node image. Yarn 2 and later are a per-project
+      // release that Corepack installs, and they keep the cache elsewhere.
+      const berry = facts.has(".yarnrc.yml") || /^yarn@[2-9]/.test(String(facts.pkg?.packageManager ?? ""));
+      if (berry) {
+        return {
+          manifests: [...shared, ...optional([".yarnrc.yml", ".npmrc", ".yarn"]), ...patches],
+          env: ["ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0", "ENV YARN_ENABLE_GLOBAL_CACHE=1"],
+          bootstrap: [pinned ? "corepack enable yarn" : "corepack enable yarn && corepack prepare yarn@stable --activate"],
+          cacheDir: "/root/.yarn/berry/cache",
+          install: `yarn install${lock === undefined ? "" : " --immutable"}`,
+          exec: "yarn expo",
+          locked: lock !== undefined,
+        };
+      }
+      return {
+        manifests: [...shared, ...optional([".yarnrc", ".npmrc"]), ...patches],
+        env: [],
+        bootstrap: [],
+        cacheDir: "/yarn-cache",
+        install: `yarn install --cache-folder /yarn-cache${lock === undefined ? "" : " --frozen-lockfile"}`,
+        exec: "yarn expo",
+        locked: lock !== undefined,
+      };
+    }
+    case "bun":
+      return {
+        manifests: [...shared, ...optional([".npmrc", "bunfig.toml"]), ...patches],
+        env: [],
+        // The Node image has no Bun. Bun publishes itself to npm.
+        bootstrap: ["npm install -g bun"],
+        cacheDir: "/root/.bun/install/cache",
+        install: `bun install${lock === undefined ? "" : " --frozen-lockfile"}`,
+        exec: "bunx expo",
+        locked: lock !== undefined,
+      };
+  }
+}
+
+/** `ENV` lines for the `EXPO_PUBLIC_*` entries, ready for the Dockerfile. */
+function publicEnvLines(env: Record<string, string>): string[] {
+  return Object.entries(env)
+    .filter(([k]) => k.startsWith("EXPO_PUBLIC_"))
+    .map(([k, v]) => {
+      if (/[\r\n]/.test(v)) {
+        throw new Error(`expo(): env ${k} must not contain newlines (baked into the Dockerfile)`);
+      }
+      return `ENV ${k}="${v.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+    });
+}
+
+/**
+ * The generated Dockerfile.
+ *
+ * The order of the steps is the whole point. The manifests come first and the
+ * install runs on them alone, so an edit to the app keeps that layer. The
+ * source comes next. The `EXPO_PUBLIC_*` values come last before the export,
+ * because Expo inlines them at export time and a change to one must not
+ * install the dependencies again.
+ *
+ * Two cache mounts survive the build: the package manager's download store,
+ * and Metro's transform cache. They stay in this project's BuildKit state
+ * (CONTAINER_STORE.md), so the next cold build starts from them. They need
+ * BuildKit, which every builder in a VM is.
+ */
+function generateDockerfile(input: {
+  nodeVersion: string;
+  plan: InstallPlan;
+  publicEnv: string[];
+  outputDir: string;
+}): string {
+  const { nodeVersion, plan, publicEnv, outputDir } = input;
+  const lines = [`FROM node:${nodeVersion}`, "WORKDIR /app", "ENV CI=1", ...plan.env];
+  for (const step of plan.bootstrap) lines.push(`RUN ${step}`);
+  lines.push(`COPY ${plan.manifests.join(" ")} ./`);
+  lines.push(`RUN --mount=type=cache,target=${plan.cacheDir},sharing=locked ${plan.install}`);
+  lines.push("COPY . .");
+  lines.push(...publicEnv);
+  lines.push(
+    `RUN --mount=type=cache,target=${METRO_CACHE_DIR},sharing=locked ` +
+      `${plan.exec} export --platform web --output-dir ${outputDir}`,
+  );
+  return lines.join("\n") + "\n";
+}
+
+/** Options that describe the generated Dockerfile, and thus mean nothing
+ *  beside `dockerfile`. Each is named if it is set. */
+function conflictingOptions(opts: ExpoOptions): string[] {
+  const named: string[] = [];
+  if (opts.nodeVersion !== undefined) named.push("nodeVersion");
+  if (opts.packageManager !== undefined) named.push("packageManager");
+  if (opts.outputDir !== undefined) named.push("outputDir");
+  if (Object.keys(opts.env ?? {}).some((k) => k.startsWith("EXPO_PUBLIC_"))) named.push("EXPO_PUBLIC_* in env");
+  return named;
+}
+
 /**
  * A ready-to-use Expo (web) service. Drop into `environment.services` and
  * drive it with `ctx.mobile`:
@@ -115,42 +467,84 @@ createServer(async (req, res) => {
 export function expo(opts: ExpoOptions = {}) {
   const port = opts.port ?? 8081;
   const appDir = opts.appDir ?? ".";
-  const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
   const outputDir = opts.outputDir ?? "dist";
+  const staticDir = opts.staticDir ?? `/app/${outputDir}`;
+  // The server resolves this path in the container, so a relative one would
+  // depend on the image's WORKDIR.
+  if (!staticDir.startsWith("/")) {
+    throw new Error(`expo(): staticDir ${JSON.stringify(staticDir)} must be an absolute path inside the image`);
+  }
 
-  // Expo inlines EXPO_PUBLIC_* variables into the bundle at `expo export`
-  // time, so they must exist during the image build — runtime container env
-  // is too late. Bake them as ENV lines placed after `npm install` (an env
-  // edit re-exports without re-installing) and before the export RUN. They
-  // remain in `env` too, so server-side reads in the container agree.
-  const publicEnv = Object.entries(opts.env ?? {}).filter(([k]) =>
-    k.startsWith("EXPO_PUBLIC_"),
-  );
-  for (const [k, v] of publicEnv) {
-    if (/[\r\n]/.test(v)) {
-      throw new Error(`expo(): env ${k} must not contain newlines (baked into the Dockerfile)`);
+  let image: ServiceImage;
+  if (opts.dockerfile !== undefined) {
+    // Your own Dockerfile. Everything that describes ours is refused here
+    // rather than ignored, because a setting that does nothing is found only
+    // by the person who reads the built image.
+    const ignored = conflictingOptions(opts);
+    if (ignored.length > 0) {
+      throw new Error(
+        `expo(): ${ignored.join(", ")} ${ignored.length === 1 ? "describes" : "describe"} the Dockerfile expo() writes, ` +
+          `and you gave your own with \`dockerfile\`. Move ${ignored.length === 1 ? "it" : "them"} into ` +
+          `${opts.dockerfile}, and use \`staticDir\` to say where that build writes the web export.`,
+      );
+    }
+    image = {
+      type: "dockerfile",
+      path: opts.dockerfile,
+      context: opts.context ?? appDir,
+      ...(opts.target === undefined ? {} : { target: opts.target }),
+      ...(opts.buildArgs === undefined ? {} : { buildArgs: opts.buildArgs }),
+    };
+  } else {
+    if (opts.context !== undefined) {
+      throw new Error("expo(): `context` names the build context of your own `dockerfile`; the generated one builds from `appDir`");
     }
+    const facts = readAppFacts(appDir);
+    if (facts.pkg === null) {
+      throw new Error(
+        `expo(): no package.json in ${appDir === "." ? "the project root" : appDir}. ` +
+          `Set \`appDir\` to the directory of the Expo app, or build the image with \`dockerfile\`.`,
+      );
+    }
+
+    const node = opts.nodeVersion !== undefined
+      ? { tag: opts.nodeVersion, source: "nodeVersion" }
+      : (declaredNode(facts) ?? { tag: DEFAULT_NODE, source: "the default" });
+    const chosen = opts.packageManager !== undefined
+      ? { pm: opts.packageManager, source: "packageManager option" }
+      : (declaredPackageManager(facts) ?? { pm: "npm" as const, source: "the default" });
+    const plan = installPlan(facts, chosen.pm);
+    console.log(
+      `expo(): node:${node.tag} (${node.source}), ${plan.install} ` +
+        `(${chosen.source}${plan.locked ? "" : ", no lockfile"}).`,
+    );
+
+    image = {
+      type: "dockerfile",
+      content: generateDockerfile({
+        nodeVersion: node.tag,
+        plan,
+        publicEnv: publicEnvLines(opts.env ?? {}),
+        outputDir,
+      }),
+      // The app dir is the context, so the image copies from it directly and
+      // the ignore rules that apply are the app's own. `exclude` gets the
+      // last word over them: a `node_modules` from the host would replace the
+      // one the install made, and the old export would leave dead files
+      // beside the new one.
+      context: appDir,
+      exclude: ["node_modules", "**/node_modules", ".expo", "**/.expo", outputDir],
+      ...(opts.target === undefined ? {} : { target: opts.target }),
+      ...(opts.buildArgs === undefined ? {} : { buildArgs: opts.buildArgs }),
+    };
   }
-  const publicEnvLines = publicEnv
-    .map(([k, v]) => `ENV ${k}="${v.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`)
-    .join("\n");
-
-  // CI=1 keeps `expo export` non-interactive. Static export resolves the web
-  // bundle deterministically into `outputDir`.
-  const dockerfile = `FROM node:${nodeVersion}
-WORKDIR /app
-ENV CI=1
-COPY ${appDir}/ ./
-RUN npm install
-${publicEnvLines ? `${publicEnvLines}\n` : ""}RUN npx expo export --platform web --output-dir ${outputDir}
-`;
 
   return {
-    image: { type: "dockerfile", content: dockerfile },
+    image,
     files: [
       { path: "/spectest-expo-serve.mjs", content: STATIC_SERVER },
     ],
-    command: `node /spectest-expo-serve.mjs /app/${outputDir} ${port}`,
+    command: `node /spectest-expo-serve.mjs ${staticDir} ${port}`,
     env: { ...(opts.env ?? {}) },
     ports: [port],
     readyCheck: { type: "http" as const, port, path: "/", timeoutSecs: 60 },

package/src/components/index.ts

@@ -41,6 +41,7 @@ export {
   expo,
   type ExpoOptions,
   type ExpoHelpers,
+  type ExpoPackageManager,
 } from "./expo.js";
 export {
   supabase,

package/src/harness/main.ts

@@ -40,6 +40,7 @@ import { codeOf } from "./methods";
 import {
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -115,12 +116,11 @@ export function serve(
       //
       // A refusal the method meant to make (an unknown case, a second test
       // while one is running) reports its own kind and just its message. An
-      // unexpected throw is a bug in the method and carries the stack,
-      // which is the only place that information exists.
+      // unexpected throw carries its message AND its stack — in that order,
+      // because a stack alone is sometimes headerless (`describeThrow`).
       const e = err as Error;
       const code = codeOf(err);
-      const detail =
-        code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+      const detail = code === "handler_error" ? describeThrow(err) : e.message;
       send(fail(req.id, detail, code));
     }
   };

package/src/harness/protocol.test.ts

@@ -18,6 +18,7 @@ import {
   KNOWN_METHODS,
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -146,3 +147,44 @@ describe("replies", () => {
     expect(fail("7", "boom", "c")!.error!.code).toBe("c");
   });
 });
+
+describe("describeThrow", () => {
+  test("an ordinary stack, which already opens with the message, is untouched", () => {
+    const err = new Error("docker build for web failed:\nCOPY: not found");
+    expect(describeThrow(err)).toBe(err.stack);
+  });
+
+  /**
+   * The shape this function exists for, produced rather than written by
+   * hand: a promise that rejects while nobody awaits it yet and is
+   * observed a turn later comes back with a headerless stack. That is a
+   * bootstrap image build (`daemon.ts` starts every build at once and a
+   * service awaits its own prep when the DAG reaches it), and the build
+   * log lives in the message it drops.
+   */
+  test("a headerless stack gets its message back", async () => {
+    const message = "docker build for client-app failed:\n#12 ERROR: killed";
+    const rejected = (async () => {
+      throw new Error(message);
+    })();
+    rejected.catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 5));
+    let caught: unknown;
+    try {
+      await rejected;
+    } catch (e) {
+      caught = e;
+    }
+    const described = describeThrow(caught);
+    expect(described).toContain(message);
+    expect(described.startsWith(`Error: ${message}`)).toBe(true);
+    // The frames survive, and the bare `Error` line they hung under does not.
+    expect(described).toContain("    at ");
+    expect(described).not.toContain("\nError\n");
+  });
+
+  test("a non-Error keeps whatever it can say for itself", () => {
+    expect(describeThrow("plain string")).toBe("plain string");
+    expect(describeThrow({ message: "no stack here" })).toBe("Error: no stack here");
+  });
+});

package/src/harness/protocol.ts

@@ -161,3 +161,36 @@ export function ok(id: string, result: Record<string, unknown> = {}): ResponseFr
 export function fail(id: string, message: string, code?: string): ResponseFrame {
   return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
 }
+
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export function describeThrow(err: unknown): string {
+  const e = err as { message?: unknown; stack?: unknown; name?: unknown } | null | undefined;
+  const message = typeof e?.message === "string" ? e.message : "";
+  const stack = typeof e?.stack === "string" ? e.stack : "";
+  if (!message) return stack || String(err);
+  if (stack.includes(message)) return stack;
+  const name = typeof e?.name === "string" && e.name.length > 0 ? e.name : "Error";
+  // The headerless form is `<Name>\n    at …`. Drop that bare first line
+  // and write the header ourselves, so the result reads like the stack a
+  // reader expects rather than a message with a stray `Error` in it.
+  const frames = stack.startsWith(`${name}\n`) ? stack.slice(name.length + 1) : stack;
+  return frames.length > 0 ? `${name}: ${message}\n${frames}` : `${name}: ${message}`;
+}