feat(cli): add branch remove for preview branches

Preview branch cleanup previously required the Console. branch remove
takes an explicit branch id or git name in the resolved project, the
exact-id --confirm convention, and maps the platform's guarantees to
structured codes: BRANCH_PROTECTED for production/default branches
(422) and BRANCH_NOT_EMPTY when live apps or databases remain (409),
so removal never cascades into member resources. Removal is a platform
soft-delete and never touches local Git branches.

Branch creation deliberately stays implicit (git-push automation and
app deploy); there is no branch create, per team alignment.

Author: AmanVarshney01

docs/product/command-spec.md

@@ -786,6 +786,31 @@ prisma-cli branch list
 prisma-cli branch list --json
 ```
 
+## `prisma-cli branch remove <branch> --project <id-or-name> --confirm <branch-id>`
+
+Purpose:
+
+- remove a preview Branch from the resolved project
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<branch>` by exact Branch id or exact git name within the resolved project
+- requires `--confirm <branch-id>` where the value exactly matches the resolved Branch id; `--yes` does not satisfy this confirmation
+- production Branches and the project's default Branch are protected: removal fails with `BRANCH_PROTECTED`
+- a Branch that still has live Apps or databases fails with `BRANCH_NOT_EMPTY`; branch removal never deletes member resources, so remove the Branch's apps and databases first
+- removal is a platform soft-delete: the Branch disappears from `branch list`, and the platform owns retention of soft-deleted Branches
+- Branch creation stays implicit (git-push automation and `app deploy`); there is deliberately no `branch create`
+- never touches local Git branches
+- fails with `BRANCH_NOT_FOUND` when no Branch matches
+
+Examples:
+
+```bash
+prisma-cli branch remove feat-login --confirm br_123
+prisma-cli branch remove br_123 --confirm br_123 --json
+```
+
 ## `prisma-cli database list --project <id-or-name> --branch <git-name>`
 
 Purpose:

docs/product/error-conventions.md

@@ -175,6 +175,9 @@ These codes are the minimum stable set for the MVP:
 - `LOCAL_STATE_WRITE_FAILED`
 - `LOCAL_STATE_STALE`
 - `BRANCH_NOT_DEPLOYABLE`
+- `BRANCH_NOT_FOUND`
+- `BRANCH_PROTECTED`
+- `BRANCH_NOT_EMPTY`
 - `COMPUTE_CONFIG_INVALID`
 - `COMPUTE_CONFIG_TARGET_REQUIRED`
 - `COMPUTE_CONFIG_TARGET_UNKNOWN`
@@ -237,6 +240,9 @@ Recommended meanings:
 - `LOCAL_STATE_WRITE_FAILED`: the CLI could not save local Project binding state such as `.prisma/local.json` or the matching `.gitignore` entry; callers should fix directory permissions or filesystem state before retrying
 - `LOCAL_STATE_STALE`: local Project pin no longer matches platform data and continuing would be ambiguous
 - `BRANCH_NOT_DEPLOYABLE`: command tried to deploy to a non-deployable branch context
+- `BRANCH_NOT_FOUND`: requested branch id or git name does not exist in the resolved project
+- `BRANCH_PROTECTED`: branch removal refused because the branch is the project's production or default branch
+- `BRANCH_NOT_EMPTY`: branch removal refused because the branch still has live apps or databases
 - `COMPUTE_CONFIG_INVALID`: `prisma.compute.ts` failed to load or validate
 - `COMPUTE_CONFIG_TARGET_REQUIRED`: a multi-app compute config needs an `[app]` target and none was given or inferred
 - `COMPUTE_CONFIG_TARGET_UNKNOWN`: the `[app]` target matches no configured app

docs/product/resource-model.md

@@ -59,6 +59,11 @@ Rules:
 - every other named branch is a preview branch by default
 - preview branches are disposable by default
 - non-production branches can become durable later
+- Branch creation is implicit (git-push automation and `app deploy`); the CLI
+  has no `branch create`
+- `branch remove` removes a preview Branch with exact id confirmation; the
+  platform refuses production/default Branches and Branches that still have
+  live Apps or databases, so removal never cascades into member resources
 - `local` is local CLI context only, not a branch
 - branch context comes from explicit targeting, Git, or safe command defaults,
   not `prisma.config.ts`

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

@@ -183,6 +183,43 @@ export class MockApi {
     );
   }
 
+  removeBranch(
+    branchId: string,
+  ):
+    | { outcome: "removed"; branch: BranchRecord }
+    | { outcome: "not-found" }
+    | { outcome: "protected" }
+    | { outcome: "not-empty" } {
+    const branch = this.data.branches.find(
+      (candidate) => candidate.id === branchId,
+    );
+    if (!branch) {
+      return { outcome: "not-found" };
+    }
+    if (branch.role === "production") {
+      return { outcome: "protected" };
+    }
+
+    // Mirrors the platform rule: removal is refused while the branch still
+    // has live member resources.
+    const hasDatabases = (this.data.databases ?? []).some(
+      (database) => database.branchId === branchId,
+    );
+    const hasDeployments = this.data.deployments.some(
+      (deployment) =>
+        deployment.projectId === branch.projectId &&
+        deployment.branch === branch.name,
+    );
+    if (hasDatabases || hasDeployments) {
+      return { outcome: "not-empty" };
+    }
+
+    this.data.branches = this.data.branches.filter(
+      (candidate) => candidate.id !== branchId,
+    );
+    return { outcome: "removed", branch };
+  }
+
   getDeployment(deploymentId: string): DeploymentRecord | undefined {
     return this.data.deployments.find(
       (deployment) => deployment.id === deploymentId,

packages/cli/src/commands/branch/index.ts

@@ -1,15 +1,20 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 
-import { runBranchList } from "../../controllers/branch";
-import { renderBranchList, serializeBranchList } from "../../presenters/branch";
+import { runBranchList, runBranchRemove } from "../../controllers/branch";
+import {
+  renderBranchList,
+  renderBranchRemove,
+  serializeBranchList,
+  serializeBranchRemove,
+} from "../../presenters/branch";
 import { attachCommandDescriptor } from "../../shell/command-meta";
 import { runCommand } from "../../shell/command-runner";
 import {
   addCompactGlobalFlags,
   addGlobalFlags,
 } from "../../shell/global-flags";
 import { type CliRuntime, configureRuntimeCommand } from "../../shell/runtime";
-import type { BranchListResult } from "../../types/branch";
+import type { BranchListResult, BranchRemoveResult } from "../../types/branch";
 
 export function createBranchCommand(runtime: CliRuntime): Command {
   const branch = attachCommandDescriptor(
@@ -20,10 +25,45 @@ export function createBranchCommand(runtime: CliRuntime): Command {
   addCompactGlobalFlags(branch);
 
   branch.addCommand(createBranchListCommand(runtime));
+  branch.addCommand(createBranchRemoveCommand(runtime));
 
   return branch;
 }
 
+function createBranchRemoveCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("remove"), runtime),
+    "branch.remove",
+  );
+
+  command
+    .argument("<branch>", "Branch id or git name")
+    .addOption(new Option("--project <id-or-name>", "Project id or name"))
+    .addOption(
+      new Option("--confirm <branch-id>", "Exact branch id required to remove"),
+    );
+  addGlobalFlags(command);
+
+  command.action(async (branchRef: string, options) => {
+    const projectRef = (options as { project?: string }).project;
+    const confirm = (options as { confirm?: string }).confirm;
+
+    await runCommand<BranchRemoveResult>(
+      runtime,
+      "branch.remove",
+      options as Record<string, unknown>,
+      (context) => runBranchRemove(context, branchRef, { projectRef, confirm }),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderBranchRemove(context, descriptor, result),
+        renderJson: (result) => serializeBranchRemove(result),
+      },
+    );
+  });
+
+  return command;
+}
+
 function createBranchListCommand(runtime: CliRuntime): Command {
   const command = attachCommandDescriptor(
     configureRuntimeCommand(new Command("list"), runtime),