Merge pull request #15 from prisma/fix/project-resolution

fix(project): resolution hierarchy

Author: luanvdw

docs/product/cli-style-guide.md

@@ -64,12 +64,13 @@ Recommended symbols:
 Human-oriented command output in TTY mode should usually start with a compact header:
 
 ```text
-project link → Linking the current repo to an existing project.
+project show → Showing the project resolved for this directory.
 
 │  project:    Acme Dashboard
 │  workspace:  Acme Inc
+│  source:     package-name
 │
-│  Read more   docs/product/command-spec.md#prisma-cli-project-link-project
+│  Read more   docs/product/command-spec.md#prisma-cli-project-show
 ```
 
 Rules:

docs/product/command-principles.md

@@ -83,23 +83,12 @@ Change local CLI context only.
 
 `use` must never mutate a remote resource.
 
-`use` is intentionally different from `link`:
-
-- `use` changes local active context only
-- `link` binds local repo context to an existing remote resource
+`use` changes local active context only.
 
 Example:
 
 - `branch use production`
 
-### `link`
-
-Connect local repo context to an existing remote resource.
-
-Example:
-
-- `project link`
-
 ### `deploy`
 
 Build and release an app into a target branch.

docs/product/command-spec.md

@@ -39,7 +39,7 @@ Out of scope for the current preview:
 - Long flags use kebab-case.
 - Boolean negation uses `--no-<flag>`.
 - `--json` and non-interactive mode must not block on prompts.
-- `prisma.config.ts` stores only the linked project id.
+- Public Beta does not read or write `prisma.config.ts`, `.prisma/settings.json`, or any repo config file for Project -> Branch -> App resolution.
 - Remote commands do not silently change local context.
 
 ## Context Resolution
@@ -48,18 +48,23 @@ Out of scope for the current preview:
 
 Commands resolve project context in this order:
 
-1. linked project id in `prisma.config.ts`
-2. explicit `project link`
-3. implicit creation by `app deploy` when no project is linked
+1. explicit `--project <id-or-name>` when present
+2. durable platform mapping when available
+3. remembered local project context, revalidated against platform data
+4. `package.json` name matched exactly against accessible project id, name, or slug
+5. unambiguous project creation for commands that are allowed to create projects
+6. prompt in interactive mode, or structured failure in `--json` / `--no-interactive` mode
 
-Only `app deploy` may create project context implicitly.
+`--project` is an escape hatch for ambiguous or unavailable automatic
+resolution, not a setup step. Only `app deploy` may create a missing project,
+and only when the inferred name is unambiguous.
 
 ### App Selection
 
 Preview app commands that need an app resolve it in this order:
 
 1. `--app <name>`
-2. locally selected app for the linked project
+2. locally selected app for the resolved project
 3. interactive select-or-create flow in TTY mode
 4. `USAGE_ERROR` in non-interactive or `--json` mode when unresolved
 
@@ -107,8 +112,7 @@ In `--json`, `result` uses this shape:
   "workspace": {
     "id": "ws_123",
     "name": "Acme Inc"
-  },
-  "linkedProjectId": "proj_123"
+  }
 }
 ```
 
@@ -118,7 +122,6 @@ Rules:
 - `provider` is `github`, `google`, or `null`
 - `user` contains the current user email or is `null`
 - `workspace` is the active workspace or `null`
-- `linkedProjectId` is the linked project id for the current repo or `null`
 - signed-out state is an empty auth state, not an error
 
 ## `prisma-cli auth login`
@@ -189,7 +192,8 @@ Behavior:
 
 - requires auth
 - lists projects visible to the active workspace
-- marks the locally linked project when one is present
+- does not resolve the current directory
+- does not mutate local state
 
 Examples:
 
@@ -202,50 +206,35 @@ prisma-cli project list --json
 
 Purpose:
 
-- show the Prisma project linked to this directory
+- show the Prisma project resolved for this directory
 
 Behavior:
 
-- reads the linked project id from `prisma.config.ts`
-- requires auth when resolving remote project details
-- fails with `PROJECT_NOT_LINKED` when no project is linked
+- requires auth
+- resolves project context without creating projects
+- does not prompt for project selection
+- does not mutate local state
+- `--project <id-or-name>` resolves only the explicit project
+- returns Workspace, Project, and `resolution.projectSource`
+- fails with `PROJECT_UNRESOLVED`, `PROJECT_NOT_FOUND`, `PROJECT_AMBIGUOUS`, or `LOCAL_STATE_STALE` when resolution cannot continue safely
 
 Examples:
 
 ```bash
 prisma-cli project show
 prisma-cli project show --json
-```
-
-## `prisma-cli project link [project]`
-
-Purpose:
-
-- link this directory to a Prisma project
-
-Behavior:
-
-- writes only the project id to `prisma.config.ts`
-- prompts for a project when no project id is passed and prompting is allowed
-- fails with `USAGE_ERROR` when no project can be selected non-interactively
-- does not change active branch context
-
-Examples:
-
-```bash
-prisma-cli project link
-prisma-cli project link proj_123
+prisma-cli project show --project proj_123 --json
 ```
 
 ## `prisma-cli branch list`
 
 Purpose:
 
-- list active Platform branches linked to this project
+- list active Platform branches for the resolved project
 
 Behavior:
 
-- shows known remote branches for the linked project
+- shows known remote branches for the resolved project
 - marks active context
 - does not create remote state
 - does not expose branch `role` or `durability` fields yet
@@ -266,7 +255,7 @@ Purpose:
 Behavior:
 
 - reads local branch context
-- shows linked project context when known
+- shows resolved project context when known
 - does not mutate local or remote state
 - does not expose branch `role` or `durability` fields yet
 
@@ -347,7 +336,7 @@ prisma-cli app deploy --app hello-world --build-type tanstack-start
 
 ## `prisma-cli project env`
 
-Manage durable, platform-stored environment variables for the linked
+Manage durable, platform-stored environment variables for the resolved
 project. Replaces the legacy `prisma app update-env` / `prisma app
 list-env` workflow, which mutated env vars on a single Foundry version
 and is now deprecated. The `env` namespace operates on the
@@ -373,9 +362,10 @@ Purpose:
 
 Behavior:
 
-- requires auth and a linked project
+- requires auth and a resolved project; accepts `--project <id-or-name>` as an explicit fallback
 - KEY=VALUE is parsed from a single positional; KEY must match
   `[A-Z_][A-Z0-9_]*`
+- KEY without `=VALUE` reads the value from the current process environment
 - if a variable with the same key already exists in the scope, the
   command fails with a clear error directing to `env update`
 - the response carries metadata only — the value is never echoed back
@@ -385,6 +375,7 @@ Examples:
 ```bash
 prisma-cli project env add STRIPE_KEY=sk_test_xxx --role production
 prisma-cli project env add STRIPE_KEY=sk_test_xxx --role preview
+API_URL=https://api.example prisma-cli project env add API_URL --project proj_123 --role preview
 ```
 
 ### `prisma-cli project env update KEY=VALUE --role <production|preview>`
@@ -396,9 +387,10 @@ Purpose:
 
 Behavior:
 
-- requires auth and a linked project
+- requires auth and a resolved project; accepts `--project <id-or-name>` as an explicit fallback
 - KEY=VALUE is parsed from a single positional; KEY must match
   `[A-Z_][A-Z0-9_]*`
+- KEY without `=VALUE` reads the value from the current process environment
 - if no variable with the key exists in the scope, the command fails
   with a clear error directing to `env add`
 - the response carries metadata only — the value is never echoed back
@@ -418,7 +410,7 @@ Purpose:
 
 Behavior:
 
-- requires auth and a linked project
+- requires auth and a resolved project; accepts `--project <id-or-name>` as an explicit fallback
 - defaults to `--role production` when `--role` is not supplied
 - never prints values (never-reveal)
 - emits `key`, `id`, `last updated`, and a `scope` annotation per row
@@ -438,7 +430,7 @@ Purpose:
 
 Behavior:
 
-- requires auth and a linked project
+- requires auth and a resolved project; accepts `--project <id-or-name>` as an explicit fallback
 - looks the variable up by natural key in the scope and `DELETE`s it
 - returns a focused error when no matching variable exists
 

docs/product/error-conventions.md

@@ -147,8 +147,10 @@ These codes are the minimum stable set for the MVP:
 
 - `USAGE_ERROR`
 - `AUTH_REQUIRED`
-- `PROJECT_NOT_LINKED`
+- `PROJECT_UNRESOLVED`
 - `PROJECT_NOT_FOUND`
+- `PROJECT_AMBIGUOUS`
+- `LOCAL_STATE_STALE`
 - `BRANCH_NOT_DEPLOYABLE`
 - `DEPLOYMENT_NOT_FOUND`
 - `NO_DEPLOYMENTS`
@@ -166,8 +168,10 @@ Recommended meanings:
 
 - `USAGE_ERROR`: invalid arguments or invalid command combination
 - `AUTH_REQUIRED`: command needs an authenticated session
-- `PROJECT_NOT_LINKED`: command needs project context and none is linked
+- `PROJECT_UNRESOLVED`: command needs project context and none could be resolved
 - `PROJECT_NOT_FOUND`: requested project does not exist or is not accessible
+- `PROJECT_AMBIGUOUS`: multiple safe project candidates matched
+- `LOCAL_STATE_STALE`: remembered local project context no longer matches platform data and continuing would be ambiguous
 - `BRANCH_NOT_DEPLOYABLE`: command tried to deploy to a non-deployable branch context
 - `DEPLOYMENT_NOT_FOUND`: requested deployment id does not exist
 - `NO_DEPLOYMENTS`: command resolved a branch or app but found no deployments

docs/product/output-conventions.md

@@ -67,7 +67,6 @@ Current MVP commands map to patterns like this:
 | `auth whoami` | `show` |
 | `project list` | `list` |
 | `project show` | `show` |
-| `project link` | `mutate` |
 | `branch list` | `list` |
 | `branch show` | `show` |
 | `branch use` | `mutate` |
@@ -99,7 +98,6 @@ Rules:
 - each list row uses `⚬` and repeats the same item noun
 - annotations are limited to one per row and use:
   - `(active)` for current context
-  - `(linked)` for the current local repo binding
   - `(default)` when the command defines a default item
 - human output prefers display labels over opaque ids
 - empty lists render a single dim sentence in the item area such as `No projects found.`
@@ -122,7 +120,7 @@ In `--json`, all list commands use this result shape:
 }
 ```
 
-`status` may be `"active"`, `"linked"`, or `null`.
+`status` may be `"active"`, `"default"`, or `null`.
 
 #### `show`
 
@@ -219,12 +217,13 @@ Human output should:
 Recommended header shape:
 
 ```text
-project link → Linking the current repo to an existing project.
+project show → Showing the project resolved for this directory.
 
 │  project:    Acme Dashboard
 │  workspace:  Acme Inc
+│  source:     package-name
 │
-│  Read more   docs/product/command-spec.md#prisma-cli-project-link-project
+│  Read more   docs/product/command-spec.md#prisma-cli-project-show
 ```
 
 Rules:
@@ -238,7 +237,7 @@ Rules:
 Recommended summary lines:
 
 ```text
-✔ Project linked
+✔ Project resolved
 ✘ Authentication required [AUTH_REQUIRED]
 ```
 

docs/product/resource-model.md

@@ -31,24 +31,16 @@ Preview relevance:
 
 ### Project
 
-`project` is the remote Prisma resource linked to a local repo.
+`project` is the remote Prisma resource resolved for local work.
 
 Rules:
 
 - `project` is not the same thing as `app`
-- `prisma.config.ts` stores only the linked project id
-- `app deploy` may create project context when none is linked
+- Public Beta does not read or write `prisma.config.ts`, `.prisma/settings.json`, or any repo config file for project resolution
+- `app deploy` may create missing project context only when resolution is unambiguous
 - other commands must not create project context implicitly
 - everything under a project happens in a branch
 
-Example config:
-
-```ts
-export default {
-  project: "proj_123",
-};
-```
-
 ### Branch
 
 `branch` is the named project-scoped isolation boundary for app and database
@@ -107,7 +99,7 @@ accidental destructive actions.
 Rules:
 
 - `app` is not the same thing as `project`
-- the app belongs to the linked project
+- the app belongs to the resolved project
 - app work is scoped by branch in the platform model
 - the app may be selected or created as part of app deployment workflows
 - app selection is local CLI state when needed for the preview package
@@ -187,26 +179,31 @@ Long-term, branch is where app and database relationships meet.
 - `local` is CLI context, not a branch or deploy target
 - `production` is protected and durable
 - every other named branch is preview by default
-- `prisma.config.ts` stores only the linked project id
+- Public Beta does not use repo config files for Project -> Branch -> App resolution
 
 ## Resolution Rules
 
 ### Project Resolution
 
 Commands resolve project context in this order:
 
-1. linked project id in `prisma.config.ts`
-2. explicit `project link`
-3. implicit creation by `app deploy` when no project is linked
+1. explicit `--project <id-or-name>` when present
+2. durable platform mapping when available
+3. remembered local project context, revalidated against platform data
+4. `package.json` name matched exactly against accessible project id, name, or slug
+5. unambiguous project creation for commands that are allowed to create projects
+6. prompt in interactive mode, or structured failure in `--json` / `--no-interactive` mode
 
-Only `app deploy` may create projects implicitly.
+Remembered local project context is an internal convenience after successful
+resolution. It must be revalidated before use and must not be described to users
+as durable linking. Only `app deploy` may create projects implicitly.
 
 ### App Selection Resolution
 
 Preview app commands that need an app resolve it in this order:
 
 1. explicit `--app <name>`
-2. locally selected app for the linked project
+2. locally selected app for the resolved project
 3. interactive selection or creation in a TTY
 4. structured usage error when no app can be resolved non-interactively
 
@@ -229,7 +226,7 @@ Consequences:
 Commands that inspect deployments resolve in this order:
 
 1. exact deployment id if the command accepts one
-2. selected app for the linked project
+2. selected app for the resolved project
 3. latest known live deployment for that app
 
 ### Promote Resolution