@specific.dev/spectest 0.78.0 → 0.79.0

package/dist/components/expo.d.ts

@@ -1,17 +1,65 @@
 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 —
@@ -29,6 +77,15 @@ export interface ExpoOptions {
 }
 /** The handle `expo()` exposes on `ctx.svc.<name>` — a {@link MobileApp}. */
 export type ExpoHelpers = MobileApp;
+/**
+ * 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 declare function nodeMajorFromRange(range: string): number | null;
 /**
  * A ready-to-use Expo (web) service. Drop into `environment.services` and
  * drive it with `ctx.mobile`:
@@ -45,8 +102,21 @@ export type ExpoHelpers = MobileApp;
  */
 export declare function expo(opts?: ExpoOptions): {
     image: {
+        type: "dockerfile";
+        path: string;
+        content?: never;
+        context?: string;
+        exclude?: readonly string[];
+        target?: string;
+        buildArgs?: Readonly<Record<string, string>>;
+    } | {
         type: "dockerfile";
         content: string;
+        path?: never;
+        context?: string;
+        exclude?: readonly string[];
+        target?: string;
+        buildArgs?: Readonly<Record<string, string>>;
     };
     files: {
         path: string;

package/dist/components/expo.js

@@ -2,20 +2,42 @@
 // 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 { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { mobileApp } from "../mobile.js";
 // 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";
@@ -35,6 +57,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" });
@@ -61,6 +95,236 @@ 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() {
+    return process.env.SPECTEST_WORKSPACE ?? "/workspace";
+}
+function readAppFacts(appDir) {
+    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) => existsSync(join(dir, name));
+    let pkg = null;
+    if (has("package.json")) {
+        try {
+            pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        }
+        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, name) {
+    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) {
+    // 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) {
+    const engines = facts.pkg?.engines;
+    const candidates = [
+        ["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 = {
+    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) {
+    // `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];
+        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"]) {
+        const found = LOCKFILES[pm].find((f) => facts.has(f));
+        if (found !== undefined)
+            return { pm, source: found };
+    }
+    return null;
+}
+/**
+ * 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, pm) {
+    const lock = LOCKFILES[pm].find((f) => facts.has(f));
+    const shared = ["package.json", ...(lock === undefined ? [] : [lock])];
+    const optional = (names) => 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) {
+    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) {
+    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) {
+    const named = [];
+    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`:
@@ -78,37 +342,75 @@ createServer(async (req, res) => {
 export function expo(opts = {}) {
     const port = opts.port ?? 8081;
     const appDir = opts.appDir ?? ".";
-    const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
     const outputDir = opts.outputDir ?? "dist";
-    // 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)`);
+    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`);
+    }
+    let image;
+    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", 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", port, path: "/", timeoutSecs: 60 },

package/dist/components/index.d.ts

@@ -2,7 +2,7 @@ export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgre
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";
 export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export { k3s, type K3sOptions, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
-export { expo, type ExpoOptions, type ExpoHelpers, } from "./expo.js";
+export { expo, type ExpoOptions, type ExpoHelpers, type ExpoPackageManager, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";
 export { aws, type AwsOptions, type LambdaOptions, } from "./aws.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/expo.test.ts

@@ -0,0 +1,227 @@
+// What `expo()` builds from a real app directory: which package manager it
+// installs with, which Node it builds on, and the order of the Dockerfile
+// steps. The order is what makes a source edit cheap, so it is the part a
+// test has to hold: an install that moves below the source COPY runs again
+// on every edit, and nothing about the environment looks wrong when it does.
+
+import { afterEach, afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { expo, nodeMajorFromRange } from "./expo.js";
+import type { ServiceConfig } from "../index.js";
+
+let root = "";
+const prevWorkspace = process.env.SPECTEST_WORKSPACE;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "expo-app-"));
+  process.env.SPECTEST_WORKSPACE = root;
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+afterAll(() => {
+  if (prevWorkspace === undefined) delete process.env.SPECTEST_WORKSPACE;
+  else process.env.SPECTEST_WORKSPACE = prevWorkspace;
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Write an app into the workspace. `files` is path → content. */
+function app(files: Record<string, string>, dir = "."): void {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(root, dir, rel);
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, content);
+  }
+}
+
+const pkg = (extra: Record<string, unknown> = {}): string =>
+  JSON.stringify({ name: "app", dependencies: { expo: "51.0.0" }, ...extra });
+
+/** The generated Dockerfile of a service. */
+function dockerfile(svc: ServiceConfig): string {
+  const image = svc.image as { content?: string };
+  if (image.content === undefined) throw new Error("service does not build a generated Dockerfile");
+  return image.content;
+}
+
+/** Line index of the first line that holds `needle`. */
+function lineOf(text: string, needle: string): number {
+  const i = text.split("\n").findIndex((l) => l.includes(needle));
+  if (i < 0) throw new Error(`no line with ${needle} in:\n${text}`);
+  return i;
+}
+
+describe("expo() Dockerfile caching", () => {
+  test("installs from the manifests before it copies the source", () => {
+    app({ "package.json": pkg(), "package-lock.json": "{}", "App.js": "x" });
+    const df = dockerfile(expo());
+
+    // The manifests, the install, then everything else. An edit to App.js
+    // invalidates only the last two steps.
+    expect(lineOf(df, "COPY package.json package-lock.json ./")).toBeLessThan(lineOf(df, "npm ci"));
+    expect(lineOf(df, "npm ci")).toBeLessThan(lineOf(df, "COPY . ."));
+    expect(lineOf(df, "COPY . .")).toBeLessThan(lineOf(df, "expo export"));
+  });
+
+  test("keeps the package store and the Metro cache across builds", () => {
+    app({ "package.json": pkg(), "package-lock.json": "{}" });
+    const df = dockerfile(expo());
+
+    expect(df).toContain("RUN --mount=type=cache,target=/root/.npm,sharing=locked npm ci");
+    expect(df).toContain("--mount=type=cache,target=/tmp/metro-cache");
+  });
+
+  test("bakes EXPO_PUBLIC_* after the source, so an edit to one only exports again", () => {
+    app({ "package.json": pkg(), "package-lock.json": "{}" });
+    const df = dockerfile(expo({ env: { EXPO_PUBLIC_API: "https://api.test", OTHER: "no" } }));
+
+    expect(lineOf(df, "npm ci")).toBeLessThan(lineOf(df, "ENV EXPO_PUBLIC_API"));
+    expect(lineOf(df, "ENV EXPO_PUBLIC_API")).toBeLessThan(lineOf(df, "expo export"));
+    // Only the public ones are baked; the rest are container env.
+    expect(df).not.toContain("OTHER");
+  });
+
+  test("copies patches, because the install applies them", () => {
+    app({
+      "package.json": pkg(),
+      "package-lock.json": "{}",
+      "patches/expo+51.0.0.patch": "diff",
+    });
+    expect(dockerfile(expo())).toContain("COPY package.json package-lock.json patches ./");
+  });
+
+  test("holds the host's node_modules and the old export out of the context", () => {
+    app({ "package.json": pkg() });
+    const image = expo().image as { context?: string; exclude?: readonly string[] };
+    expect(image.context).toBe(".");
+    expect(image.exclude).toContain("node_modules");
+    expect(image.exclude).toContain("dist");
+  });
+});
+
+describe("expo() package manager", () => {
+  test("npm installs from the lockfile, and without one it resolves", () => {
+    app({ "package.json": pkg(), "package-lock.json": "{}" });
+    expect(dockerfile(expo())).toContain("npm ci");
+
+    rmSync(join(root, "package-lock.json"));
+    expect(dockerfile(expo())).toContain("npm install");
+  });
+
+  test("pnpm comes from its lockfile, with Corepack and its own store", () => {
+    app({ "package.json": pkg(), "pnpm-lock.yaml": "lockfileVersion: 9" });
+    const df = dockerfile(expo());
+
+    expect(df).toContain("RUN corepack enable pnpm");
+    expect(df).toContain("pnpm install --store-dir /pnpm-store --frozen-lockfile");
+    expect(df).toContain("pnpm exec expo export");
+  });
+
+  test("yarn 1 uses the image's own yarn; yarn 2+ is a Corepack release", () => {
+    app({ "package.json": pkg(), "yarn.lock": "" });
+    const classic = dockerfile(expo());
+    expect(classic).toContain("yarn install --cache-folder /yarn-cache --frozen-lockfile");
+    expect(classic).not.toContain("corepack");
+
+    app({ "package.json": pkg({ packageManager: "yarn@4.5.0" }), ".yarnrc.yml": "nodeLinker: node-modules" });
+    const berry = dockerfile(expo());
+    expect(berry).toContain("corepack enable yarn");
+    expect(berry).toContain("yarn install --immutable");
+    expect(berry).toContain("ENV YARN_ENABLE_GLOBAL_CACHE=1");
+  });
+
+  test("bun is installed into the Node image", () => {
+    app({ "package.json": pkg(), "bun.lock": "" });
+    const df = dockerfile(expo());
+    expect(df).toContain("RUN npm install -g bun");
+    expect(df).toContain("bun install --frozen-lockfile");
+    expect(df).toContain("bunx expo export");
+  });
+
+  test("the packageManager field wins over a stray lockfile", () => {
+    app({ "package.json": pkg({ packageManager: "pnpm@9.1.0" }), "package-lock.json": "{}" });
+    expect(dockerfile(expo())).toContain("pnpm install");
+  });
+
+  test("the option wins over both", () => {
+    app({ "package.json": pkg(), "package-lock.json": "{}" });
+    expect(dockerfile(expo({ packageManager: "yarn" }))).toContain("yarn install");
+  });
+});
+
+describe("expo() Node version", () => {
+  test("takes the version the app declares", () => {
+    app({ "package.json": pkg({ engines: { node: ">=22" } }) });
+    expect(dockerfile(expo())).toContain("FROM node:22-bookworm-slim");
+
+    app({ "package.json": pkg(), ".nvmrc": "v20.11.1\n" });
+    expect(dockerfile(expo())).toContain("FROM node:20-bookworm-slim");
+  });
+
+  test("builds on 22 when the app declares nothing readable", () => {
+    app({ "package.json": pkg(), ".nvmrc": "lts/iron\n" });
+    expect(dockerfile(expo())).toContain("FROM node:22-bookworm-slim");
+  });
+
+  test("the option wins", () => {
+    app({ "package.json": pkg({ engines: { node: ">=22" } }) });
+    expect(dockerfile(expo({ nodeVersion: "20-alpine" }))).toContain("FROM node:20-alpine");
+  });
+
+  test("a range names what to build on, not what to avoid", () => {
+    // An upper bound says which version must NOT run, so it is not a choice.
+    expect(nodeMajorFromRange(">=18 <21")).toBe(18);
+    expect(nodeMajorFromRange("18 || 20 || 22")).toBe(22);
+    expect(nodeMajorFromRange("^20.9.0")).toBe(20);
+    // One version is one token — its first number is the major.
+    expect(nodeMajorFromRange("18.20.4")).toBe(18);
+    expect(nodeMajorFromRange("22.x")).toBe(22);
+    expect(nodeMajorFromRange("lts/*")).toBeNull();
+  });
+});
+
+describe("expo() with your own Dockerfile", () => {
+  test("builds the repo file from the app dir, and serves the documented path", () => {
+    app({ "package.json": pkg(), "Dockerfile": "FROM node:22\n" }, "mobile");
+    const svc = expo({ appDir: "mobile", dockerfile: "mobile/Dockerfile" });
+
+    expect(svc.image).toEqual({ type: "dockerfile", path: "mobile/Dockerfile", context: "mobile" });
+    expect(svc.command).toContain("/app/dist");
+  });
+
+  test("staticDir says where that build wrote the export", () => {
+    app({ "package.json": pkg(), "Dockerfile": "FROM nginx\n" });
+    const svc = expo({ dockerfile: "Dockerfile", staticDir: "/srv/web" });
+    expect(svc.command).toBe("node /spectest-expo-serve.mjs /srv/web 8081");
+  });
+
+  test("refuses a staticDir that depends on the image's WORKDIR", () => {
+    app({ "package.json": pkg(), "Dockerfile": "FROM nginx\n" });
+    expect(() => expo({ dockerfile: "Dockerfile", staticDir: "web" })).toThrow(/absolute path/);
+  });
+
+  test("refuses the options that describe the generated Dockerfile", () => {
+    app({ "package.json": pkg(), "Dockerfile": "FROM node:22\n" });
+    expect(() => expo({ dockerfile: "Dockerfile", nodeVersion: "22-alpine" })).toThrow(/nodeVersion/);
+    expect(() => expo({ dockerfile: "Dockerfile", env: { EXPO_PUBLIC_API: "x" } })).toThrow(/EXPO_PUBLIC/);
+    // `env` that Expo does not inline is the container's, and stays allowed.
+    expect(expo({ dockerfile: "Dockerfile", env: { API: "x" } }).env).toEqual({ API: "x" });
+  });
+
+  test("the static server stops on an image with no export in it", () => {
+    app({ "package.json": pkg() });
+    const server = expo().files!.find((f) => f.path.endsWith(".mjs"))!.content;
+    expect(server).toContain("holds no index.html");
+    expect(server).toContain("process.exit(1)");
+  });
+});
+
+describe("expo() app directory", () => {
+  test("names the directory when there is no app in it", () => {
+    app({ "package.json": pkg() });
+    expect(() => expo({ appDir: "mobile" })).toThrow(/appDir "mobile" is not in the project/);
+    app({ "readme.md": "x" }, "mobile");
+    expect(() => expo({ appDir: "mobile" })).toThrow(/no package.json in mobile/);
+  });
+});

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,