cdk-nextjs 0.6.2 → 0.7.1

package/scripts/e2e-harness/screen.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * Screen vercel/next.js's e2e suite for harness candidates, and keep the
+ * `screening` block in `test/deploy-tests-manifest.json` honest.
+ *
+ *   node scripts/e2e-harness/screen.mjs --next ../next.js            # print the funnel
+ *   node scripts/e2e-harness/screen.mjs --next ../next.js --check    # fail if stale
+ *   node scripts/e2e-harness/screen.mjs --next ../next.js --write    # update the manifest
+ *   node scripts/e2e-harness/screen.mjs --next ../next.js --list cache
+ *
+ * Why this exists rather than a number typed into a doc: the funnel moves every
+ * time next.js is upgraded, and a stale count is indistinguishable from a
+ * measured one. `--check` is what makes the recorded overview trustworthy.
+ *
+ * The disqualifying screens are the ones in this directory's README, in the
+ * order that costs least to apply:
+ *
+ * - **edge / middleware** — cdk-nextjs throws during `next build` for any
+ *   non-`nodejs` runtime (`assertNodeRuntimes`), so the fixture is unbuildable
+ *   and no per-case `failed` entry can rescue it.
+ * - **skipped-upstream** — `describe.skip`, so the file reports "passing" in
+ *   seconds without deploying anything. Adding it claims coverage that does not
+ *   exist. This one over-reports, because the match is textual and some skips are
+ *   conditional: `incremental-cache-path-traversal` writes
+ *   `(process.env.__NEXT_CACHE_COMPONENTS ? describe.skip : describe)`, which the
+ *   harness does not set, so the file does run and did find a real defect. A file
+ *   disqualified only by this screen is worth re-reading before it is dismissed.
+ * - **skipDeployment** — the same trap, spelled in the `nextTestSetup` call:
+ *   next.js replaces the whole file with `it.only('should skip next deploy')`.
+ *   The costliest screen to have been missing — it covers 236 of what were
+ *   otherwise counted as candidates, and two files had already been added to
+ *   `rules.include` on the strength of a 4s "pass".
+ * - **mode-gated** — the third spelling of the same trap, and the one that cost a
+ *   deploy slot to find: the file's real cases sit inside `if (isNextStart)` or
+ *   `if (isNextDev)`, and every other mode gets an empty
+ *   `it('should skip …', () => {})`. `app-fetch-deduping` reported a pass in 5.9s
+ *   having deployed nothing. A stub whose title names *dev* is the opposite case
+ *   — the file runs everywhere but dev, `app-prefetch-static` being one — so
+ *   those are left in.
+ * - **isNextDeploy-gate** — usually next.js itself gating out what cannot work
+ *   behind a CDN. Not always disqualifying; read the gate before dismissing it.
+ * - **output-export** — a static export is not what any `NextjsType` deploys.
+ * - **scaffold** — `test-template/{{ toFileName name }}`, a `pnpm new-test`
+ *   template rather than a test.
+ * - **verdict** — the file already has a written verdict in the manifest's
+ *   `excluded-notes`, so it has been deployed (or read) and deliberately left out.
+ *   Without this screen a decided file stays a candidate forever and gets picked
+ *   for another batch, which is how the `next-config-ts-native-ts` family would
+ *   have burned 18 deploy slots twice.
+ *
+
+ * "Clean" means only that none of those apply. It is a candidate list, not a
+ * prediction: a clean file still has to be deployed and watched before it goes
+ * into `rules.include`.
+ */
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const MANIFEST = join(repoRoot, "test", "deploy-tests-manifest.json");
+const TEST_ROOT = "test/e2e";
+const SOURCE_RE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const TEST_RE = /\.test\.[tj]sx?$/;
+/**
+ * Both spellings that pin a route to the edge runtime: app router's
+ * `export const runtime = 'edge'` and pages router's
+ * `export const config = { runtime: 'experimental-edge' }`. Matching only the
+ * first undercounts by ~17 files.
+ */
+const EDGE_RUNTIME_RE = /runtime\s*[:=]\s*['"](experimental-)?edge['"]/;
+/**
+ * An empty `it('should skip …', () => {})` — next.js's stub for the modes a
+ * mode-gated file does not cover. `dev` in the title means dev is the excluded
+ * mode and deploy is not, so those are deliberately not matched.
+ */
+const MODE_GATED_STUB_RE =
+  /it\(\s*(['"`])should skip (?!.*\bdev\b)[^'"`]*\1\s*,\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/;
+
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(`--${name}`);
+const value = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+
+const nextDir = resolve(value("next") ?? join(repoRoot, "..", "next.js"));
+
+/** Every file under `dir`, skipping build output. */
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walk(path, out);
+    else out.push(path);
+  }
+  return out;
+}
+
+const read = (path) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+/**
+ * The test file's text, plus the text of every sibling module it pulls in with a
+ * relative `import`/`require`, two levels deep. `nextTestSetup` is not always
+ * called in the test file: `app-dir/cache-components-errors` has thirteen files
+ * that call it through a `shared.util.ts`, or that are a two-line
+ * `require('./client.test')` wrapper, and every one of them reported a 4s "pass"
+ * having deployed nothing. Two levels is what those two shapes need.
+ */
+function testSourceText(testFile, depth = 2, seen = new Set()) {
+  if (seen.has(testFile)) return "";
+  seen.add(testFile);
+  const text = read(testFile);
+  if (depth === 0) return text;
+  const dir = dirname(testFile);
+  const specifiers = [...text.matchAll(/(?:from\s*|require\(\s*)['"](\.[^'"]*)['"]/g)];
+  const extensions = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+  return [
+    text,
+    ...specifiers.flatMap(([, specifier]) => {
+      for (const extension of extensions) {
+        const candidate = join(dir, specifier + extension);
+        if (existsSync(candidate) && !statSync(candidate).isDirectory()) {
+          return testSourceText(candidate, depth - 1, seen);
+        }
+      }
+      return [];
+    }),
+  ].join("\n");
+}
+
+/**
+ * The fixture for a test file. For `test/e2e/<name>/test/index.test.ts` it lives
+ * a directory *above* the test file, and screening only the test file's own
+ * directory quietly misses its `middleware.js`.
+ */
+function fixtureRoot(testFile) {
+  const dir = dirname(testFile);
+  return basename(dir) === "test" ? dirname(dir) : dir;
+}
+
+/**
+ * The `excluded-notes` keys that name files rather than a topic ("edge runtime,
+ * generally" is prose), as predicates. Only `**` is honored, and only as a
+ * directory-tree suffix — that is every shape the keys use, and a real minimatch
+ * would be a dependency for nothing.
+ */
+function decidedMatchers(manifest) {
+  return Object.keys(manifest["excluded-notes"] ?? {})
+    .filter((key) => key.startsWith(`${TEST_ROOT}/`))
+    .map((key) =>
+      key.endsWith("/**")
+        ? (file) => file.startsWith(key.slice(0, -2))
+        : (file) => file === key,
+    );
+}
+
+/** Which of the screens disqualify this file, if any. */
+function screen(testFile, decided = []) {
+  const reasons = [];
+  if (decided.some((matches) => matches(testFile))) reasons.push("verdict");
+  const test = read(testFile);
+  const fixture = walk(fixtureRoot(testFile));
+  const sources = fixture.filter((p) => SOURCE_RE.test(p));
+
+  if (fixture.some((p) => /\/middleware\.[tj]sx?$/.test(p))) {
+    reasons.push("middleware");
+  }
+  if (sources.some((p) => EDGE_RUNTIME_RE.test(read(p)))) reasons.push("edge");
+  if (/describe\.skip/.test(test)) reasons.push("skipped-upstream");
+  // An empty `it('should skip …', () => {})` is what next.js writes for the modes
+  // a mode-gated file does not cover. Deploy mode is one of them unless the stub
+  // is the *dev*-only one, in which case the file runs here.
+  if (MODE_GATED_STUB_RE.test(test)) reasons.push("mode-gated");
+  if (/isNextDeploy/.test(test)) reasons.push("isNextDeploy-gate");
+  // `nextTestSetup({ skipDeployment: true })` returns `skipped`, the file
+  // early-returns, and jest reports it as passing in ~4s having deployed
+  // nothing. next.js declaring a file out of scope for deploy mode is the same
+  // signal as `isNextDeploy`, just spelled in the setup call.
+  // Read through relative imports for this one screen only. `skipDeployment: true`
+  // in a shared helper replaces every file that calls it, so following the import
+  // cannot over-report; the mode gates above can, since a helper's `isNextDev`
+  // branch may cover only some of a file's cases.
+  if (/skipDeployment:\s*true/.test(testSourceText(testFile))) {
+    reasons.push("skipDeployment");
+  }
+  // `test/e2e/**/test-template/{{ toFileName name }}/…` is a scaffold for
+  // `pnpm new-test`, not a test.
+  if (testFile.includes("{{")) reasons.push("scaffold");
+  if (sources.some((p) => /output:\s*['"]export['"]/.test(read(p)))) {
+    reasons.push("output-export");
+  }
+  return reasons;
+}
+
+process.chdir(nextDir);
+const testFiles = walk(TEST_ROOT).filter((p) => TEST_RE.test(p));
+if (testFiles.length === 0) {
+  console.error(`No e2e tests under ${join(nextDir, TEST_ROOT)}`);
+  process.exit(1);
+}
+
+const manifest = JSON.parse(readFileSync(MANIFEST, "utf8"));
+const included = new Set(manifest.rules.include);
+/**
+ * A file in `suites` runs too - minus its named cases - so it is neither a
+ * candidate nor an unscreened file.
+ */
+const inPart = new Set(Object.keys(manifest.suites ?? {}));
+
+const decided = decidedMatchers(manifest);
+
+const rows = testFiles.map((file) => ({
+  file,
+  included: included.has(file) || inPart.has(file),
+  reasons: screen(file, decided),
+  cases: (read(file).match(/^\s*it(\.each)?\(/gm) ?? []).length,
+}));
+
+const candidates = rows.filter((r) => !r.included && r.reasons.length === 0);
+const tally = {};
+for (const row of rows) {
+  if (row.included) continue;
+  for (const reason of row.reasons) tally[reason] = (tally[reason] ?? 0) + 1;
+}
+/** The ceiling on what could ever run here, edge being the hard limitation. */
+const edgeFree = rows.filter(
+  (r) => !r.reasons.includes("edge") && !r.reasons.includes("middleware"),
+).length;
+
+const screening = {
+  comment: [
+    "Regenerate with `node scripts/e2e-harness/screen.mjs --next ../next.js --write`,",
+    "and `--check` to verify these numbers still hold. Not read by next.js's",
+    "test/get-test-filter.js, which only looks at `version`, `suites` and `rules`.",
+    "",
+    "`candidates` is what is left after the screens below, all of which are",
+    "explained in scripts/e2e-harness/README.md. A candidate is a file worth",
+    "spending a deploy on - not a file expected to pass. Nothing enters",
+    "`rules.include` until it has been watched to pass against a real deployment,",
+    "and anything that fails gets a verdict in docs/harness-coverage.md.",
+    "",
+    "`included-in-part` counts files in `suites`: run, minus the cases named in",
+    "their `failed` arrays. They are excluded from `candidates` too.",
+    "",
+    "`disqualified-by` counts overlap - a fixture can ship edge middleware *and*",
+    "be skipped upstream - so the values sum to more than `e2e-files` minus",
+    "`candidates` minus `included`.",
+  ],
+  "next-version": JSON.parse(
+    readFileSync(join(nextDir, "packages", "next", "package.json"), "utf8"),
+  ).version,
+  "e2e-files": rows.length,
+  included: included.size,
+  "included-in-part": inPart.size,
+  "edge-free": edgeFree,
+  candidates: candidates.length,
+  "disqualified-by": Object.fromEntries(
+    Object.entries(tally).sort((a, b) => b[1] - a[1]),
+  ),
+};
+
+if (flag("list")) {
+  const pattern = value("list");
+  for (const row of candidates) {
+    if (!pattern || row.file.includes(pattern)) {
+      console.log(`${String(row.cases).padStart(3)}  ${row.file}`);
+    }
+  }
+  process.exit(0);
+}
+
+console.log(JSON.stringify(screening, null, 2));
+
+if (flag("write")) {
+  writeFileSync(
+    MANIFEST,
+    `${JSON.stringify({ ...manifest, screening }, null, 2)}\n`,
+  );
+  console.log(`\nWrote ${MANIFEST}`);
+} else if (flag("check")) {
+  const recorded = JSON.stringify(manifest.screening);
+  if (recorded !== JSON.stringify(screening)) {
+    console.error(
+      "\nThe manifest's `screening` block is stale. Re-run with --write.",
+    );
+    process.exit(1);
+  }
+  console.log("\n`screening` is up to date.");
+}

package/scripts/e2e-harness/stage-proxy.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * A localhost front door for a `NextjsRegionalFunctions` harness stack, which
+ * puts the API Gateway stage back into every request path.
+ *
+ *   node stage-proxy.mjs <port> <target>
+ *   node stage-proxy.mjs 43210 https://abc123.execute-api.us-east-1.amazonaws.com/prod
+ *
+ * Why it has to exist: a REST API's execute-api URL always carries the stage
+ * (`.../prod`), and next.js's harness discards any path in the deployment URL —
+ * `getFullUrl` in `test/lib/next-test-utils.ts` assigns `pathname` outright — so
+ * every absolute path the suite requests would miss the stage and get a 403 from
+ * API Gateway. The fixtures are written against a deployment served at the
+ * origin root, which is what this presents: `http://127.0.0.1:<port>/foo` goes to
+ * `<target>/foo`.
+ *
+ * The app is deployed with the fixture's own `basePath`, or none (`app.js`),
+ * never one that includes the stage. API Gateway strips the stage again before
+ * invoking the Lambda, so the app sees the same paths it would at a root-mapped
+ * custom domain — which is the setup `examples/regional-functions/README.md`
+ * recommends for production.
+ *
+ * The response goes back unchanged except for `Location`: an absolute one naming
+ * the target, or this origin over `https`, is rewritten to this origin, so the harness follows redirects here
+ * rather than to a URL whose stage it would then strip. Bodies stream both ways,
+ * so a streamed render is observed as streamed.
+ *
+ * Plain Node, no dependencies: `e2e-deploy.sh` starts it detached and it outlives
+ * that script, serving every test file the shared stack hosts.
+ */
+import { createServer, request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+
+const [portArg, targetArg] = process.argv.slice(2);
+if (!portArg || !targetArg) {
+  console.error("usage: stage-proxy.mjs <port> <target-url-with-stage>");
+  process.exit(2);
+}
+const port = Number(portArg);
+const target = new URL(targetArg);
+// No trailing slash: request paths are absolute and supply their own.
+const stagePrefix = target.pathname.replace(/\/+$/, "");
+const targetOrigin = `${target.protocol}//${target.host}`;
+const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+
+/** Hop-by-hop headers (RFC 9110 §7.6.1), which a proxy must not forward. */
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-connection",
+  "transfer-encoding",
+  "te",
+  "trailer",
+  "upgrade",
+]);
+
+function forwardable(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (!HOP_BY_HOP.has(name.toLowerCase()) && value !== undefined) {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+const server = createServer((req, res) => {
+  const localOrigin = `http://${localHost(req)}`;
+  const headers = forwardable(req.headers);
+  // API Gateway routes on the Host header and TLS on SNI, so both have to name
+  // the target - which is not the origin the browser is on. `x-forwarded-host`
+  // carries that one, and both Next.js and cdk-nextjs's runtime prefer it over
+  // `host`: without it, a server action's CSRF check compares the browser's
+  // `Origin` (`127.0.0.1:<port>`) against the execute-api host and aborts, and a
+  // `redirect()` to `location.origin + ...` reads as external. API Gateway sets
+  // `x-forwarded-proto: https` over ours, so absolute URLs the app builds come
+  // back as `https://127.0.0.1:<port>`; `rewriteLocation` fixes those up.
+  //
+  // What no header can fix: a fetch the *server* makes to its own origin (a
+  // server action streaming its redirect target, for one). It leaves the Lambda
+  // for 127.0.0.1, which is not this machine from there. That is the price of a
+  // local front door, and why such a test failing here is not a product defect.
+  headers.host = target.host;
+  headers["x-forwarded-host"] = localHost(req);
+
+  const upstream = send(
+    {
+      protocol: target.protocol,
+      hostname: target.hostname,
+      port: target.port || undefined,
+      method: req.method,
+      // `req.url` is the raw request target, still percent-encoded and with any
+      // repeated slashes intact: what the suite sent is what the app should see.
+      path: `${stagePrefix}${req.url}`,
+      headers,
+    },
+    (upstreamRes) => {
+      const responseHeaders = forwardable(upstreamRes.headers);
+      const location = upstreamRes.headers.location;
+      if (typeof location === "string") {
+        responseHeaders.location = rewriteLocation(location, localOrigin);
+      }
+      res.writeHead(upstreamRes.statusCode ?? 502, responseHeaders);
+      upstreamRes.pipe(res);
+    },
+  );
+  upstream.on("error", (error) => {
+    console.error(`stage-proxy: ${req.method} ${req.url}:`, error.message);
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain" });
+    }
+    res.end(`stage-proxy: ${error.message}`);
+  });
+  req.pipe(upstream);
+});
+
+/**
+ * An absolute `Location` on the target — with or without the stage — comes back
+ * on this origin. A relative one needs nothing: the app sees no stage, so it
+ * never emits one.
+ */
+function rewriteLocation(location, localOrigin) {
+  const httpsLocal = localOrigin.replace(/^http:/, "https:");
+  for (const prefix of [
+    `${targetOrigin}${stagePrefix}`,
+    targetOrigin,
+    httpsLocal,
+  ]) {
+    if (location === prefix || location.startsWith(`${prefix}/`)) {
+      return `${localOrigin}${location.slice(prefix.length) || "/"}`;
+    }
+  }
+  return location;
+}
+
+/** The authority the client addressed this proxy by. */
+function localHost(req) {
+  return req.headers.host ?? `127.0.0.1:${port}`;
+}
+
+server.listen(port, "127.0.0.1", () => {
+  console.error(
+    `stage-proxy: http://127.0.0.1:${port} -> ${targetOrigin}${stagePrefix}`,
+  );
+});

package/scripts/e2e-harness/type-filters.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Writes the manifest overlay that applies one NextjsType's exclusions.
+ *
+ *   node scripts/e2e-harness/type-filters.mjs <manifest> <nextjs-type> <out>
+ *
+ * `rules.excludeByType` in `test/deploy-tests-manifest.json` maps a type to the
+ * files, or cases within a file, that the harness cannot pass on that type for
+ * a reason docs/harness-coverage.md records - never a cdk-nextjs defect, which
+ * is a bug to fix. next.js's `test/get-test-filter.js` reads only
+ * `rules.include`/`rules.exclude` and `suites`, but it merges every manifest in
+ * the comma-separated NEXT_EXTERNAL_TESTS_FILTERS, and an exclusion by filename
+ * beats an inclusion. So this writes one more manifest for that list:
+ *
+ * - an entry with no `failed` excludes the whole file (`rules.exclude`);
+ * - an entry with `failed` skips those cases and runs the rest (`suites`), the
+ *   same mechanism as a `suites` entry in the manifest itself.
+ *
+ * A manifest without `rules.excludeByType`, or a type without an entry, gets an
+ * overlay that changes nothing, so a custom `test_filters` still works.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+
+const [manifestPath, nextjsType, outPath] = process.argv.slice(2);
+if (!manifestPath || !nextjsType || !outPath) {
+  console.error("usage: type-filters.mjs <manifest> <nextjs-type> <out>");
+  process.exit(2);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const entries = manifest.rules?.excludeByType?.[nextjsType] ?? {};
+
+const overlay = { version: 2, suites: {}, rules: { include: [], exclude: [] } };
+for (const [file, entry] of Object.entries(entries)) {
+  if (file === "comment") continue;
+  if (entry.failed?.length) {
+    overlay.suites[file] = { failed: entry.failed, flakey: [] };
+  } else {
+    overlay.rules.exclude.push(file);
+  }
+}
+
+writeFileSync(outPath, `${JSON.stringify(overlay, null, 2)}\n`);
+console.log(
+  `harness: ${nextjsType} excludes ${overlay.rules.exclude.length} files and ` +
+    `cases in ${Object.keys(overlay.suites).length} more`,
+);

package/scripts/e2e-logs.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH for the Next.js adapter compatibility
+# harness. Runs with `cwd` set to the harness's temporary app, in a separate
+# process from the deploy script, and additionally gets NEXT_TEST_DIR and
+# NEXT_TEST_DEPLOY_URL.
+#
+# Its output must start with the BUILD_ID / DEPLOYMENT_ID /
+# NEXT_SUPPORTS_IMMUTABLE_ASSETS markers.
+#
+# What comes *after* them is not just failure diagnostics: in deploy mode this
+# script's stdout **is** `next.cliOutput` (`next-deploy.ts`:
+# `this._cliOutput = await this.fetchBuildLogsUsingCustomScript()`), so every test
+# that asserts on `cliOutput` sees it. Vercel's own deploy mode puts only the
+# *build* logs there, and a test like `test/e2e/deprecation-warnings` -
+# `expect(cliOutput).not.toContain('is deprecated')` - fails on a deprecation
+# notice printed by the CDK CLI or echoed out of a CloudWatch tail, neither of
+# which the app emitted. So the default output stops at the build log, and the
+# deploy log and runtime logs are opt-in via HARNESS_VERBOSE_LOGS=1 for when a
+# deployment is actually being debugged.
+#
+# @see https://nextjs.org/docs/app/api-reference/adapters/testing-adapters
+set -uo pipefail
+
+: "${ADAPTER_DIR:?must be set to the cdk-nextjs checkout (the harness passes it through)}"
+# shellcheck source=scripts/e2e-harness/common.sh
+source "$ADAPTER_DIR/scripts/e2e-harness/common.sh"
+
+# Never fail. The harness turns a non-zero exit here into
+# "Custom deploy logs script failed", which replaces the deploy error that is
+# the actual reason it asked for logs.
+trap 'exit 0' ERR
+
+LOG_LINES=400
+
+# Markers first: `parseIdsFromCliOutput` takes the first match of each.
+[ -f "$HARNESS_MARKERS_FILE" ] && cat "$HARNESS_MARKERS_FILE"
+
+if [ -f "$HARNESS_BUILD_LOG" ]; then
+  echo "=== $HARNESS_BUILD_LOG (last $LOG_LINES lines) ==="
+  tail -n "$LOG_LINES" "$HARNESS_BUILD_LOG"
+fi
+
+# Everything below is off by default; see the header. The harness spawns this
+# script with the environment `run-tests.js` was started in, so re-running one
+# file with `HARNESS_VERBOSE_LOGS=1 node run-tests.js …` is all it takes.
+if [ "${HARNESS_VERBOSE_LOGS:-0}" != "1" ]; then
+  exit 0
+fi
+
+if [ -f "$HARNESS_DEPLOY_LOG" ]; then
+  echo "=== $HARNESS_DEPLOY_LOG (last $LOG_LINES lines) ==="
+  tail -n "$LOG_LINES" "$HARNESS_DEPLOY_LOG"
+fi
+
+# Runtime logs: a deployment that came up but answers wrongly leaves its
+# evidence in CloudWatch, not in either log above.
+# The Containers types name their log group outright; the Functions types' is
+# derived from the function name.
+if [ -f "$HARNESS_STACK_FILE" ]; then
+  STACK_NAME="$(cat "$HARNESS_STACK_FILE")"
+  LOG_GROUP="$(harness_stack_output "$STACK_NAME" ServerLogGroupName)"
+  if [ -z "$LOG_GROUP" ]; then
+    FUNCTION_NAME="$(harness_stack_output "$STACK_NAME" ServerFunctionName)"
+    [ -n "$FUNCTION_NAME" ] && LOG_GROUP="/aws/lambda/$FUNCTION_NAME"
+  fi
+  if [ -n "$LOG_GROUP" ]; then
+    echo "=== $LOG_GROUP (last 30m) ==="
+    aws logs tail "$LOG_GROUP" \
+      --since 30m \
+      --format short 2>&1 | tail -n "$LOG_LINES" || true
+  fi
+fi
+
+exit 0

package/scripts/e2e-offline.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# Build one e2e fixture through the adapter and serve it locally, so a failing
+# harness case can be instrumented without a 3-minute deploy per iteration.
+#
+# Usage, from this repo:
+#   scripts/e2e-offline.sh app-dir/layout-params [port]
+#
+# Prints two URLs: our container shell, and `next start` on the *same build*, which
+# is the comparison that matters - every "why does the deployed app disagree with
+# `next start`" question is one `diff` of two responses away once both are up.
+#
+# Why inside the next.js checkout: a fixture resolves `next` by walking up to the
+# repo's own `node_modules/next` symlink. Staged anywhere else, Turbopack fails with
+# "Could not find the Next.js package". `node_modules/cdk-nextjs` then has to live
+# inside the app for the same reason `e2e-deploy.sh` puts it there - the adapter
+# resolves its cache handler through a package boundary, and a relative path out of
+# the app directory "leaves the filesystem root".
+#
+# @see scripts/e2e-harness/README.md
+# @see docs/harness-coverage.md, which several entries were measured with this
+set -euo pipefail
+
+FIXTURE="${1:?usage: e2e-offline.sh <fixture, e.g. app-dir/layout-params> [port]}"
+PORT="${2:-3112}"
+NEXT_START_PORT=$((PORT + 1))
+
+ADAPTER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+NEXTJS_DIR="${NEXTJS_DIR:-$(cd "$ADAPTER_DIR/../next.js" && pwd)}"
+FIXTURE_DIR="$NEXTJS_DIR/test/e2e/$FIXTURE"
+if [ ! -d "$FIXTURE_DIR" ]; then
+  echo "e2e-offline: no fixture at $FIXTURE_DIR (set NEXTJS_DIR?)" >&2
+  exit 1
+fi
+for required in "$ADAPTER_DIR/lib/adapter/adapter.mjs" \
+  "$ADAPTER_DIR/lib/adapter/cache-handler.mjs" \
+  "$ADAPTER_DIR/lib/adapter/use-cache-default-handler.mjs" \
+  "$ADAPTER_DIR/lib/adapter/use-cache-remote-handler.mjs" \
+  "$ADAPTER_DIR/lib/runtime/server.mjs"; do
+  if [ ! -f "$required" ]; then
+    echo "e2e-offline: $required is missing. Run \`pnpm bundle\` in $ADAPTER_DIR." >&2
+    exit 1
+  fi
+done
+
+APP_NAME="offline-$(basename "$FIXTURE")"
+APP_DIR="$NEXTJS_DIR/$APP_NAME"
+rm -rf "$APP_DIR"
+mkdir -p "$APP_DIR"
+# Everything the fixture ships except its test file: the harness copies the same
+# set, minus the config snippet it appends (which only aliases __NEXT_TEST_MODE).
+(cd "$FIXTURE_DIR" && tar cf - --exclude='*.test.ts' --exclude='*.test.js' .) |
+  (cd "$APP_DIR" && tar xf -)
+printf '{ "name": "%s", "private": true }\n' "$APP_NAME" >"$APP_DIR/package.json"
+[ -f "$APP_DIR/next.config.js" ] || [ -f "$APP_DIR/next.config.ts" ] ||
+  [ -f "$APP_DIR/next.config.mjs" ] || echo 'module.exports = {}' >"$APP_DIR/next.config.js"
+
+mkdir -p "$APP_DIR/node_modules/cdk-nextjs/lib/adapter"
+cp "$ADAPTER_DIR/package.json" "$APP_DIR/node_modules/cdk-nextjs/package.json"
+# Every bundle the package's `exports` map points at: the adapter, the
+# `cacheHandler`, and the `cache-handlers/*` it resolves. A glob rather than the
+# list checked above, so a new export is copied without being added here.
+cp "$ADAPTER_DIR"/lib/adapter/*.mjs "$APP_DIR/node_modules/cdk-nextjs/lib/adapter/"
+
+cd "$APP_DIR"
+echo "e2e-offline: building $APP_NAME" >&2
+NEXT_ADAPTER_PATH="$APP_DIR/node_modules/cdk-nextjs/lib/adapter/adapter.mjs" \
+  NEXT_PRIVATE_TEST_MODE=e2e \
+  NEXT_TELEMETRY_DISABLED=1 \
+  "$NEXTJS_DIR/node_modules/.bin/next" build
+
+# `deploymentRootOf` asserts the shell lives in a directory named
+# `cdk-nextjs-runtime` next to the staged project, so reproduce that layout rather
+# than running the bundle from wherever it happens to be.
+STAGED="$APP_DIR/.next/cdk-nextjs-adapter/app"
+mkdir -p "$STAGED/cdk-nextjs-runtime"
+cp "$ADAPTER_DIR/lib/runtime/server.mjs" "$STAGED/cdk-nextjs-runtime/server.mjs"
+cp "$APP_DIR/.next/cdk-nextjs-adapter/manifest.json" "$STAGED/cdk-nextjs-runtime/manifest.json"
+
+cd "$STAGED"
+PORT="$PORT" node cdk-nextjs-runtime/server.mjs &
+SHELL_PID=$!
+cd "$APP_DIR"
+"$NEXTJS_DIR/node_modules/.bin/next" start --port "$NEXT_START_PORT" &
+START_PID=$!
+trap 'kill $SHELL_PID $START_PID 2>/dev/null || true' EXIT INT TERM
+sleep 3
+echo "e2e-offline: cdk-nextjs  http://localhost:$PORT" >&2
+echo "e2e-offline: next start  http://localhost:$NEXT_START_PORT" >&2
+echo "e2e-offline: app         $APP_DIR (delete it when done)" >&2
+wait