fix(run): quote a long app log's first lines in APP_UNREACHABLE

Merged
DE
13d ago
+216-30

What and why

  • When an app.command dies during startup, the APP_UNREACHABLE message is often the only diagnostic a run leaves. With a command.log, it quotes what the process appended since it started, command.env and inheritEnv values redacted.
  • That quote was a tail: the last 20 lines of the last 4 KiB. A process that prints its fatal error early and keeps logging (file watchers, bundlers, half-started dev servers) buried the one line that explains the failure. #1527 hit this: the cause was in the first lines, the message showed only the end.
  • outputSince(offset) read a single window at the end of the file, so nothing before it could be recovered downstream. It now reads the other end too.

What changed

  • packages/e2e/src/run/managed-process.ts: outputSince reads two windows of OUTPUT_WINDOW_BYTES (4 KiB), one from the command's own log offset and one ending at the end of the file.
    • Windows that meet (the log since the command started fits in 8 KiB): quoted whole up to 40 lines, otherwise the first 20, [startup output omitted], the last 20.
    • Windows that do not meet: always the first 20, the marker, the last 20. The marker stays even when one huge first line leaves nothing above it.
    • The head starts at the command's own offset without clipping, so a first line written after a previous run's unfinished line survives.
    • A clipped edge drops its fragment before empty lines are filtered, so a whitespace-only fragment cannot take the complete line above it.
    • Every quoted line goes through the same this.redact pass as before.
  • packages/e2e/src/run/managed-process.ts: the inline read became a module-level readLines(fd, from, to, { start, end }) helper that both windows share.
  • packages/e2e/tests/unit/managed-process.test.ts: keeps the last 20 lines only became a whole-log test, since a 25-line log has nothing omitted now. New exact-equality tests cover the line cap on both branches, both byte thresholds of the overlap check, cuts inside a line and exactly between lines, the whitespace fragment, an offset > 0 log with and without a final newline, and the marker after a huge first line.
  • docs/web.mdx, docs/reference/config.mdx, docs/reference/errors.mdx: the quote is described as whole for a short log, otherwise the first and last lines with the marker between them. The config page names the byte bound.
  • .changeset/app-unreachable-first-lines.md: e2e patch.
flowchart TD
  A[app.command fails at startup] --> B[read the log since the command started]
  B --> C{do the head and tail windows meet?}
  C -- yes --> L{more than 40 lines?}
  L -- no --> D[quote every line]
  L -- yes --> E
  C -- no --> E[first 20 lines]
  E --> F[startup output omitted]
  F --> G[last 20 lines]
  D --> H[redact command.env and inheritEnv values]
  G --> H
  H --> I[APP_UNREACHABLE message]

Issue

Fixes #1527

Verified

Ran it locally: yes

Surface: the APP_UNREACHABLE message the built CLI prints when app.command exits before the app is ready, on a scratch project whose command writes one fatal line, one line naming DATABASE_URL, then 40 watcher lines, and exits 1. The main side below is the dist built before this change, the branch side is the same command after rebuilding packages/e2e.

main:        output in .e2e\app.log since target "web" command started:
               watcher: rebuilt module 21
               ...
               watcher: rebuilt module 40

this branch: output in .e2e\app.log since target "web" command started:
               fatal: ENOENT: no such file or directory, open .env.local
               hint: DATABASE_URL=<secret:DATABASE_URL>
               watcher: rebuilt module 1
               ...
               watcher: rebuilt module 19
               [startup output omitted]
               watcher: rebuilt module 21
               ...
               watcher: rebuilt module 40
mainthis branch
the fatal line and modules 1 to 20 are missing from the messagethe fatal line comes first, the gap is marked
the line naming DATABASE_URL is missing, so no value could leakthe same line is quoted with the value masked as <secret:DATABASE_URL>
the log file keeps the raw valuethe log file keeps the raw value, the message does not
  • The first two new tests were written first and watched failing on the old code (expected [ ' line 41', ... ] to equal [ ' line 1', ... ]), then passing after the change. The whole file on the latest head: 34 passed, 1 failed, 1 skipped.
  • The one failure is fails with APP_UNREACHABLE when the log path cannot be opened, and it fails on this machine on main too, with the change stashed: opening a directory as an append log resolves here instead of throwing, so no InfrastructureError is raised. Windows-only, unrelated to this change.
  • tsc --noEmit on packages/e2e: exit 0. oxlint on both changed files: 0 warnings, 0 errors. check-changeset-bumps.ts and check-error-codes.ts: exit 0.
  • Not run locally: the full pnpm check chain and the browser-backed integration suites, which need a full build of every package (about twelve minutes here) and Chromium. CI ran them on the latest head and the spec, benchmark, mobile, and docs gates passed. The change touches no engine code, no wire format, and no exported type.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.