@specific.dev/spectest 0.77.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/dist/components/s3.d.ts

@@ -1,7 +1,5 @@
 import { type S3ClientLike } from "../s3.js";
 export interface S3Options {
-    /** HTTP port the S3 API is served on. Default `9090`. */
-    port?: number;
     /**
      * Buckets to create on first boot. The backing server's own `initialBuckets`
      * env is unreliable across versions, so the component creates them in `setup`
@@ -17,7 +15,7 @@ export interface S3Options {
     /**
      * Hostnames to additionally serve the store at over **HTTPS** (CA-trusted),
      * via the daemon's TLS-terminating reverse proxy. Optional — defaults to none;
-     * the store is always reachable at `http://<key>:<port>` regardless. Set this
+     * the store is always reachable at `http://<key>:9090` regardless. Set this
      * only when the app under test hardcodes a specific prod S3 endpoint it can't
      * be told to override (`https://<bucket>.s3.amazonaws.com`, a provider's
      * storage host): the daemon mints a cert for each host and proxies to the

package/dist/components/s3.js

@@ -3,6 +3,15 @@ import { S3Client } from "../s3.js";
 // is the current release; avoid exactly 5.0.0, which crashed at startup on
 // Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
 const S3_IMAGE = "adobe/s3mock:5.1.0";
+// Port the store listens on, fixed like the image and deliberately NOT an
+// option. The backing server's HTTP port is baked into the image, and nothing
+// the component returns can move it — so a `port` option could only relabel
+// the ready check, the declared ports and the client endpoint while the
+// container kept listening here. That is exactly what it did until 0.78.0: a
+// project that passed one got 60 s of refused probes and an environment that
+// never booted, with a healthy container beside it. A service reaches the
+// store at `http://<key>:9090`.
+const S3_PORT = 9090;
 /**
  * A ready-to-use, S3-compatible object store (backed by
  * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
@@ -35,7 +44,6 @@ const S3_IMAGE = "adobe/s3mock:5.1.0";
  * ```
  */
 export function s3(opts = {}) {
-    const port = opts.port ?? 9090;
     const buckets = opts.buckets ?? [];
     const defaultBucket = opts.bucket ?? buckets[0];
     const accessKeyId = opts.accessKeyId ?? "s3";
@@ -43,16 +51,16 @@ export function s3(opts = {}) {
     const region = opts.region ?? "us-east-1";
     return {
         image: { type: "registry", reference: S3_IMAGE },
-        ports: [port],
+        ports: [S3_PORT],
         ...(opts.env ? { env: opts.env } : {}),
         ...(opts.hosts
-            ? { tls: opts.hosts.map((hostname) => ({ hostname, port })) }
+            ? { tls: opts.hosts.map((hostname) => ({ hostname, port: S3_PORT })) }
             : {}),
         // GET / returns the ListBuckets XML with 200 once the store is up.
-        readyCheck: { type: "http", port, path: "/", timeoutSecs: 60 },
+        readyCheck: { type: "http", port: S3_PORT, path: "/", timeoutSecs: 60 },
         helpers: ({ name }) => ({
             client: new S3Client({
-                endpoint: `http://${name}:${port}`,
+                endpoint: `http://${name}:${S3_PORT}`,
                 region,
                 accessKeyId,
                 secretAccessKey,
@@ -67,7 +75,7 @@ export function s3(opts = {}) {
                         // CreateBucket is a plain `PUT` on the bucket root; the store
                         // returns 200 (or 409 if it already exists — idempotent enough to
                         // ignore).
-                        const res = await fetch(`http://${name}:${port}/${bucket}`, {
+                        const res = await fetch(`http://${name}:${S3_PORT}/${bucket}`, {
                             method: "PUT",
                         });
                         if (!res.ok && res.status !== 409) {

package/package.json

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