feat(cli): add project rename, remove, and transfer (#107)

Completes the `project` group's remote lifecycle: rename, remove, and
transfer. Spec-first (`command-spec.md` + `resource-model.md` updated in
the same change).

```bash
$ prisma-cli project rename "Acme Dashboard v2"
✔ Renamed. Directory bindings pin the project id, so they stay valid.

$ prisma-cli project remove proj_999 --confirm proj_999
✔ The project, its databases, and its apps were removed.
  This directory's local project binding was cleared.

$ prisma-cli project transfer proj_123 --to-workspace "Prisma Labs" --confirm proj_123
✔ The project now belongs to the recipient workspace.
  This directory's local project binding now points at the recipient workspace.
```

Design notes
- The transfer API authorizes with a recipient *access token*, not a
workspace id. `--to-workspace` resolves a locally stored OAuth session
(same targets as `auth workspace use`) through a new workspace-pinned
`FileTokenStorage` view that refreshes via the SDK and can never move
the active-workspace selection; `--recipient-token` is the
cross-account/headless path. Under `PRISMA_SERVICE_TOKEN`,
`--to-workspace` fails with `TRANSFER_RECIPIENT_UNAVAILABLE`.
- Remove and transfer take an explicit positional target (never the
bound project) plus exact-id `--confirm`.
- Local pin hygiene: remove clears a matching `.prisma/local.json`;
transfer rewrites it to the recipient workspace when known, else clears
it; both best-effort with warnings.
- Structured codes: `PROJECT_REMOVE_BLOCKED` (active deployments),
`PROJECT_TRANSFER_REJECTED`, `PROJECT_RENAME_FAILED`,
`TRANSFER_RECIPIENT_REQUIRED`/`_UNAVAILABLE`, `CONFIRMATION_REQUIRED`
with meta.

Testing: 14 new integration tests, full suite green, and all three
commands verified against the live Management API with scratch projects,
including a real cross-workspace transfer (project visible in the
recipient workspace, pin rewritten, cleaned up afterwards).

Note: merge after #106 or rebase; both touch `mock-api.ts`/fixtures.

Author: AmanVarshney01

docs/product/command-spec.md

@@ -696,6 +696,85 @@ prisma-cli project link proj_123
 prisma-cli project link "Acme Dashboard" --json
 ```
 
+## `prisma-cli project rename <name> --project <id-or-name>`
+
+Purpose:
+
+- rename the resolved Prisma Project
+
+Behavior:
+
+- requires auth
+- renames the resolved Project; accepts `--project <id-or-name>` as an explicit fallback and otherwise uses the directory's durable Project binding
+- requires a non-empty `<name>`
+- renames the remote Project only; `.prisma/local.json` pins Project IDs, so existing directory bindings stay valid without rewrite
+- returns the previous and new name
+- does not mutate any other remote resource
+- fails with `PROJECT_NOT_FOUND`, `PROJECT_AMBIGUOUS`, or `PROJECT_SETUP_REQUIRED` when the Project cannot be resolved safely
+- fails with `PROJECT_RENAME_FAILED` when the platform rejects the rename
+
+Examples:
+
+```bash
+prisma-cli project rename "Acme Dashboard v2"
+prisma-cli project rename billing-api --project proj_123
+prisma-cli project rename billing-api --json
+```
+
+## `prisma-cli project remove <project> --confirm <project-id>`
+
+Purpose:
+
+- remove a Prisma Project permanently
+
+Behavior:
+
+- requires auth
+- resolves `<project>` by exact Project id or exact Project name inside the active workspace
+- never defaults to the directory's bound Project: the positional target is required, because removal is destructive
+- requires `--confirm <project-id>` where the value exactly matches the resolved Project id; `--yes` does not satisfy this confirmation
+- removal is permanent: the Project's databases are deleted and its Apps stop being served
+- fails with `PROJECT_REMOVE_BLOCKED` when the platform reports the Project still has active deployments; remove or tear down the Apps first
+- when this directory's `.prisma/local.json` pin points at the removed Project, the pin is cleared and the result reports it
+- fails with `PROJECT_NOT_FOUND` or `PROJECT_AMBIGUOUS` when the target cannot be selected safely
+
+Examples:
+
+```bash
+prisma-cli project remove proj_123 --confirm proj_123
+prisma-cli project remove "Old Sandbox" --confirm proj_456
+prisma-cli project remove proj_123 --confirm proj_123 --json
+```
+
+## `prisma-cli project transfer <project> (--to-workspace <id-or-name> | --recipient-token <token>) --confirm <project-id>`
+
+Purpose:
+
+- transfer a Prisma Project to another workspace
+
+Behavior:
+
+- requires auth
+- resolves `<project>` by exact Project id or exact Project name inside the active workspace; the positional target is required and never defaults to the directory's bound Project
+- exactly one recipient source is required:
+  - `--to-workspace <id-or-name>` resolves a locally authenticated OAuth workspace, the same targets `auth workspace use` accepts, and authorizes the transfer with that workspace's stored session; this is the same-user path
+  - `--recipient-token <token>` passes an access token for the receiving workspace directly; this is the cross-account and headless path
+- `--to-workspace` and `--recipient-token` are mutually exclusive; passing neither fails with `TRANSFER_RECIPIENT_REQUIRED`
+- `--to-workspace` fails with `WORKSPACE_NOT_AUTHENTICATED` or `WORKSPACE_AMBIGUOUS` when no unique local OAuth session matches, and with `TRANSFER_RECIPIENT_UNAVAILABLE` when `PRISMA_SERVICE_TOKEN` is set, because service-token mode does not read local OAuth sessions
+- requires `--confirm <project-id>` where the value exactly matches the resolved Project id; `--yes` does not satisfy this confirmation
+- after the transfer the Project belongs to the recipient workspace and the source workspace loses access; Project, Branch, App, and database ids are unchanged
+- when this directory's `.prisma/local.json` pin points at the transferred Project: with `--to-workspace` the pin's workspace id is rewritten to the recipient workspace, otherwise the pin is cleared; the result reports which happened
+- fails with `PROJECT_TRANSFER_REJECTED` when the platform rejects the transfer, for example an invalid or expired recipient token
+- fails with `PROJECT_NOT_FOUND` or `PROJECT_AMBIGUOUS` when the target cannot be selected safely
+
+Examples:
+
+```bash
+prisma-cli project transfer proj_123 --to-workspace "Prisma Labs" --confirm proj_123
+prisma-cli project transfer proj_123 --recipient-token <token> --confirm proj_123
+prisma-cli project transfer proj_123 --to-workspace wksp_456 --confirm proj_123 --json
+```
+
 ## `prisma-cli git connect [git-url]`
 
 Purpose:

docs/product/error-conventions.md

@@ -168,6 +168,12 @@ These codes are the minimum stable set for the MVP:
 - `PROJECT_SETUP_REQUIRED`
 - `PROJECT_LINK_TARGET_REQUIRED`
 - `PROJECT_CREATE_FAILED`
+- `PROJECT_RENAME_FAILED`
+- `PROJECT_REMOVE_BLOCKED`
+- `PROJECT_TRANSFER_REJECTED`
+- `PROJECT_API_ERROR`
+- `TRANSFER_RECIPIENT_REQUIRED`
+- `TRANSFER_RECIPIENT_UNAVAILABLE`
 - `PROJECT_NOT_FOUND`
 - `PROJECT_AMBIGUOUS`
 - `APP_AMBIGUOUS`
@@ -233,6 +239,12 @@ Recommended meanings:
 - `PROJECT_SETUP_REQUIRED`: command needs explicit or durable Project context before it can continue
 - `PROJECT_LINK_TARGET_REQUIRED`: `project link` needs the user to choose an existing Project or create a new one
 - `PROJECT_CREATE_FAILED`: Project creation failed before deployment or linking could continue
+- `PROJECT_RENAME_FAILED`: the platform rejected the new project name
+- `PROJECT_REMOVE_BLOCKED`: project removal is blocked while it still has active deployments
+- `PROJECT_TRANSFER_REJECTED`: the platform rejected the transfer, for example an invalid or expired recipient token
+- `PROJECT_API_ERROR`: project Management API request failed without a more specific CLI error code
+- `TRANSFER_RECIPIENT_REQUIRED`: project transfer needs --to-workspace or --recipient-token
+- `TRANSFER_RECIPIENT_UNAVAILABLE`: --to-workspace cannot resolve local OAuth sessions while PRISMA_SERVICE_TOKEN is set
 - `PROJECT_NOT_FOUND`: requested project does not exist or is not accessible
 - `PROJECT_AMBIGUOUS`: multiple safe project candidates matched
 - `APP_AMBIGUOUS`: multiple apps matched the inferred or explicit app target

docs/product/resource-model.md

@@ -42,6 +42,10 @@ Rules:
 - Project setup is explicit: users choose an existing Project or explicitly create a new one before remote work starts
 - `app deploy` may orchestrate Project setup, but it must not silently choose or create Project scope
 - everything under a project happens in a branch
+- `project rename` mutates only the remote Project name; pins bind by id and stay valid
+- `project remove` and `project transfer` take an explicit positional Project target and exact id confirmation with `--confirm <project-id>`; they never default to the directory's bound Project and `--yes` is not sufficient
+- removal is permanent and takes the Project's databases with it; transfer moves ownership to another workspace without changing resource ids
+- when a destructive Project command invalidates this directory's local pin, the CLI cleans the pin up (clear on remove; rewrite or clear on transfer) and reports it
 
 ### Branch
 

packages/cli/fixtures/mock-api.json

@@ -64,6 +64,13 @@
       "slug": "website",
       "url": "https://prisma.build/prisma/website",
       "workspaceId": "ws_456"
+    },
+    {
+      "id": "proj_999",
+      "name": "Sandbox",
+      "slug": "sandbox",
+      "url": "https://prisma.build/acme/sandbox",
+      "workspaceId": "ws_123"
     }
   ],
   "branches": [

packages/cli/src/adapters/mock-api.ts

@@ -156,6 +156,10 @@ export class MockApi {
     );
   }
 
+  listWorkspaces(): WorkspaceRecord[] {
+    return this.data.workspaces;
+  }
+
   getWorkspace(workspaceId: string): WorkspaceRecord | undefined {
     return this.data.workspaces.find(
       (workspace) => workspace.id === workspaceId,
@@ -190,6 +194,76 @@ export class MockApi {
     );
   }
 
+  renameProject(projectId: string, name: string): ProjectRecord | undefined {
+    const project = this.getProject(projectId);
+    if (!project) {
+      return undefined;
+    }
+
+    project.name = name;
+    return project;
+  }
+
+  removeProject(
+    projectId: string,
+  ):
+    | { outcome: "removed"; project: ProjectRecord }
+    | { outcome: "not-found" }
+    | { outcome: "blocked" } {
+    const project = this.getProject(projectId);
+    if (!project) {
+      return { outcome: "not-found" };
+    }
+
+    // Mirrors the platform rule: removal is blocked while the project still
+    // has active deployments.
+    const hasDeployments = this.data.deployments.some(
+      (deployment) => deployment.projectId === projectId,
+    );
+    if (hasDeployments) {
+      return { outcome: "blocked" };
+    }
+
+    const removedDatabaseIds = new Set(
+      (this.data.databases ?? [])
+        .filter((database) => database.projectId === projectId)
+        .map((database) => database.id),
+    );
+
+    this.data.projects = this.data.projects.filter(
+      (candidate) => candidate.id !== projectId,
+    );
+    this.data.branches = this.data.branches.filter(
+      (branch) => branch.projectId !== projectId,
+    );
+    this.data.databases = (this.data.databases ?? []).filter(
+      (database) => database.projectId !== projectId,
+    );
+    this.data.databaseConnections = (
+      this.data.databaseConnections ?? []
+    ).filter((connection) => !removedDatabaseIds.has(connection.databaseId));
+    return { outcome: "removed", project };
+  }
+
+  transferProject(
+    projectId: string,
+    targetWorkspaceId: string,
+  ):
+    | { outcome: "transferred"; project: ProjectRecord }
+    | { outcome: "not-found" }
+    | { outcome: "workspace-not-found" } {
+    const project = this.getProject(projectId);
+    if (!project) {
+      return { outcome: "not-found" };
+    }
+    if (!this.getWorkspace(targetWorkspaceId)) {
+      return { outcome: "workspace-not-found" };
+    }
+
+    project.workspaceId = targetWorkspaceId;
+    return { outcome: "transferred", project };
+  }
+
   listBranchesForProject(projectId: string): BranchRecord[] {
     return this.data.branches.filter(
       (branch) => branch.projectId === projectId,

packages/cli/src/adapters/token-storage.ts

@@ -48,6 +48,13 @@ export interface FileTokenStorageOptions {
   lockRetryMs?: number;
   lockStaleMs?: number;
   lockWaitTimeoutMs?: number;
+  /**
+   * Pin this storage view to one workspace's credentials. getTokens then
+   * ignores the active-workspace pointer, so an SDK built on a pinned view
+   * authenticates (and refreshes) as that workspace without touching the
+   * user's selected workspace.
+   */
+  pinnedWorkspaceId?: string;
 }
 
 const REFRESH_LOCK_RETRY_MS = 100;
@@ -178,6 +185,14 @@ export class FileTokenStorage implements TokenStorage {
     try {
       // CredentialsStore does not accept AbortSignal; check immediately before and after the boundary.
       const credentials = await this.readCredentialsFromDisk();
+
+      if (this.options.pinnedWorkspaceId) {
+        return findTokensForWorkspace(
+          credentials,
+          this.options.pinnedWorkspaceId,
+        );
+      }
+
       const context = await this.readAuthContext();
 
       if (context.state.activeWorkspaceId) {
@@ -273,6 +288,13 @@ export class FileTokenStorage implements TokenStorage {
     const credentials = await this.readCredentialsFromDisk();
     const context = await this.ensureMigratedAuthContext(credentials);
 
+    return this.workspacesFromState(credentials, context);
+  }
+
+  private workspacesFromState(
+    credentials: StoredCredential[],
+    context: AuthContextReadResult,
+  ): StoredAuthWorkspace[] {
     return credentials
       .map((credential) => storedCredentialToTokens(credential))
       .filter((tokens): tokens is Tokens => tokens !== null)
@@ -317,6 +339,38 @@ export class FileTokenStorage implements TokenStorage {
     return this.withRefreshLock(() => this.useWorkspaceUnlocked(workspaceRef));
   }
 
+  /**
+   * Resolve a workspace ref (id, credential workspace id, or cached name)
+   * against the locally stored sessions without changing the active
+   * workspace. Read-only counterpart of useWorkspace: it reads the auth
+   * context as-is and never runs the legacy-state migration, so it writes
+   * nothing.
+   */
+  async resolveWorkspace(workspaceRef: string): Promise<StoredAuthWorkspace> {
+    const ref = workspaceRef.trim();
+    if (!ref) {
+      throw new WorkspaceSelectionError("missing");
+    }
+
+    this.signal?.throwIfAborted();
+    const credentials = await this.readCredentialsFromDisk();
+    const context = await this.readAuthContext();
+    const workspaces = this.workspacesFromState(credentials, context);
+    const matches = workspaces.filter((workspace) =>
+      workspaceMatchesRef(workspace, ref),
+    );
+
+    if (matches.length === 0) {
+      throw new WorkspaceSelectionError("not-found", ref);
+    }
+
+    if (matches.length > 1) {
+      throw new WorkspaceSelectionError("ambiguous", ref, matches);
+    }
+
+    return matches[0];
+  }
+
   private async useWorkspaceUnlocked(workspaceRef: string): Promise<{
     previous: StoredAuthWorkspace | null;
     selected: StoredAuthWorkspace;
@@ -581,6 +635,13 @@ export class FileTokenStorage implements TokenStorage {
   }
 
   private async maybeActivateWorkspaceId(workspaceId: string): Promise<void> {
+    // A pinned view is a per-workspace read/refresh surface; its token writes
+    // must never move the user's workspace selection, even when no active
+    // workspace is set.
+    if (this.options.pinnedWorkspaceId) {
+      return;
+    }
+
     const context = await this.readAuthContext();
     if (
       this.options.activateOnSetTokens === false &&