[wmadden-electric]

At a glance

D  .drive/projects/emulator-commands/   (spec, plan, design notes, six slice specs, deferred list)
M  .drive/deferred.md                   (+ "Emulator commands — deferred at project close")

This closes the emulator-commands project. It deletes the project's planning files and moves the follow-ups it left open into the repo-wide deferred list.

What the project delivered

These commands ship in Composer 0.32.0 and prisma@8.0.0-rc.24:

• prisma dev url <address> prints where a node of the local app answers.
• prisma dev stop stops the app and keeps its data and ports.
• prisma dev --detach returns once every service answers.
• prisma emulator list shows every instance the machine's emulators hold.

The design is recorded in ADR-0052 (Composer maps its nodes to emulator instances per directory) and ADR-0053 (the commands). The user docs are docs/guides/running-locally.md, docs/design/10-domains/local-dev.md and the core-concepts skill. Nothing in the deleted files needs to move: the design notes' decisions are in those ADRs, and the specs and plan only coordinated the work.

Definition of done

Each item from the project spec, with its evidence:

• The getting-started app returns a quote through curl "$(npx prisma dev url gateway)" from the published binary. Met. The page was followed as written against prisma@8.0.0-rc.24 (docs: Composer pages ask prisma dev url for local URLs, and the CLI reference covers dev url, dev stop, --detach and emulator list web#8545). The spec's jq pipe was dropped when the CLI started giving a pipe plain data (feat!: piping a prisma command gives its plain data; JSON needs --json prisma-cli#353).
• Two directories running the same app get separate instances. Met. Instances are keyed per directory (feat(dev): checkouts of one app get their own local services, and a service keeps its port #354, feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356), and emulator list labels each with its directory.
• After Ctrl-C, or dev stop after a kill -9, nothing of the app runs, and the next prisma dev gets the same ports. Met (feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356, fix(dev): prisma dev stop reports only what it stopped, and dev and deploy flag help says what each flag does #368). This was checked against real emulators, including a stop while a service is still starting.
• emulator list shows services, databases and buckets with their directory and address. Met (feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356, fix: emulator list writes data lines to a pipe, and dev url's docs use the bare URL #365).
• No emulator route, state key or file name carries an app, address or directory. Met (feat(dev): checkouts of one app get their own local services, and a service keeps its port #354). Composer data reaches an emulator only as labels.
• ADRs record the model and the commands, and ADR-0044 lists the new codes. Met: ADR-0052 and ADR-0053 were written as new ADRs rather than amendments, and ADR-0044 lists the DEV.* codes.
• The local-dev domain doc, the running-locally guide and the skill describe the commands. Met.
• prisma-cli mounts the commands, with e2e coverage exclusions. Met (feat: add prisma dev url, prisma dev stop and prisma emulator list (Composer 0.31.0) prisma-cli#355).
• The prisma/web pages use prisma dev url. Met (docs: Composer pages ask prisma dev url for local URLs, and the CLI reference covers dev url, dev stop, --detach and emulator list web#8545).

Follow-ups

The project's open follow-ups now live in .drive/deferred.md, under "Emulator commands — deferred at project close". Two items were dropped because they were resolved: a held service's start race, and services that never listen (both fixed in #353). A third was dropped too: what a previous app's databases and buckets become, which was decided as "stopped and kept". One prisma-cli item was added: its agent-skills notice names @prisma/orm-postgres in projects that don't use it.

Retro

Lessons from the project, each already recorded where it applies:

• A stopped instance first released its port, which broke restarts, because the port is baked into dependents' environment variables. ADR-0052 now says an instance keeps its port until it is deleted.
• A change to dev stop's report made it skip instances that were still starting. A real-emulator test now fails if the stop is sent only to listed instances.
• Test files picked clashing ports on CI. Each file now uses its own port range.
• A fixed bot review left in "changes requested" blocked approved PRs. This is noted in the agent's merge procedure.

Alternatives considered

• Keep the project directory as a record. The ADRs, guide and merged PRs already hold everything a later reader needs. The planning files would go stale.
• Open GitHub issues for each follow-up. The repo keeps follow-ups from closed projects in .drive/deferred.md, so this follows that.

Agent: attila-51

🤖 Generated with Claude Code

[prisma-gizmo]

Caution

Gizmo failed to process the last GitHub event for this pull request: This suspended workflow run was already resumed by another caller. Workflow "guardrail-lifecycle" run "67a34152-6694-44ea-b41d-662f056c7579" moved from "suspended" to "running" before this resume could claim it. Only one resume() call may continue a given suspension; re-read the run state before resuming again.

Open findings: 🟡 1 minor

Change walkthrough

This PR closes the emulator-commands project: it deletes .drive/projects/emulator-commands/ (spec, plan, design notes, six slice specs, deferred list) and migrates the project's open follow-ups into the repo-wide .drive/deferred.md under a new "Emulator commands — deferred at project close (2026-10-21)" section, following the repo's convention of keeping follow-ups from closed projects in the central list rather than filing GitHub issues.

What shipped (recorded as done). The four commands — prisma dev url, prisma dev stop, prisma dev --detach, prisma emulator list — are marked delivered against real emulators, with the design captured in ADR-0052 (per-directory instance mapping) and ADR-0053 (the commands). The PR argues nothing needs migrating out of the deleted files: the design notes' decisions live in the ADRs, and the specs and plan only coordinated the work.

The deferred section. The new section carries the project's unresolved items forward — the delete-while-starting race, shared env.json/secrets.json, [dev] notices bypassing the CLI engine's output, missing dev url retry, data-line gaps for deploy/--detach/ORM commands, and the planned emulator start/stop project. Three items from the project's own deferred list were dropped as resolved (start-join crash-backoff race, services that never listen, and the fate of a previous app's databases/buckets), which the PR description accounts for.

Incremental delta. Since the last reviewed commit, the only change is a two-line parenthetical appended to the "ORM commands print nothing to a pipe" bullet at .drive/deferred.md:237-238, carving out contract print and contract emit as already writing their output to stdout.

One review-context note: git history beyond the diff was unreachable in this checkout, so claims pointing at merged PRs (composer #353–#368, prisma-cli #353/#355, web #8545) were taken as documented rather than re-verified.

[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: 64b9925d-0b47-401b-8725-6a9e4df244d2

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

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

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[prisma-gizmo]

New findings: 🟡 1 minor · trace