@juangadm/pre-post 1.1.0 → 1.3.0

package/dist/baseline.js

@@ -11,14 +11,15 @@
  * The cost is time: a checkout, an install and a dev-server boot. So callers
  * reach for it after a reachable deployment, not before one.
  */
-import { spawn, execFileSync } from 'child_process';
+import { spawn, execFile, execFileSync } from 'child_process';
 import fs from 'fs';
 import net from 'net';
 import os from 'os';
 import path from 'path';
+import { NeedsHumanError } from './errors.js';
 import { devScript, readPackage } from './pkg.js';
 import { findAppRoots } from './routes.js';
-const NPM = { bin: 'npm', install: ['install'], run: (s, a) => ['run', s, '--', ...a] };
+const NPM = { bin: 'npm', install: ['install'], retry: { argv: ['install', '--legacy-peer-deps'], when: isPeerConflict }, run: (s, a) => ['run', s, '--', ...a] };
 const PNPM = { bin: 'pnpm', install: ['install', '--prefer-offline'], run: (s, a) => ['run', s, ...a] };
 const YARN = { bin: 'yarn', install: ['install'], run: (s, a) => ['run', s, ...a] };
 const BUN = { bin: 'bun', install: ['install'], run: (s, a) => ['run', s, ...a] };
@@ -114,6 +115,10 @@ export function servableDir(treeRoot, appPrefix) {
     }
     return null;
 }
+/** Has this app directory been installed? */
+function isInstalled(appDir) {
+    return fs.existsSync(path.join(appDir, 'node_modules'));
+}
 /** Local env files, in the order a framework would layer them. */
 const ENV_FILES = ['.env', '.env.local', '.env.development', '.env.development.local'];
 /**
@@ -149,6 +154,90 @@ export function copyEnvFiles(from, to, appPrefix) {
     }
     return copied;
 }
+/**
+ * Prefixes a framework uses to mark a variable as safe to send to the browser.
+ * Stripped before the name is matched, so `NEXT_PUBLIC_APP_URL` and `APP_URL`
+ * are the same question.
+ */
+const PUBLIC_PREFIXES = ['NEXT_PUBLIC_', 'NUXT_PUBLIC_', 'EXPO_PUBLIC_', 'REACT_APP_', 'GATSBY_', 'VITE_', 'PUBLIC_'];
+/**
+ * Names that can only mean "the address this app is served at".
+ *
+ * Deliberately a list and not a pattern: `*_URL` would sweep up
+ * `DATABASE_URL` and an API on a second port, and pointing either of those at
+ * the dev server breaks the app more thoroughly than the wrong port ever did.
+ *
+ * And deliberately a short list. The generic names — `URL`, `BASE_URL`,
+ * `SERVER_URL`, `HOST_URL`, `PUBLIC_URL` — read as the app's own address about
+ * as often as they read as a backend on another port or, for `BASE_URL` under
+ * Vite and `PUBLIC_URL` under CRA, a path prefix that is not a URL at all.
+ * Rewriting one of those is the same class of mistake this fix is about: a
+ * page that renders and is quietly wrong. Every name here is qualified by what
+ * it addresses (`APP_`, `SITE_`, `AUTH_`), which is what makes it answerable.
+ */
+const ORIGIN_KEYS = new Set([
+    'APP_URL', 'APP_ORIGIN', 'APP_BASE_URL',
+    'SITE_URL', 'SITE_ORIGIN',
+    'WEBSITE_URL', 'CANONICAL_URL', 'DEPLOYMENT_URL',
+    'AUTH_URL', 'AUTH_ORIGIN', 'AUTH_BASE_URL', 'NEXTAUTH_URL', 'NEXTAUTH_URL_INTERNAL', 'BETTER_AUTH_URL',
+]);
+/** Does this variable name the app's own origin? */
+export function isOriginKey(key) {
+    const prefix = PUBLIC_PREFIXES.find(p => key.startsWith(p) && key.length > p.length);
+    return ORIGIN_KEYS.has(key) || (prefix ? ORIGIN_KEYS.has(key.slice(prefix.length)) : false);
+}
+/** One env file's text with every origin variable pointed at `origin`. */
+export function rewriteEnvOrigins(text, origin) {
+    const keys = [];
+    const lines = text.split('\n').map(line => {
+        const m = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)(.*)$/.exec(line);
+        if (!m || !isOriginKey(m[2]))
+            return line;
+        keys.push(m[2]);
+        // Keep the quoting the author used; drop whatever followed, because a
+        // trailing comment about the old address is now wrong.
+        const quote = /^["']/.test(m[4]) ? m[4][0] : '';
+        return `${m[1]}${m[2]}${m[3]}${quote}${origin}${quote}`;
+    });
+    return { text: lines.join('\n'), keys };
+}
+/**
+ * Point the worktree's copied env files at the baseline's real origin.
+ *
+ * The copies name the port the developer's own dev server uses, and the
+ * baseline is on an ephemeral one. An app whose auth library is told it lives
+ * at :3000 while it is answering on :51234 rejects its own callbacks: the page
+ * renders, the session never resolves, and every capture is a loading
+ * skeleton. That reads as success — a screenshot came back — which is the
+ * failure mode this whole file exists to avoid.
+ *
+ * Same constraint as the copy: only ever writes inside `dir`, and returns
+ * names, never values.
+ */
+export function pointEnvFilesAt(dir, origin, appPrefix) {
+    const rewritten = new Set();
+    const root = path.resolve(dir);
+    for (const sub of appPrefix ? ['', appPrefix] : ['']) {
+        for (const name of ENV_FILES) {
+            const file = path.resolve(root, sub, name);
+            if (file !== root && !file.startsWith(root + path.sep))
+                continue;
+            try {
+                if (!fs.existsSync(file))
+                    continue;
+                const before = fs.readFileSync(file, 'utf-8');
+                const { text, keys } = rewriteEnvOrigins(before, origin);
+                if (!keys.length || text === before)
+                    continue;
+                fs.writeFileSync(file, text);
+                for (const key of keys)
+                    rewritten.add(key);
+            }
+            catch { /* best effort: the same as a missing env file */ }
+        }
+    }
+    return [...rewritten];
+}
 /** An OS-assigned free port. */
 export function freePort() {
     return new Promise((resolve, reject) => {
@@ -160,6 +249,299 @@ export function freePort() {
         });
     });
 }
+/** Keep the end of the output: managers put the diagnosis last. */
+function tail(text, lines = 24) {
+    const kept = text.replace(/\s+$/, '').split('\n').slice(-lines);
+    return kept.join('\n').trim();
+}
+/**
+ * Room for the noisiest install that still works.
+ *
+ * Node's default is 1 MiB per stream, and exceeding it kills the child with
+ * ENOBUFS — which this code would read as a failed install. A verbose set of
+ * postinstall scripts must not be the reason a baseline cannot be built, and
+ * the buffer is transient and freed as soon as the tail is taken.
+ */
+const MAX_INSTALL_OUTPUT = 64 * 1024 * 1024;
+/**
+ * Run one command to completion, keeping the tail of what it said.
+ *
+ * Shared by the install and the setup step that follows it: they fail the same
+ * way, and a reader needs the same thing from both — the end of the output.
+ */
+function runCommand(bin, argv, cwd, timeoutMs, shell = false, signal) {
+    // Asynchronous, so the other side's server and the browser download keep
+    // moving while this one installs: a synchronous call froze the whole process.
+    return new Promise(resolve => {
+        execFile(bin, argv, { cwd, shell, signal, timeout: Math.max(1, timeoutMs), encoding: 'utf-8', maxBuffer: MAX_INSTALL_OUTPUT }, (err, stdout, stderr) => {
+            // Only a failure has anything to explain, so the successful run's log is
+            // dropped rather than split into lines nothing will read.
+            if (!err)
+                return resolve({ argv, ok: true, output: '' });
+            const output = [stdout, stderr].map(part => (part ? String(part) : '')).join('');
+            resolve({ argv, ok: false, output: tail(output || err.message || '') });
+        }).stdin?.end();
+    });
+}
+const runInstall = (bin, argv, cwd, timeoutMs, signal) => runCommand(bin, argv, cwd, timeoutMs, false, signal);
+/**
+ * Does this look like npm refusing to resolve a peer range?
+ *
+ * Matched on npm's own error code rather than on prose, so it does not depend
+ * on the wording of a given npm release. The second pattern is the same
+ * failure as reported by older npm, which does not always print the code.
+ */
+export function isPeerConflict(output) {
+    return /ERESOLVE/i.test(output) || /could not resolve dependency/i.test(output);
+}
+/**
+ * Install this app's dependencies, retrying once past a peer-dependency wall.
+ *
+ * The retry is deliberately narrow: only on the specific failure that a looser
+ * resolver would not have had, and only for a manager that has a looser mode.
+ * A baseline installed with `--legacy-peer-deps` is not a perfect reproduction
+ * of the branch's own install — but the alternative is no baseline at all, and
+ * the comparison this tool exists to make is between two renders of the same
+ * app, not between two dependency trees.
+ */
+export async function installDeps(pm, cwd, timeoutMs, run = runInstall, signal) {
+    const deadline = Date.now() + timeoutMs;
+    const first = await run(pm.bin, pm.install, cwd, timeoutMs, signal);
+    if (first.ok || signal?.aborted || !pm.retry?.when(first.output))
+        return { ok: first.ok, attempts: [first] };
+    // The remainder of the original budget, not a fresh one: a first attempt
+    // that burned the clock must not let the retry double the wall time.
+    const second = await run(pm.bin, pm.retry.argv, cwd, deadline - Date.now(), signal);
+    return { ok: second.ok, attempts: [first, second] };
+}
+/**
+ * The install failed and nothing else can rescue this run.
+ *
+ * Its own error rather than a quiet null, for the reason docs/portability.md
+ * §1 gives about base resolution: a run that compared nothing must not exit
+ * clean. A null here fell through to "no baseline", and on a repository with a
+ * configured production URL it fell through to comparing against that instead
+ * — a different answer to a different question, published as if it were this
+ * one.
+ */
+/**
+ * What a reader has to do about a failed install, in one sentence.
+ *
+ * One sentence because that is what `NeedsHumanError` is for (AGENTS.md): the
+ * CLI prints the whole message for exit 3, so pasting a screen of package
+ * manager output here would bury the instruction inside it. The output is
+ * still the thing that answers "why", so it goes to the log instead — above
+ * this line, where it reads as diagnostics rather than as the remedy.
+ *
+ * The command names the caller's own directory, never the worktree: by the
+ * time anyone reads this, cleanup has deleted the worktree, so telling them to
+ * run it there would be an instruction they cannot follow.
+ */
+export function installFailureHint(where, ranIn) {
+    return `Could not install ${where} for the baseline; run \`install\` in ${ranIn} to fix it, or re-run with --no-local-baseline and pass --before <production-url>.`;
+}
+export class BaselineInstallError extends NeedsHumanError {
+    result;
+    constructor(result, where, ranIn) {
+        super(installFailureHint(where, ranIn));
+        this.result = result;
+        this.name = 'BaselineInstallError';
+    }
+}
+const TURBO_CONFIGS = ['turbo.json', 'turbo.jsonc'];
+/** A binary the install just put in a `node_modules/.bin`, nearest first. */
+function localBin(name, ...dirs) {
+    const file = process.platform === 'win32' ? `${name}.cmd` : name;
+    for (const dir of dirs) {
+        const bin = path.join(dir, 'node_modules', '.bin', file);
+        if (fs.existsSync(bin))
+            return bin;
+    }
+    return null;
+}
+/**
+ * Build the workspace packages the app imports, before the dev server starts.
+ *
+ * A monorepo app depends on sibling packages that ship compiled output, and a
+ * fresh install does not produce it — `turbo dev` normally would, but the dev
+ * script this file runs is the app's own. So the app boots against a package
+ * with no `dist`, and the baseline is an error page or a shell.
+ *
+ * `^...` is turbo's "dependencies of, excluding itself": the siblings get
+ * built, the app is left to the dev server.
+ */
+export function turboDependencyBuild(treeRoot, appDir) {
+    // A single-package repo has no upstream workspace to build; its dev script
+    // is the whole thing.
+    if (path.resolve(appDir) === path.resolve(treeRoot))
+        return null;
+    if (!TURBO_CONFIGS.some(name => fs.existsSync(path.join(treeRoot, name))))
+        return null;
+    const name = readPackage(appDir)?.name;
+    if (typeof name !== 'string' || !name)
+        return null;
+    const bin = localBin('turbo', appDir, treeRoot);
+    if (!bin)
+        return null;
+    const argv = ['run', 'build', `--filter=${name}^...`];
+    return { label: `turbo ${argv.join(' ')}`, bin, argv, cwd: treeRoot };
+}
+/**
+ * What to run between install and dev: `baselineSetup` if the repository
+ * configured one, else turbo's dependency build when this is a turborepo.
+ *
+ * The configured command wins outright. It is the general answer — one line in
+ * `.pre-post.json` for a repository whose baseline needs a codegen step, a
+ * prisma generate, a build this tool has never heard of — and a repository
+ * that names one has already told us the guess is not wanted.
+ */
+export function setupStep(treeRoot, appDir, configured) {
+    const command = configured?.trim();
+    if (command)
+        return { label: command, bin: command, argv: [], cwd: appDir, shell: true };
+    return turboDependencyBuild(treeRoot, appDir);
+}
+/**
+ * The configured setup command failed, and nothing else can rescue this run.
+ *
+ * One sentence, and the output goes to the log above it, for the reason
+ * `installFailureHint` gives. The directory named is the caller's own, never
+ * the worktree: cleanup has deleted the worktree by the time anyone reads it.
+ */
+export function setupFailureHint(label, ranIn) {
+    return `The \`baselineSetup\` command (\`${label}\`) failed while preparing the baseline; run it in ${ranIn} to fix it, or drop it from .pre-post.json.`;
+}
+export class BaselineSetupError extends NeedsHumanError {
+    constructor(label, ranIn) {
+        super(setupFailureHint(label, ranIn));
+        this.name = 'BaselineSetupError';
+    }
+}
+/**
+ * Files that decide what an install produces. When none of them differ between
+ * the base commit and the working tree, the two installs would be the same
+ * dependency tree, so the one already on disk can stand in for a fresh one.
+ */
+const LOCKFILES = [...MANAGERS.map(m => m.lockfile), 'bun.lock', 'npm-shrinkwrap.json'];
+const INSTALL_INPUTS = [
+    ...LOCKFILES.map(f => `:(glob)**/${f}`),
+    ':(glob)**/package.json',
+    ':(glob)**/.npmrc',
+    ':(glob)**/.yarnrc.yml',
+    ':(glob)**/.pnpmfile.cjs',
+    ':(glob)**/pnpm-workspace.yaml',
+];
+/** Run git without blocking the process; resolves null when it exits non-zero. */
+function gitAsync(args, cwd) {
+    return new Promise(resolve => {
+        execFile('git', args, { cwd, encoding: 'utf-8', maxBuffer: MAX_INSTALL_OUTPUT }, (err, stdout) => resolve(err ? null : stdout));
+    });
+}
+/**
+ * Can the base commit use the dependencies this checkout already installed?
+ *
+ * Only when no install input differs between the base and the working tree,
+ * uncommitted edits included, and a lockfile is tracked (without one there is
+ * nothing to prove the trees match). Returns the package directories whose
+ * node_modules to bring across, or null to install as usual. Once the diff is
+ * clean, the index lists the same package.json files the base has, so it
+ * answers that without walking the base commit's whole tree.
+ */
+export async function reusableInstall(repoRoot, sha) {
+    if (await gitAsync(['diff', '--quiet', sha, '--', ...INSTALL_INPUTS], repoRoot) === null)
+        return null;
+    // The diff sees tracked files only. A new package.json or lockfile the
+    // branch has not added yet is still a different dependency tree.
+    const untracked = await gitAsync(['ls-files', '--others', '--exclude-standard', '--', ...INSTALL_INPUTS], repoRoot);
+    if (untracked === null || untracked.trim())
+        return null;
+    const tracked = await gitAsync(['ls-files', '--', ...INSTALL_INPUTS], repoRoot);
+    const files = tracked?.split('\n') ?? [];
+    if (!files.some(f => LOCKFILES.includes(path.basename(f))))
+        return null;
+    const dirs = files
+        .filter(f => path.basename(f) === 'package.json' && !f.split('/').includes('node_modules'))
+        .map(f => path.dirname(f));
+    if (dirs.some(dir => generatesDuringInstall(path.join(repoRoot, dir))))
+        return null;
+    return dirs.filter(dir => {
+        try {
+            return fs.lstatSync(path.join(repoRoot, dir, 'node_modules')).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Scripts a package manager runs on the project itself during an install. */
+const INSTALL_HOOKS = ['preinstall', 'install', 'postinstall', 'prepare'];
+/**
+ * Could this package's install have written code built from its own source?
+ *
+ * An install hook can read files no install input covers — `prisma generate`
+ * reads a schema — and write the result into node_modules. Copying that into
+ * the baseline would render Pre with the branch's generated code, so such a
+ * package is installed fresh. Prisma is checked by its output as well, because
+ * `@prisma/client` generates from its own postinstall with no project hook.
+ */
+function generatesDuringInstall(dir) {
+    const scripts = readPackage(dir)?.scripts ?? {};
+    if (INSTALL_HOOKS.some(hook => typeof scripts[hook] === 'string' && scripts[hook].trim()))
+        return true;
+    return fs.existsSync(path.join(dir, 'node_modules', '.prisma'));
+}
+const COPY_CONCURRENCY = 6;
+/**
+ * Installs running in a caller's own checkout, by repository root. The base
+ * worktree waits on these before reusing that checkout's node_modules, which
+ * lets both sides boot at once even when nothing was installed yet.
+ */
+const installsInFlight = new Map();
+/**
+ * Copy one node_modules into the worktree as its own tree.
+ *
+ * A copy, not a symlink: package managers link workspace packages with
+ * relative paths, and through a symlink those would resolve back into this
+ * checkout, so Pre would quietly render the branch's own workspace code.
+ * Turbopack also refuses a node_modules that points outside the project. The
+ * copy keeps those links relative, so they land in the worktree. On macOS
+ * (APFS) and on reflink filesystems it is copy-on-write: near-instant and no
+ * extra disk.
+ */
+function copyTree(from, to) {
+    const argv = process.platform === 'darwin' ? ['-c', '-R', from, to] : ['-a', '--reflink=auto', from, to];
+    return new Promise(resolve => {
+        execFile('cp', argv, { maxBuffer: MAX_INSTALL_OUTPUT }, err => {
+            if (!err)
+                return resolve(true);
+            // A cp without the clone flag (older macOS, BSD): Node's own copy.
+            fs.promises.rm(to, { recursive: true, force: true })
+                .then(() => fs.promises.cp(from, to, { recursive: true, verbatimSymlinks: true }))
+                .then(() => resolve(true), () => fs.promises.rm(to, { recursive: true, force: true }).then(() => resolve(false)));
+        });
+    });
+}
+/**
+ * Bring this checkout's installed dependencies into the base worktree.
+ * True when every one was copied; on any failure the partial copies are
+ * removed so the normal install starts from a clean tree.
+ */
+export async function reuseInstall(repoRoot, worktree, dirs) {
+    const targets = dirs.map(dir => ({ from: path.join(repoRoot, dir, 'node_modules'), to: path.join(worktree, dir, 'node_modules') }));
+    // A few at a time: a monorepo can have hundreds of packages, and hundreds of
+    // concurrent copies thrash the disk the dev servers are reading from.
+    const queue = [...targets];
+    let ok = true;
+    const worker = async () => {
+        for (let t = queue.shift(); t && ok; t = queue.shift())
+            ok = await copyTree(t.from, t.to) && ok;
+    };
+    await Promise.all(Array.from({ length: Math.min(COPY_CONCURRENCY, targets.length) }, worker));
+    if (ok)
+        return true;
+    await Promise.all(targets.map(t => fs.promises.rm(t.to, { recursive: true, force: true })));
+    return false;
+}
 async function waitForServer(url, timeoutMs, alive) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -206,6 +588,16 @@ async function serveLocally(opts) {
     };
     const timeoutMs = opts.timeoutMs ?? 300_000;
     const deadline = Date.now() + timeoutMs;
+    /** True, having cleaned up, when the caller has given up on this side. */
+    const aborted = async () => {
+        if (!opts.signal?.aborted)
+            return false;
+        await cleanup();
+        return true;
+    };
+    const side = opts.sha ? 'pre' : 'post';
+    const timed = (name, work) => opts.timings ? opts.timings.time(`${side}.${name}`, work) : work;
+    const started = Date.now();
     const worktree = opts.sha ? fs.mkdtempSync(path.join(os.tmpdir(), 'pre-post-base-')) : opts.repoRoot;
     let child = null;
     let stopped = false;
@@ -241,16 +633,16 @@ async function serveLocally(opts) {
         }
     };
     if (opts.sha) {
-        try {
-            execFileSync('git', ['worktree', 'add', '--detach', '--force', worktree, opts.sha], { cwd: opts.repoRoot, stdio: 'ignore' });
-        }
-        catch {
+        // Asynchronous: in a large repository a checkout takes seconds, and the
+        // other side is booting meanwhile.
+        if (await gitAsync(['worktree', 'add', '--detach', '--force', worktree, opts.sha], opts.repoRoot) === null || await aborted()) {
             await cleanup();
             return skip('the worktree checkout failed.');
         }
         const copied = copyEnvFiles(opts.repoRoot, worktree, opts.appPrefix);
         if (copied.length)
             log(`Using local env file(s) for the baseline: ${copied.join(', ')}`);
+        opts.timings?.add(`${side}.checkout`, Date.now() - started);
     }
     const app = servableDir(worktree, opts.appPrefix);
     if (!app) {
@@ -269,7 +661,7 @@ async function serveLocally(opts) {
         await cleanup();
         return skip(`neither ${declared.bin} nor npm is on PATH, so nothing can install ${where}.`);
     }
-    const install = !fs.existsSync(path.join(appDir, 'node_modules'));
+    const install = !isInstalled(appDir);
     // Substituting npm for the declared manager is safe in a throwaway worktree
     // and not in the caller's own checkout: npm cannot share a node_modules with
     // pnpm, so installing over their tree leaves the working copy broken — the
@@ -281,21 +673,89 @@ async function serveLocally(opts) {
         await cleanup();
         return skip(`${declared.bin} is not on PATH, and installing ${where} with npm instead would leave a node_modules your ${declared.bin} cannot use. Install ${declared.bin}, or run \`${declared.bin} install\` in ${appIn}.`);
     }
-    if (pm !== declared) {
-        log(`${declared.bin} is not on PATH; installing the baseline with ${pm.bin} instead (it will not honour the ${declared.bin} lockfile).`);
-    }
     log(`Starting a dev server for ${what} (${pm.bin} ${script}) ...`);
-    if (install) {
-        try {
-            execFileSync(pm.bin, pm.install, { cwd: appDir, stdio: 'ignore', timeout: Math.max(1, deadline - Date.now()) });
+    // The slowest step of a first run, and usually one that would rebuild the
+    // exact tree already on disk: most branches change code, not dependencies.
+    const tryReuse = async (sha) => {
+        // Post may be installing this checkout right now; a half-written
+        // node_modules must never be copied, so wait for it to finish.
+        await installsInFlight.get(opts.repoRoot);
+        const dirs = await reusableInstall(opts.repoRoot, sha);
+        if (!dirs?.includes(rel || '.') || !await reuseInstall(opts.repoRoot, worktree, dirs))
+            return false;
+        log(`Dependencies are unchanged since ${sha.slice(0, 7)}; reusing this checkout's install for the baseline.`);
+        return true;
+    };
+    const reused = install && opts.sha ? await timed('reuse', tryReuse(opts.sha)) : false;
+    if (await aborted())
+        return null;
+    if (install && !reused) {
+        if (pm !== declared) {
+            log(`${declared.bin} is not on PATH; installing the baseline with ${pm.bin} instead (it will not honour the ${declared.bin} lockfile).`);
         }
-        catch {
+        const installing = installDeps(pm, appDir, deadline - Date.now(), runInstall, opts.signal);
+        if (worktree === opts.repoRoot)
+            installsInFlight.set(opts.repoRoot, installing);
+        const result = await timed('install', installing).finally(() => installsInFlight.delete(opts.repoRoot));
+        if (await aborted())
+            return null;
+        if (!result.ok) {
+            const tried = result.attempts.map(a => `\`${pm.bin} ${a.argv.join(' ')}\``).join(', then ');
+            log(`${tried} failed${worktree === opts.repoRoot ? '' : ' in a throwaway worktree of the base commit'}:`);
+            log(result.attempts[result.attempts.length - 1].output);
             await cleanup();
-            return skip(`\`${pm.bin} ${pm.install.join(' ')}\` failed. Run it in ${appIn} to see why.`);
+            throw new BaselineInstallError(result, where, appIn);
+        }
+        const retried = result.attempts[1];
+        if (retried) {
+            log(`\`${pm.bin} ${pm.install.join(' ')}\` hit a peer-dependency conflict; installed the baseline with \`${retried.argv.join(' ')}\` instead.`);
         }
     }
+    // Before the setup step, not after it: that step is a build, and a build that
+    // reads NEXT_PUBLIC_APP_URL bakes whatever the file says into its output.
+    // Rewriting afterwards would leave the compiled copy holding the old port —
+    // the same mismatch, now somewhere no later rewrite can reach. The cost is
+    // that the port is claimed across the build rather than a moment before the
+    // spawn; if something else takes it meanwhile, the server fails to bind and
+    // this run says so, which is the failure worth having.
     const port = await freePort();
     const url = `http://localhost:${port}`;
+    // Only the throwaway worktree's copies may be edited; the caller's own env
+    // files are theirs.
+    if (worktree !== opts.repoRoot) {
+        const pointed = pointEnvFilesAt(worktree, url, opts.appPrefix);
+        if (pointed.length)
+            log(`Pointed ${pointed.join(', ')} at ${url} so the baseline agrees with its own address.`);
+    }
+    // The inferred build follows a fresh install and nothing else: a tree that
+    // already had node_modules has its workspace packages built too, and running
+    // a repo-wide build over someone's own checkout to take a screenshot is not
+    // a trade this tool gets to make. A configured command is different — the
+    // repository asked for it, so it runs either way.
+    const configured = Boolean(opts.setup?.trim());
+    const setup = configured ? setupStep(worktree, appDir, opts.setup) : install ? setupStep(worktree, appDir) : null;
+    if (setup) {
+        log(`Preparing ${what} before its dev server (${setup.label}) ...`);
+        const attempt = await timed('setup', runCommand(setup.bin, setup.argv, setup.cwd, deadline - Date.now(), setup.shell, opts.signal));
+        if (await aborted())
+            return null;
+        if (!attempt.ok) {
+            // Loud either way. A dev server started over a half-built workspace
+            // serves an error page, and an error page is a baseline that reports a
+            // wall of changes this branch never made.
+            log(attempt.output);
+            await cleanup();
+            // A command the repository asked for is the install's case exactly
+            // (docs/portability.md §1): yielding here lets the run fall through to a
+            // configured production URL and publish a different comparison as if it
+            // were this one, or die further along on an error about dev servers that
+            // names nothing the reader can fix. Only the inferred build yields —
+            // nobody asked for it, so it is allowed to be one option among several.
+            if (configured)
+                throw new BaselineSetupError(setup.label, appIn);
+            return skip(`\`${setup.label}\` failed.`);
+        }
+    }
     child = spawn(pm.bin, pm.run(script, ['--port', String(port)]), {
         cwd: appDir,
         stdio: 'ignore',
@@ -303,9 +763,18 @@ async function serveLocally(opts) {
         env: { ...process.env, PORT: String(port), BROWSER: 'none' },
     });
     child.unref();
-    const ready = await waitForServer(url, Math.max(1, deadline - Date.now()), () => !!child && child.exitCode === null);
+    const ready = await timed('boot', waitForServer(url, Math.max(1, deadline - Date.now()), () => !!child && child.exitCode === null && !opts.signal?.aborted));
+    if (await aborted())
+        return null;
     if (!ready) {
+        // A server that died is not one that was slow. Reporting "did not start
+        // within 300s" about one that exited after two seconds, as a CI run did,
+        // sends the reader to look at timeouts instead of at the crash.
+        const exitCode = child?.exitCode ?? null;
         await cleanup();
+        if (exitCode !== null) {
+            return skip(`${pm.bin} ${script} exited with code ${exitCode} before serving; run it in ${appIn} to see why.`);
+        }
         return skip(`${pm.bin} ${script} did not start serving within ${Math.round(timeoutMs / 1000)}s (missing env vars are the usual cause).`);
     }
     process.once('SIGINT', onSignal);