feat(dev): checkouts of one app get their own local services, and a service keeps its port

[wmadden-electric]

Linked issue

n/a. Part of the local-dev work that adds prisma dev url, prisma dev stop and prisma emulator list (plan in .drive/projects/emulator-commands/).

Summary

Two checkouts of the same app can now run prisma dev side by side without touching each other:

~/work/shop   $ prisma dev module.ts        ~/work/shop-2 $ prisma dev module.ts
dev: ready                                  dev: ready
gateway: http://localhost:3001              gateway: http://localhost:3003
quotes: http://localhost:3000               quotes: http://localhost:3002

Before this PR, the second prisma dev took over the first one's services. It redeployed its own build onto the same processes and ports, and a --fresh in either checkout wiped both.

Decision: the local emulator that runs service processes no longer knows what an app, a node or a directory is. It runs instances under ids it generates. Composer records, in each directory, which instance runs each of that directory's services. A service keeps its port until its instance is deleted. ADR-0052 records this.

Background: what runs a service locally

prisma dev runs your app against local stand-ins for Prisma Cloud. The stand-in for Prisma Compute is the Compute emulator: one long-lived process per machine that starts and supervises every local service process. Until now it identified services by app name and service name (/apps/shop/services/gateway). Two checkouts of one app have the same names, so they got the same services.

The emulator runs instances

The Compute emulator now holds instances. Creating one returns an id the emulator generates (svc_ plus 16 hex characters). Deploying, starting, stopping, deleting and reading logs all take that id, and GET /instances lists them all.

An instance can carry labels, strings the emulator stores and returns but never reads. Composer writes the directory, the app and the service's address on every instance it creates, so a person reading the list can tell what started each one.

A deployment still contains Composer's names: the artifact directory sits inside the project, and environment variable names include service addresses. The emulator stores these as they are and never interprets them. A test fails if any route, state key, file name or field the emulator generates contains an app, address or directory.

Composer keeps a record per directory

.prisma-composer/dev/emulator-instances.json stores the app's name and, for each service, the id of its instance and its port. prisma dev writes the record before it deploys:

• It reuses each recorded instance the emulator still has.
• It creates any instance that's missing.

Everything else finds instances only through the record: deploying, starting and stopping services, reading logs, and --fresh. Nothing looks instances up by label.

Ports stay with a directory

An instance keeps its port from creation until it is deleted, whether its service is running or stopped. That matters because the port is built into more than the process: the service's environment contains it, and its dependents' environments contain its URL. A warm start doesn't redeploy anything, so a port that moved between sessions would leave services running with stale values.

The record remembers each port for the one case where it can change: the emulator lost an instance, for example when its state was wiped, and Composer has to create it again. Composer then asks for the same port. If something else holds it, the service gets the lowest free port from 3000, and prisma dev prints:

[dev] service "gateway" now uses port 3004: its previous port 3001 is in use

The re-created service and its dependents are then redeployed with the new values.

Other behaviour

• Running a different app from the same directory deletes the previous app's services, which hold no data, and prints which app's services were removed. (The next PR, feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356, changes this to stop-and-keep, once databases are involved.)
• Error messages from the emulator name the instance id. Composer rewrites them to name the service, so prisma dev prints what it printed before.
• Old emulator state in the app-keyed format is discarded on upgrade. Local dev state has never been migrated across versions.
• Postgres and buckets are still keyed by app name. feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356 moves them to this model.

Testing performed

Against a real Compute emulator in a temporary PRISMA_COMPOSER_EMULATORS_DIR, with real bun service processes (skipped on Windows, where local dev isn't supported):

• One app run from two directories gets separate instances and ports. Redeploying one directory leaves the other's process ids unchanged.
• A warm restart reuses the same instances and ports. A lost instance comes back on its remembered port. A taken port moves, with the notice, and dependents are redeployed.
• --fresh and app switching remove the right instances.
• Error messages name the service, not the instance.
• The emulator's own tests cover ids, labels, port rules, restarts, discarding old state, and the readiness and concurrency rules it already had.
• By hand, on examples/env-param: a cold start, Ctrl-C, a warm start on the same port, a deleted instance coming back, a taken port moving, and --fresh.

Also pnpm build, typecheck, lint, lint:deps and lint:casts, and the local-dev integration scripts, each run on its own.

Checklist

• All commits are signed off (git commit -s) per the DCO. The DCO status check will block merge if any commit is missing a Signed-off-by: trailer.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• The PR title is a conventional commit (feat, fix, chore, docs, refactor, test, build) — PR titles drive the auto-generated release notes.
• Tests are updated (or n/a if the change is doc-only / refactor with no behavioural delta).

Notes for the reviewer

• Docs updated: ADR-0052, docs/design/10-domains/local-dev.md, docs/guides/running-locally.md and the core-concepts skill. The guides' example of prisma dev's output was out of date and is fixed.
• Deferred, in .drive/projects/emulator-commands/deferred.md: the [dev] notice lines go straight to stdout, outside the CLI's output handling, as the existing [dev] lines already do.

Alternatives considered

• Keep app-keyed emulators and make the local identity the app name plus a hash of the directory. This separates checkouts, but keeps Composer's names inside the emulators, which should be usable without Composer, and may move out of this repo.
• Find instances by their labels instead of keeping a record. The labels would become a second, unenforced identity.
• Release a port when an instance stops, so a deleted checkout doesn't hold ports. The port is baked into the service's and its dependents' environments, and a warm start doesn't redeploy, so a restarted service could end up on a port its environment doesn't match. Leftover instances keep their ports until a remove command exists.
• Fail prisma dev when a remembered port is taken. That breaks one checkout whenever another happens to take the port. Moving with a notice keeps it running.

Agent: attila-51

🤖 Generated with Claude Code

[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: b40914bf-873c-4565-a053-83611340e7ff

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

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

[prisma-gizmo]

✅ Gizmo reviewed a16380a — posted 1 inline comment(s) this pass.

Open findings: 🟡 1 minor

Change walkthrough

This delta extends the emulator-instance work from the rest of PR #354 with a test-only readiness-poll knob and two race tests. The compute daemon now takes --ready-poll-ms (default 50 ms, matching the old hard-coded constant), validated and threaded exactly like --ready-timeout-ms into the single waitUntilListening call site, so both the deployment PUT and the session-resume start honor it. Nothing outside the emulator's own tests passes it — daemon.ts and client.ts send no such argument, as the updated local-dev.md:121 now documents.

The purpose is to widen the window between a child process exiting and its start noticing, so the tests can act inside the race that #353's joinableStart/supersededOutcome machinery governs: a start arriving after the child exited but before the in-flight start fails must begin fresh rather than join a dead restart. The new "with a 3-second readiness poll" block in compute-readiness.test.ts covers the session-resume path (start just after held re-runs the service) and the deployment path (an identical PUT just after exit starts clean, verified by asserting the log has no crash trail). Supporting pieces follow existing patterns closely: the slow-ready-poll.ts fixture mirrors short-ready-timeout.ts (process.argv.push then re-import of @internal/dev-emulators/compute-main), and CRASH_UNTIL_ALLOWED_BOOTSTRAP in helpers.ts follows CRASH_ONCE_THEN_SILENT_BOOTSTRAP, relying on the child's cwd being the artifact directory, which the spawn confirms.

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: 6e495ff

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: 🟠 1 major · trace

Findings outside the diff

• 🟠 Major · tests packages/1-prisma-cloud/0-lowering/dev-emulators/src/compute-main.ts — New joinability rule (a process-exited start is not joined) has no test
  The delta changes when concurrent requests join an in-flight start: joinableStart returns undefined once the start's child has exited, so a resume start or an identical deployment PUT arriving in the window between child exit and the doomed start's promise settling now spawns its own attempt instead of awaiting a failure. Both changed call sites (startInstance and the PUT handler at L759-L764) and the two amended local-dev.md table rows specify this rule, but src/__tests__/compute-readiness.test.ts has no case for it — its start-interleaving tests (e.g. "a repeated identical deployment during a redeploy waits for the new process", "two concurrent session-resume starts share one process") only cover the still-joinable cases. This is exactly the race class #353 shipped bugs in, and the window is real (exit listener fires while the start is still awaiting waitUntilListening), so the new semantics can regress silently.
  Recommended fix: Add a concurrency test to src/__tests__/compute-readiness.test.ts alongside the other start-interleaving cases: spawn a service that exits before listening, wait for the exit event, then issue a session-resume start (and separately an identical PUT) and assert it fails on its own with a fresh attempt's message rather than inheriting the first start's result.

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: 🟡 1 minor · trace