[wmadden-electric]

Linked issue

n/a. Part of the local-dev work; the plan is in .drive/projects/emulator-commands/.

Summary

Scripts, docs and agents can ask where a locally running service is, instead of assuming its port:

$ prisma dev module.ts        # terminal 1: runs the app
$ prisma dev url gateway      # terminal 2
http://localhost:3001
$ prisma dev stop             # stops this directory's app; its data stays
$ prisma emulator list        # every local emulator on this machine, and what it runs

Decision: Composer adds three commands, prisma dev url, prisma dev stop and prisma emulator list. The first two are also programmatic operations, devUrl and devStop, on @prisma/composer/control. ADR-0053 records this.

Why

Local ports aren't fixed. prisma dev gives services the lowest free ports from 3000, in dependency order, and each directory keeps its own (#354). So localhost:3001 is right for one checkout on one machine and wrong for the next. Composer's getting-started page currently hard-codes curl localhost:3001. prisma dev url lets it ask instead.

Background

prisma dev runs an app against emulators: long-lived local stand-ins for Prisma Cloud, shared across the machine, which run its services, Postgres databases and buckets. Each part of the app is a node, and its address is its dotted name in the app, such as gateway or shop.quotes. #354 and #356 made prisma dev record, in .prisma-composer/dev/emulator-instances.json, which emulator instance runs each node of the app it last ran from that directory.

prisma dev url <address>

prisma dev url reads that record for the current directory and prints where the node answers:

• a service: http://localhost:<port>;
• a database: its local connection string, password included, since it's only useful with it and only works locally;
• a bucket: the bucket emulator's S3 endpoint plus /<bucket>. Access keys are never printed.

It prints a URL only while the node is running, so every URL it prints answers. Its JSON result is { address, kind, url, state }. Failures each have their own code:

Situation	Code
prisma dev never ran in this directory	DEV.NOT_STARTED_HERE
No node has that address (the known ones are listed)	DEV.ADDRESS_UNKNOWN
The node's emulator isn't running	DEV.EMULATOR_UNREACHABLE
The node exists but isn't running. The advice depends on why: it's stopped, so run prisma dev; it's crashing, so read its log; or its emulator lost it, so prisma dev re-creates it, empty	DEV.NOT_RUNNING

prisma dev stop

prisma dev stop stops the current directory's app, its service processes and its Postgres servers, as ending prisma dev does. Data and ports stay. It's for an agent cleaning up before deleting its checkout, or for a prisma dev that was killed before it could stop the app. It reports what it actually stopped.

prisma emulator list

prisma emulator list asks about the machine, not a project, so it needs no prisma.config.ts. For each emulator it shows:

• whether it is running, and its admin URL;
• its instances, with their id, kind, URL, state and labels. The labels show the directory and address that started each one.

An emulator that doesn't answer gets an error in its own entry, and the others are still listed.

How it fits Composer's layers

Composer's core doesn't know about any particular deploy target. devUrl and devStop therefore go through the local-target interface that core already has. It gains an optional current({ devDir }), which returns the directory's recorded app and lets core locate or stop its nodes. The Prisma Cloud target implements it from the record. emulator list has no project to start from, so it lives next to the emulator clients, and @prisma/composer-cli adds it to the command family.

Mounting and piping

These commands reach users once the prisma CLI mounts them. That needs @prisma/cli-engine 0.8.0, which lets prisma dev be both a command and a group (prisma/prisma-cli#349, merged).

Today a piped prisma command prints JSON, so the guide shows scripts using jq. prisma/prisma-cli#353 changes a pipe to get the plain URL, after which curl "$(prisma dev url gateway)" works directly.

Testing performed

• Through a real prisma.config.ts against real emulators (skipped on Windows):
  • devUrl returns a service URL that answers and a database connection string.
  • devStop stops exactly the app's nodes and closes their ports.
  • devUrl then fails with DEV.NOT_RUNNING.
• At the target level, against real Compute, Postgres and bucket emulators:
  • A service URL answers HTTP, a database URL answers select 1, and a bucket URL takes an S3 write and listing.
  • Stop reports only what it stopped.
  • Two directories are listed with their labels.
• Every error in the table above, over a fake target.
• emulator list with nothing running, with an emulator that doesn't answer, and with one that returns an HTTP 500.
• The commands' grammar, help and output.

Also pnpm build, typecheck, lint, lint:deps, lint:casts, the family import-graph check, and the packaging checks.

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

• Stacked on feat(dev): checkouts of one app get their own local databases and buckets, and prisma dev stops its Postgres servers on exit #356. It retargets to main as the stack merges.
• Docs updated: ADR-0053; ADR-0044 (three new DEV codes); local-dev.md; deploy-cli.md; the running-locally and deploying guides; the core-concepts skill. They say prisma emulator start and stop are planned.
• The prisma CLI now carries the emulator client. @prisma/composer-cli bundles it, and the emulators may have been started by a different Composer version. So the emulators' registry files and instance-list routes now have to stay backward compatible. ADR-0053 says so.
• emulator list's JSON departs from the CLI's usual list shape. It nests emulators and their instances, because an instance means nothing without its emulator.

Alternatives considered

• prisma emulator url <address>. It would behave the same, but it answers a question about this directory's app, which belongs under dev. The emulator commands are about the machine.
• A top-level prisma url. It's ambiguous between a local service and a deployed one.
• Naming the app on the command line, or with --app. Addresses are relative to the directory's app, and app names repeat across checkouts.
• emulator list through the local-target interface. That would require a project and a configuration for a question about the machine.

Agent: attila-51

🤖 Generated with Claude Code

[prisma-gizmo]

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

Open findings: none

Change walkthrough

This incremental pass reviewed the delta since the last reviewed commit: a coordinated dependency/version-bump block across the workspace, plus design-doc, guide, skill, and integration-test updates. It does not touch the dev url/dev stop/emulator list implementation itself.

Version and dependency bumps. Every workspace manifest moves from 0.29.1 to 0.30.0 (the minor bump produced by scripts/bump-minior.ts's procedure via set-version.ts), with coordinated dependency upgrades: alchemy 2.0.0-beta.78 → beta.83, effect 4.0.0-rc.115 → 4.0.3, @prisma/orm-postgres/orm-toolchain rc.17 → rc.18, @distilled.cloud/prisma rc.12 → rc.15, and vitest ^4 → ^5. I verified these pins are consistent across all packages, examples, test/integration, and the website — no manifest was left behind, and the lockfile-adjacent checks the repo runs (check-npm-effect-resolution, check-orm-pins, check-publish-deps, check:cli-engine-pin) map onto exactly these files. @prisma/composer-cli deliberately keeps its @prisma/cli-engine 0.7.0 peer/dev pin, matching the PR's stated constraint that the family waits on the CLI's 0.8.0.

Docs. docs/design/10-domains/local-dev.md refines the concurrent-starts rules: a start whose process has already exited no longer accepts waiters, so a session-resume or identical-deployment PUT arriving in that window starts the service again — the prose and the two qualified table rows agree with each other and with the readiness/crash-loop rules earlier in the section. docs/guides/deploying.md documents the node-address-as-logicalId identity semantics (address is the identity; renaming or re-homing a node makes a new entity and deletes the old rows, data included) and updates the effect pin in the hoisting-resolution recipe. The same identity paragraph lands in skills/prisma-composer-core-concepts/SKILL.md alongside the version stamp, and the two docs stay consistent.

Tests. test/integration/test/control.dev-current.test.ts hardens the port-skip placeholder-instance setup: a failed creation now throws with the status and response body before the unchecked { port } JSON parse, turning a silent bad-port path into a clear setup error.

[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: 66f7b7f2-6d09-4a71-870e-c6a336ed2390

• 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@357

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

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

commit: 3141896

[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: none · 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 Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

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

[prisma-gizmo]

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