feat(cli): app remove --branch and branch remove --cascade

Review feedback from #110:

- app remove now accepts --branch, honored as-is like the other
  read-branch commands, so branch cleanup can target apps on branches
  that are not checked out locally. The BRANCH_NOT_EMPTY recovery
  command previously pointed at this flag before it existed, which was
  a dead end.

- branch remove --cascade removes the branch's apps, then its
  databases, then the branch, for preview branches only: production
  and default branches stay refused before any member resource is
  touched. The result lists every removed resource (human output and
  result.removed in JSON) so the blast radius is explicit. Cascade is
  client-orchestrated because the platform's branch delete refuses
  non-empty branches; a mid-cascade failure stops immediately with
  BRANCH_CASCADE_INCOMPLETE, whose meta lists what was already removed.

- BRANCH_NOT_EMPTY recovery steps now offer the cascade rerun first,
  then individual app/database cleanup.

Author: AmanVarshney01

docs/product/command-spec.md

@@ -865,7 +865,7 @@ prisma-cli branch list
 prisma-cli branch list --json
 ```
 
-## `prisma-cli branch remove <branch> --project <id-or-name> --confirm <branch-id>`
+## `prisma-cli branch remove <branch> --project <id-or-name> --confirm <branch-id> --cascade`
 
 Purpose:
 
@@ -876,9 +876,11 @@ 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
+- production Branches and the project's default Branch are protected: removal fails with `BRANCH_PROTECTED`, and `--cascade` never widens that; the protection check runs before any member resource is touched
+- without `--cascade`, a Branch that still has live Apps or databases fails with `BRANCH_NOT_EMPTY`; plain removal never deletes member resources, and the recovery steps offer both the cascade rerun and individual `app remove --branch` / `database` cleanup
+- with `--cascade`, the CLI removes the Branch's Apps, then its databases, then the Branch itself; the result lists every removed resource so the blast radius is explicit, in human output and in `result.removed` for `--json`
+- cascade is client-orchestrated because the platform's branch delete refuses non-empty Branches; a mid-cascade failure stops immediately and fails with `BRANCH_CASCADE_INCOMPLETE`, whose `meta` lists what was already removed (removed resources are not restored, and the Branch itself remains)
+- removal is a platform soft-delete: the Branch disappears from `branch list`, and the platform owns retention of soft-deleted Branches; cascaded member resources are removed through their own APIs
 - 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
@@ -887,6 +889,7 @@ Examples:
 
 ```bash
 prisma-cli branch remove feat-login --confirm br_123
+prisma-cli branch remove feat-login --confirm br_123 --cascade
 prisma-cli branch remove br_123 --confirm br_123 --json
 ```
 
@@ -1854,16 +1857,18 @@ prisma-cli app rollback
 prisma-cli app rollback --app hello-world --to dep_123
 ```
 
-## `prisma-cli app remove [app] --app <name> -y --yes`
+## `prisma-cli app remove [app] --app <name> --branch <name> -y --yes`
 
 Purpose:
 
-- remove the app from the current branch
+- remove the app from the resolved branch
 
 Behavior:
 
 - requires auth and project context
-- resolves the selected app
+- resolves the branch it reads like the other management commands: explicit `--branch` honored as-is, then the active Git branch when it exists in the project, then the project's default branch
+- `--branch <name>` makes branch cleanup possible for branches that are not checked out locally, such as a teammate's preview branch
+- resolves the selected app within that branch
 - requires confirmation unless `-y` or `--yes` is passed
 - clears local selected app state when the removed app was selected
 

docs/product/error-conventions.md

@@ -184,6 +184,7 @@ These codes are the minimum stable set for the MVP:
 - `BRANCH_NOT_FOUND`
 - `BRANCH_PROTECTED`
 - `BRANCH_NOT_EMPTY`
+- `BRANCH_CASCADE_INCOMPLETE`
 - `COMPUTE_CONFIG_INVALID`
 - `COMPUTE_CONFIG_TARGET_REQUIRED`
 - `COMPUTE_CONFIG_TARGET_UNKNOWN`
@@ -258,6 +259,7 @@ Recommended meanings:
 - `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
+- `BRANCH_CASCADE_INCOMPLETE`: a --cascade branch removal failed partway; meta lists the resources already removed and the branch remains
 - `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

@@ -66,8 +66,11 @@ Rules:
 - 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
+  platform refuses production/default Branches outright, and plain removal
+  refuses Branches that still have live Apps or databases
+- `branch remove --cascade` removes a preview Branch's Apps and databases with
+  it, with the blast radius listed explicitly; production/default Branches stay
+  refused regardless of flags
 - `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

@@ -279,6 +279,55 @@ export class MockApi {
     );
   }
 
+  cascadeBranchResources(branchId: string): {
+    apps: Array<{ id: string; name: string }>;
+    databases: Array<{ id: string; name: string }>;
+  } {
+    const branch = this.data.branches.find(
+      (candidate) => candidate.id === branchId,
+    );
+    if (!branch) {
+      return { apps: [], databases: [] };
+    }
+
+    const databases = (this.data.databases ?? []).filter(
+      (database) => database.branchId === branchId,
+    );
+    const databaseIds = new Set(databases.map((database) => database.id));
+    // The fixture has no standalone app records; deployments on the branch
+    // stand in for its apps.
+    const apps = this.data.deployments.filter(
+      (deployment) =>
+        deployment.projectId === branch.projectId &&
+        deployment.branch === branch.name,
+    );
+
+    this.data.databases = (this.data.databases ?? []).filter(
+      (database) => database.branchId !== branchId,
+    );
+    this.data.databaseConnections = (
+      this.data.databaseConnections ?? []
+    ).filter((connection) => !databaseIds.has(connection.databaseId));
+    this.data.deployments = this.data.deployments.filter(
+      (deployment) =>
+        !(
+          deployment.projectId === branch.projectId &&
+          deployment.branch === branch.name
+        ),
+    );
+
+    return {
+      apps: apps.map((deployment) => ({
+        id: deployment.id,
+        name: deployment.id,
+      })),
+      databases: databases.map((database) => ({
+        id: database.id,
+        name: database.name,
+      })),
+    };
+  }
+
   removeBranch(
     branchId: string,
   ):

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

@@ -835,18 +835,21 @@ function createRemoveCommand(runtime: CliRuntime): Command {
       "App target from prisma.compute.ts when the config defines multiple apps",
     )
     .addOption(new Option("--app <name>", "App name"))
-    .addOption(new Option("--project <id-or-name>", "Project id or name"));
+    .addOption(new Option("--project <id-or-name>", "Project id or name"))
+    .addOption(new Option("--branch <name>", "Branch name"));
   addGlobalFlags(command);
 
   command.action(async (configTarget: string | undefined, options) => {
     const appName = (options as { app?: string }).app;
     const projectRef = (options as { project?: string }).project;
+    const branchName = (options as { branch?: string }).branch;
 
     await runCommand<AppRemoveResult>(
       runtime,
       "app.remove",
       options as Record<string, unknown>,
-      (context) => runAppRemove(context, appName, projectRef, configTarget),
+      (context) =>
+        runAppRemove(context, appName, projectRef, configTarget, branchName),
       {
         renderHuman: (context, descriptor, result) =>
           renderAppRemove(context, descriptor, result),

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

@@ -41,18 +41,26 @@ function createBranchRemoveCommand(runtime: CliRuntime): Command {
     .addOption(new Option("--project <id-or-name>", "Project id or name"))
     .addOption(
       new Option("--confirm <branch-id>", "Exact branch id required to remove"),
+    )
+    .addOption(
+      new Option(
+        "--cascade",
+        "Also remove the branch's apps and databases (preview branches only)",
+      ),
     );
   addGlobalFlags(command);
 
   command.action(async (branchRef: string, options) => {
     const projectRef = (options as { project?: string }).project;
     const confirm = (options as { confirm?: string }).confirm;
+    const cascade = (options as { cascade?: boolean }).cascade;
 
     await runCommand<BranchRemoveResult>(
       runtime,
       "branch.remove",
       options as Record<string, unknown>,
-      (context) => runBranchRemove(context, branchRef, { projectRef, confirm }),
+      (context) =>
+        runBranchRemove(context, branchRef, { projectRef, confirm, cascade }),
       {
         renderHuman: (context, descriptor, result) =>
           renderBranchRemove(context, descriptor, result),

packages/cli/src/controllers/app.ts

@@ -2043,6 +2043,7 @@ export async function runAppRemove(
   appName: string | undefined,
   projectRef?: string,
   configTarget?: string,
+  branchName?: string,
 ): Promise<CommandSuccess<AppRemoveResult>> {
   ensurePreviewAppMode(context);
 
@@ -2056,6 +2057,12 @@ export async function runAppRemove(
     await requireProviderAndProjectContext(context, projectRef, {
       commandName: "app remove",
       projectDir: compute.projectDir,
+      // Branch cleanup needs "remove this app from that branch" even when the
+      // branch is not checked out locally, so an explicit --branch is honored
+      // as-is like the other read-branch commands.
+      branch: branchName
+        ? await resolveDeployBranch(context, branchName)
+        : undefined,
     });
   const apps = await listApps(context, provider, projectId, target.branch.name);
   const selectedApp = await requireReleaseAppSelection(