[wmadden-electric]

Linked issue

n/a. Rough edges found while testing the Composer 0.31.0 local-dev commands through the real prisma binary (prisma/prisma-cli#355).

Summary

# before
$ prisma dev stop
✔ Stopped orm-demo. Its data and ports are kept for the next `prisma dev`.
$ prisma dev stop
✔ Stopped orm-demo. Its data and ports are kept for the next `prisma dev`.
$ prisma dev url api
✖ The service "api" is not running (stopped).
  `prisma dev` stops the app when it ends, and a stopped node has no URL that answers.

# after
$ prisma dev stop
✔ Stopped orm-demo. Its data and ports are kept for the next `prisma dev`.
  Address   Kind
  database  database
  api       service
$ prisma dev stop
ℹ Nothing of orm-demo was running.
$ prisma dev url api
✖ The service "api" is stopped.
  `prisma dev stop`, `prisma dev` ending, and running another app in this directory all stop an app's services and database servers, and a stopped node has no URL that answers.

Decision: the local-dev commands report what actually happened, and four flag descriptions say what the user gets instead of using internal terms.

Background

prisma dev runs an app on local emulators, the processes that stand in for Prisma Cloud on your machine. Each of the app's services and databases runs there as an instance. prisma dev stop stops the app's instances, and so does prisma dev when it ends.

prisma dev stop reports only what it stopped

Before, dev stop listed every service and database the app had, whether or not it was running. A second dev stop claimed to stop everything again.

Now it asks each emulator which of the app's instances are running and lists only those. When nothing was running, it says "Nothing of was running." and still exits 0.

It still sends a stop to every instance, running or not. An instance that is still starting reports itself as stopped until it accepts connections. If dev stop skipped it, a Ctrl-C during startup would leave it running after prisma dev exits. The one instance it leaves alone is a service the emulator has given up on after repeated crashes: it has no process left to stop.

Ctrl-C on prisma dev, and running a different app from the same directory, use the same stop.

A stopped service says what stops services

prisma dev url for a stopped service used to say "prisma dev stops the app when it ends". That was wrong after an explicit prisma dev stop. The command can't know which cause applied, so it now lists them: prisma dev stop, prisma dev ending, and running another app in this directory. The fix is unchanged: run prisma dev.

Flag help in plain terms

These follow the prisma CLI's help standard. "Root module" is the term the help already uses for the <entry> argument.

Flag	Before	After
dev --name	Override the root node's name — the dev instance's application name.	Run the app under this name instead of the name its root module declares. A different name gets its own local services, databases and buckets.
dev --fresh	Destroy the dev stack and wipe the dev state directory.	Delete this app's local services, databases and buckets, and their data, before starting.
deploy --name	Override the root node's name — the deploy's application name.	Deploy the app under this name instead of the name its root module declares. A different name is a separate app on Prisma Cloud.
deploy --stage	Deploy scope to target; omit for production.	Deploy a complete, isolated copy of the app under this name instead of production, such as staging or one per pull request.

local-dev.md and deploy-cli.md now describe --fresh the same way: it deletes the current app's local services, databases and buckets and their data, and other apps run from the same directory keep theirs.

Testing performed

• Against real emulators (local-target-current.test.ts, skipped on Windows):
  • A second stop stops nothing and reports nothing.
  • A stop while a service is still starting ends that start, and the service ends stopped with its port closed. This test fails if the stop is sent only to instances listed as running.
  • A crash-looping service is reported and stays stopped past its restart delay.
  • A service the emulator gave up on is not reported and is left as it is.
• Through a real prisma.config.ts (control.dev-current.test.ts): devStop reports only the running service and database, then nothing on a second call.
• Command output: the dev stop table, the "Nothing … was running" message, and the stopped-service error.
• Integration scripts: local-dev-detach and local-dev-store, each run on its own, since Ctrl-C uses the changed stop.
• Checks: pnpm typecheck, pnpm lint, pnpm lint:deps, the family import-graph check, check:skill-packaging, lint:retired-binary-name, and the website tests.

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

• A database that is still starting is stopped but not listed, because it reports itself as stopped until its server is up. Stopping it is what matters.
• The database database row is correct. In the example it's a node whose address happens to be database.
• Recorded for later in .drive/projects/emulator-commands/deferred.md:
  • prisma dev --detach prints its URLs only as human text on stderr, while the deploy engine's log goes to stdout. That's the same cause as prisma deploy having no plain pipe output, so the two should be fixed together.
  • prisma dev url outside a Composer project fails with two config errors instead of "prisma dev has not run here".

Alternatives considered

• Keep listing every node from dev stop and only change the wording. It would still claim to stop nodes that were already stopped.
• Send a stop only to instances listed as running. The report is right, but an instance that is still starting keeps running.
• Rename the table's Kind column. The headers already make the database database row clear, and the column names match prisma emulator list.

Agent: attila-51

🤖 Generated with Claude Code

[prisma-gizmo]

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

Open findings: none

Change walkthrough

This PR makes the local dev surface report what actually happened: prisma dev stop now stops and lists only instances that were running (saying "Nothing of … was running." when none were), dev url for a stopped node states every way the node can have been stopped instead of blaming only prisma dev ending, and the --name/--fresh/--stage flag help on dev and deploy describes the effect on services, databases and buckets. The incremental delta since the last pass rewords the flag briefs to "root module", adds the "running another app in this directory" cause to the DEV.NOT_RUNNING message, refines stopRunning to cancel in-flight starts while preserving held services, and adds emulator-backed tests and doc/skill updates.

Stop semantics (emulator-instances.ts). The service branch stops every recorded id except settled-held instances (held with no pid), and reports those with a pid or a running/backoff status — this covers starts in flight, which can still be listed as stopped, and pending crash restarts, which the stop cancels. The database branch stops all recorded ids (the emulator skips unknown ids) and reports those listed running, which is the only non-stopped database state. The returned-ids contract to stopNodes and its callers (dev stop, selectApp, Ctrl-C) is unchanged.

Stopped-node message (execute-dev-current.ts). The dedicated stopped branch now reads "is stopped" with all three causes — prisma dev stop, prisma dev ending, and switching apps (selectApp stops the previous app) — while the crashing and missing branches keep their own why/fix. The unit test in dev-current.test.ts asserts the new strings verbatim.

Flag help (dev.ts, deploy.ts). --name on both commands now says "root module", matching the entry positional's wording; deploy --stage's brief describes the isolated named-stage branch with its production default, consistent with validateStageName and target resolution.

Tests and docs. The three new tests in local-target-current.test.ts exercise the new stop paths against real emulators: an in-flight start is cancelled and nothing ends up listening, a backoff service is reported and stays stopped past its restart timer, and a held service is neither stopped nor reported. running-locally.md and SKILL.md mirror the new messages and stop behaviour.

[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: 8d33a31c-190e-4bb6-8284-18b4ec2746ad

• Autofix · 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@368

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

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

commit: 0401300

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[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: none · trace

[prisma-gizmo]

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