Accept a deployed app's addresses as command subjects: prisma service logs @pr-42:shop.api

docs/product/command-principles.md

@@ -117,6 +117,8 @@ Resolve a service version and show or stream its logs.
 
 A command that operates on a subject resource takes that resource's identifier as its first positional argument (`service show my-api`, `postgres delete db_123`, `service version promote cpv_123`) — the established convention across CLIs. Flags never name the subject; they scope or qualify it (`--project`, `--branch`, `--role`). The argument primarily targets the stable platform id, with the display name as a secondary fallback: an id match always wins, and a resource named like another resource's id can never shadow it. Environment variables never target a subject. When the subject's identifier is globally unique — a service version id, a bucket id — the id alone is the complete target, and the command asks for no redundant parent scope.
 
+A Project, service, database or bucket that Prisma Composer deployed can also be named by its address: the name the app gave it, such as `shop.api`. The address is the row's `logicalId`, and its first `.`-separated part is the app, which is the Project's `logicalId`. On the command line the subject is `@`, then an optional environment and `:`, then the address: `@pr-42:shop.api`. The environment is the one the app was deployed to: the git name of one of the Project's Branches. Leaving it out, or writing `production`, means the Project's default Branch (the Branch with `isDefault` set), so `@shop.api` is production. This is the default Branch, not the Branch whose role is `production`, and not a Branch whose git name is `production`; a non-default Branch with that git name cannot be named by address. A Project's address is the app name alone, with no environment (`@shop`), because a Project spans every Branch. With an address, a destructive command's `--confirm` takes the address as typed (`postgres delete @pr-42:shop.db --confirm @pr-42:shop.db`), and its question names the row id, the environment and the Branch, saying plainly when that is production. `--project` and `--branch` cannot be combined with an address, because the address already names both.
+
 ### `wait`
 
 Block until a remote resource reaches a terminal state.

docs/reference/error-reference.md

@@ -14,6 +14,7 @@ Namespaces:
 
 | Namespace | Covers |
 | --- | --- |
+| `ADDRESS` | Naming a Project, service, database or bucket by its address (`@<environment>:<address>`) instead of its id |
 | `AUTH` | Workspace authentication and sessions (`prisma auth`, credential resolution) |
 | `BRANCH` | Branch listing (`prisma branch`) |
 | `BUCKET` | Bucket and bucket-key management (`prisma bucket`) |
@@ -27,6 +28,30 @@ Namespaces:
 | `SERVICE` | Deployed service management (`prisma service`) |
 | `SKILLS` | Agent-skill delivery (`prisma skills`) |
 
+## ADDRESS
+
+These codes cover a subject written as `@`, an optional environment and `:`, then an address: the name the app gave a Project, service, database or bucket, such as `shop.api`. The environment is the one the app was deployed to: a Branch's git name, or production (the default Branch) when left out. Any project, service, postgres or bucket command given an address can fail with these codes before its own lookup runs, so an `ADDRESS` code can replace the group's own not-found code: a script that handles a missing database on `postgres delete` also needs to handle `ADDRESS.NOT_FOUND`.
+
+### ADDRESS.AMBIGUOUS
+
+An address matched more than one row: more than one Project in the workspace carries the app name as its logical id, or more than one service, database or bucket on the environment's branch carries the full address. The nextActions list the matching ids to pass instead. Meta: `address`, `matches` (the `id` and `name` of each match).
+
+### ADDRESS.API_ERROR
+
+A Management API request made to look up an address (listing Projects, services, databases or buckets by logical id) failed. The `why` carries the API's message or HTTP status, and the fix is the API's hint when it sent one. A failed branch listing raises `BRANCH.API_ERROR` instead. Meta: `status`, `apiCode` (the API's own error code, when the response supplied one).
+
+### ADDRESS.NOT_FOUND
+
+An address named nothing: no Project in the workspace has the app name as its logical id, the Project has no branch for the environment (no default branch for production, or no branch with that git name), or nothing on that branch has the address. The nextActions point at `prisma project list`, `prisma branch list`, or `prisma deploy list`. Meta: `address`, plus `app`, `environment`, `projectId`, `branchId` or `expected` as they apply.
+
+### ADDRESS.USAGE_ERROR
+
+A subject starting with `@` is not a valid address (an empty environment before `:`, an empty address, an empty part between dots, or whitespace), an address was combined with `--project` or `--branch`, which the address already names, or a project command was given an address with an environment, which a Project's address never has. Meta: `address`, plus `flags` for the flag conflict.
+
+### ADDRESS.WRONG_KIND
+
+An address names a different kind of thing than the command acts on: a service, postgres or bucket command was given the bare app name (which names the Project) or the address of another kind of row, or a project command was given an address longer than the app name. The nextActions name the command group that acts on it. Meta: `address`, `expected`, `actual` (`project`, `service`, `database`, `bucket`, or `service, database or bucket` when a project command is given a longer address and the kind was not looked up).
+
 ## AUTH
 
 ### AUTH.CREDENTIAL_WORKSPACE_MISMATCH