The emulator port-retry test exercises the retry and waits for the daemon; PRISMA_COMPOSER_EMULATORS_DIR picks the registry

[wmadden-electric]

Found while landing the one-config-file project (prisma/orm#30536): the dev-emulators suite failed the port-retry test on four of six CI runs of two branches, while main stayed green.

(fail) fresh-allocation port retry (spec § 2 step 5) > a bind failure on a fresh allocation retries the next free port
error: expect(received).toHaveLength(expected)
Expected length: 1
Received length: 0

What was wrong

Two things, both in the test.

It raced the daemon's log line. ensureDaemon returns on the first good health check. Under Bun the compute daemon answers /health before its listen callback has written the "listening on" line, and the test read the log straight away. Measured by starting the built daemon the way ensureDaemon does and polling health: the line was missing at the first good check in roughly one start in six, and present 300 ms later every time. Writing the line synchronously does not help; the callback itself runs late. Which branch hits it is timing: main's CI run of this test took 2.1 s and the failing branch run 1.26 s.

It never exercised the retry. The test "squatted" a port it got from get-port, but get-port locks every port it hands out inside the process, so the squatted port was never allocated to the daemon and the first bind succeeded. The retry path the test is named for had no coverage.

The fix

The retry test starts the daemon through a fixture that, on its first start, binds its own allocated port and then runs the real daemon, so the bind fails for real and ensureDaemon retries. It asserts the daemon ends on a port above the taken one, and waits for the listening line instead of reading the log immediately. The concurrent-ensure test waits for the line the same way. With retries disabled the new test fails with "compute emulator failed to start on port 4307".

Emulator copies per checkout or CI job

The daemons are machine-wide by design, registered under ~/.prisma-composer/emulators, and the daemon API already takes a registryRoot so copies can coexist. Nothing let a user or CI choose one. PRISMA_COMPOSER_EMULATORS_DIR now sets the registry root; a relative value is refused with DEV.EMULATORS_DIR_INVALID. The three local-dev integration proofs read their root from the new emulatorRegistryRoot() export on @prisma/composer-prisma-cloud/local-target instead of hardcoding the home path. The running-locally guide and the skill describe the variable. Not covered: @prisma/dev keeps its own Postgres server records outside this directory, so two checkouts still share those.

Review outcome

The architect and principal-engineer passes (in prisma/orm#30536, slices/04-emulator-port-retry/review/) found one thing the first version understated: the variable isolates the compute and buckets daemons, their registry and their data, but not local Postgres. Two checkouts of one app get the same local Postgres server names, so the second checkout's emulator adopts the first's running server, and --fresh or teardown in either stops that server and deletes its database for both. The guide, the skill and the local-dev design doc now say exactly that. Smaller items from the review: the settle wait requires two quiet windows and has a deadline; the value is normalised and the error says ~ is not expanded; the variable name is an exported constant; the error reaching the CLI is tested through the engine harness.

Follow-ups, not in this PR

• Include the registry root in local Postgres instance names when the variable is set, so each root gets its own Postgres server.
• The "held after 5 consecutive fast crashes" test allows 20 s while its backoff alone takes 15 s, a likely flake under load; raise the budget or make the backoff base injectable.

Verification

• The four new registry-root tests failed before the implementation and pass after; the retry test fails with retries disabled.
• Root lint, typecheck, lint:deps and check:skill-packaging pass. test/integration's bun test passes.
• A local-dev proof run with the variable set to a scratch directory started its daemons on 4303, 4305 and 4307 beside the home daemons on 4304 and 4306, wrote its lock files under the scratch directory, and left the home registry byte-identical.

Agent: columbo-17

🤖 Generated with Claude Code

[prisma-gizmo]

✅ Gizmo reviewed 60973f1 — posted 0 inline comment(s) this pass.

Open findings: 🟡 2 minor

Change walkthrough

This PR fixes a flaky dev-emulators port-retry test that never actually exercised the retry (the old test squatted a port that get-port had already locked in-process, so the first bind always succeeded; it also read the daemon's log before the listen callback had written the "listening on" line), and adds PRISMA_COMPOSER_EMULATORS_DIR so a checkout or CI job can get its own emulator daemons instead of sharing the machine-wide ~/.prisma-composer/emulators registry.

Test reliability (daemon.test.ts, helpers.ts, port-taken-on-first-start.ts). The retry test now starts the daemon through a fixture that binds its allocated port itself on first start, so ensureDaemon's fresh-allocation retry path runs for real; the shared awaitListeningLines helper waits for the log line and requires two quiet 500 ms windows before asserting counts, which the concurrent-ensure test uses too. The fixture's args match what daemon.ts spawnDaemonProcess passes, and the asserted listening-line string matches compute-main's output exactly.

Registry root (daemon.ts, local-target.ts). defaultRegistryRoot() now reads the env var, normalises the value, and refuses relative or ~-prefixed paths with a structured DEV.EMULATORS_DIR_INVALID error (registered in ADR-0044). The variable is exported as EMULATORS_DIR_ENV, re-exported through the published local-target entry as emulatorRegistryRoot() (with the ambient .d.ts kept in sync), which is how the three local-dev integration proofs replaced their hardcoded home path. The existing { registryRoot } test seam stays test-only — production emulators.ts relies on the default, so the env var is the single production knob.

Coverage (dev-emulators-dir.test.ts). A new CLI-level test proves the structured error reaches the dev run envelope unchanged; it duplicates the error's strings because the CLI package can't import @internal/dev-emulators, as its header documents.

Docs (design doc, guide, skill). All three state the same caveat: the variable isolates compute/buckets daemons, registry, and data, but not local Postgres — two checkouts of one app still share a server, with --fresh/teardown in either affecting both.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 535010e2-a45b-4538-9418-afb0dba542c7

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@333

npm i https://pkg.pr.new/@prisma/composer-cli@333

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@333

commit: 60973f1

[prisma-gizmo]

New findings: 🟡 2 minor · trace

[prisma-gizmo]

🟡 Minor · correctness — Guide overstates isolation: Postgres data is not scoped by PRISMA_COMPOSER_EMULATORS_DIR

The new bullet says setting PRISMA_COMPOSER_EMULATORS_DIR gives a checkout or CI job its own emulators "with their own data, so two checkouts or two CI jobs never share a daemon by accident". That is true for the compute/buckets/postgres daemons and their registries, but — as the PR description itself notes — @prisma/dev keeps its own Postgres server records outside this directory, so two checkouts with different PRISMA_COMPOSER_EMULATORS_DIR values still share the local Postgres data and the machine-wide Postgres session. A reader isolating a CI job for data-separation reasons (not just daemon-port reasons) will not get the isolation the bullet implies. The existing "local Postgres is one shared session" bullet below covers the session, not the server records.

Recommended fix

Add a caveat sentence to the new bullet, e.g. "The @prisma/dev Postgres server records stay machine-wide regardless of this variable, so two registry roots still share the local Postgres data."

[prisma-gizmo]

🟡 Minor · tests — awaitListeningLines stops at the first line, so the concurrent-ensure count can still race a duplicate line

awaitListeningLines resolves as soon as the first listening on line appears, and the concurrent-ensure test immediately asserts toHaveLength(1). A losing racing spawn's listening line — the exact failure mode this test exists to catch — that lands after the first successful poll is never seen, so the assertion can pass while the protocol violation is still in flight. This is not a regression (the old code read the log immediately, a strictly worse window), but since this PR reworks this line to stop racing the daemon, waiting only for the first line still leaves the assertion able to outrun the evidence. The retry-test caller is unaffected: its failed start provably cannot log a listening line.

Recommended fix

After the first listening line appears, let the helper settle before returning — e.g. sleep ~500 ms and re-read the log — so a second spawn's line has time to show up before the count is asserted.

[prisma-gizmo]

New findings: none · trace

Still open from previous reviews: 🟡 2 minor

Both findings addressed in the follow-up commits; the bot's re-review reports no new findings.

[prisma-gizmo]

New findings: none · trace

Still open from previous reviews: 🟡 2 minor

[prisma-gizmo]

New findings: none · trace

Still open from previous reviews: 🟡 2 minor