fix(app): resolve management-command branch to the project default (#91)

## Problem

`app show`, `logs`, `list-deploys`, `open`, `promote`, `rollback`, and
`remove` scope the app lookup to a single branch via `GET
/v1/compute-services?projectId=…&branchGitName=…`. The branch is
resolved as `--branch` → active git branch → literal `main` (per
`command-spec.md`).

The management API returns an empty page (HTTP 200, `data: []`) when
`branchGitName` matches no live branch. So an app deployed via git-push
whose default/production branch is not `main` — e.g. `master` — is
invisible to these commands unless the caller happens to be on a local
`master` checkout:

```
$ prisma-cli app logs --project proj_…
✘ No deployments available to stream logs [NO_DEPLOYMENTS]
```

The control plane and management API are correct; the app, its branch
(`master`, `isDefault: true`), and its versions all exist. The defect is
the CLI's branch resolution.

## Fix

Management commands never create branches, so they now resolve the
branch they read against the project's actual branches:

1. `--branch <name>` — honored as-is
2. the active git branch — only when a branch with that name exists in
the project
3. the project's default (production) branch — from `GET
/v1/projects/:id/branches`

This drops the implicit `main` fallback for read commands. Deploy is
unchanged.

- `src/lib/app/read-branch.ts` (new): read-only `resolveReadBranch` —
match by name, else default branch, else null. Lives in its own module
so the existing `preview-provider` test mocks don't need to stub it.
- `src/controllers/app.ts`: `resolveProjectContext` resolves the
inferred branch via the API.
- `docs/product/command-spec.md`: branch-resolution spec updated (the
`main` fallback was documented; management commands now resolve
existing-or-default).

## Testing

- `tests/read-branch.test.ts` (new): match / default-fallback /
no-branches.
- Updated the shared `verboseContext.branch` expectation in
`tests/app-controller.test.ts` (now carries the resolved branch id +
role).
- Full suite: **484 passing**. `tsc --noEmit` clean. Biome clean on
changed lines.

## Note

Even once merged, `bunx @prisma/cli@latest` only picks this up after a
release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: kristof-siket

docs/product/command-spec.md

@@ -135,12 +135,24 @@ resolved production Branch and fail when none exists.
 
 ### Branch
 
-Commands that use branch context resolve it in this order:
+Deploy resolves the branch it writes to in this order:
 
 1. explicit branch argument or `--branch <name>` when the command accepts one
 2. active Git branch for local deploy workflows
 3. `main`
 
+App management commands (`show`, `open`, `logs`, `list-deploys`, `promote`,
+`rollback`, `remove`) never create branches, so they resolve the branch they
+read in this order:
+
+1. explicit `--branch <name>` when the command accepts one, honored as-is
+2. the active Git branch when a branch with that name exists in the project
+3. the project's default (production) branch
+
+Resolving the default branch from the project keeps a git-push app deployed on
+a non-`main` default branch (for example `master`) visible to management
+commands regardless of the local Git branch.
+
 `local` is local CLI context only. It is never a branch or deploy target.
 Production is a protected durable branch and must require explicit user intent.
 

packages/cli/src/controllers/app.ts

@@ -86,6 +86,7 @@ import {
   runLocalApp,
 } from "../lib/app/local-dev";
 import { enforceProductionDeployGate } from "../lib/app/production-deploy-gate";
+import { resolveReadBranch } from "../lib/app/read-branch";
 import { readAuthState } from "../lib/auth/auth-ops";
 import { getApiBaseUrl, SERVICE_TOKEN_ENV_VAR } from "../lib/auth/client";
 import { requireComputeAuth } from "../lib/auth/guard";
@@ -3279,15 +3280,27 @@ async function resolveProjectContext(
     throw projectResolutionErrorToCliError(resolvedResult.error);
   }
   const resolved = resolvedResult.value;
-  const branch =
+  const requested =
     options?.branch ?? (await resolveDeployBranch(context, undefined));
 
+  // An explicit --branch is honored as-is. An inferred branch (active Git
+  // branch or the default) is resolved against the project's branches and
+  // falls back to the default branch so a git-push app on a non-`main`
+  // default branch stays visible.
+  const remoteBranch = options?.branch
+    ? null
+    : await resolveReadBranch(client, {
+        projectId: resolved.project.id,
+        branchName: requested.name,
+        signal: context.runtime.signal,
+      });
+
   return {
     ...resolved,
-    branch: {
+    branch: remoteBranch ?? {
       id: null,
-      name: branch.name,
-      kind: toBranchKind(branch.name),
+      name: requested.name,
+      kind: toBranchKind(requested.name),
     },
   };
 }

packages/cli/src/lib/app/read-branch.ts

@@ -0,0 +1,52 @@
+import type { ManagementApiClient } from "@prisma/management-api-sdk";
+
+import type { BranchKind } from "../../types/branch";
+
+export interface ReadBranch {
+  id: string;
+  name: string;
+  kind: BranchKind;
+}
+
+/**
+ * Resolves the branch an app management command should read from, without ever
+ * creating one. Returns the branch whose `gitName` matches `branchName`, else
+ * the project's default branch, else null when the project has no branches.
+ */
+export async function resolveReadBranch(
+  client: ManagementApiClient,
+  options: { projectId: string; branchName: string; signal?: AbortSignal },
+): Promise<ReadBranch | null> {
+  const branches: Array<{
+    id: string;
+    gitName: string;
+    isDefault: boolean;
+    role: BranchKind;
+  }> = [];
+  let cursor: string | undefined;
+
+  do {
+    const result = await client.GET("/v1/projects/{projectId}/branches", {
+      params: { path: { projectId: options.projectId }, query: { cursor } },
+      signal: options.signal,
+    });
+    if (result.error || !result.data) {
+      throw new Error(
+        `Failed to list branches for project ${options.projectId}: ${JSON.stringify(result.error)}`,
+      );
+    }
+
+    branches.push(...result.data.data);
+    cursor = result.data.pagination.hasMore
+      ? (result.data.pagination.nextCursor ?? undefined)
+      : undefined;
+  } while (cursor);
+
+  const chosen =
+    branches.find((branch) => branch.gitName === options.branchName) ??
+    branches.find((branch) => branch.isDefault) ??
+    null;
+  return chosen
+    ? { id: chosen.id, name: chosen.gitName, kind: chosen.role }
+    : null;
+}

packages/cli/tests/app-controller.test.ts

@@ -71,9 +71,9 @@ function expectedAppVerboseContext() {
       name: "Acme Dashboard",
     },
     branch: {
-      id: null,
+      id: "branch_main",
       name: "main",
-      kind: "production",
+      kind: "preview",
     },
     resolution: {
       projectSource: "local-pin",

packages/cli/tests/helpers/mock-factories.ts

@@ -55,6 +55,7 @@ export function createProjectClient(
                   options.branchExists === false
                     ? []
                     : [branchRecord(branchName)],
+                pagination: { hasMore: false, nextCursor: null },
               },
             };
           }

packages/cli/tests/read-branch.test.ts

@@ -0,0 +1,150 @@
+import type { ManagementApiClient } from "@prisma/management-api-sdk";
+import { describe, expect, it, vi } from "vitest";
+
+import { resolveReadBranch } from "../src/lib/app/read-branch";
+
+type RawBranch = {
+  id: string;
+  gitName: string;
+  isDefault: boolean;
+  role: "production" | "preview";
+};
+
+function pageResponse(branches: RawBranch[], nextCursor: string | null) {
+  return {
+    data: {
+      data: branches,
+      pagination: { hasMore: nextCursor !== null, nextCursor },
+    },
+  };
+}
+
+function clientReturning(branches: RawBranch[]): ManagementApiClient {
+  return {
+    GET: vi.fn().mockResolvedValue(pageResponse(branches, null)),
+  } as unknown as ManagementApiClient;
+}
+
+describe("resolveReadBranch", () => {
+  it("returns the branch whose gitName matches the request", async () => {
+    const client = clientReturning([
+      {
+        id: "b_master",
+        gitName: "master",
+        isDefault: true,
+        role: "production",
+      },
+      { id: "b_feat", gitName: "feat/x", isDefault: false, role: "preview" },
+    ]);
+
+    const result = await resolveReadBranch(client, {
+      projectId: "proj_1",
+      branchName: "feat/x",
+    });
+
+    expect(result).toEqual({ id: "b_feat", name: "feat/x", kind: "preview" });
+  });
+
+  it("falls back to the default branch when the requested branch does not exist", async () => {
+    const client = clientReturning([
+      {
+        id: "b_master",
+        gitName: "master",
+        isDefault: true,
+        role: "production",
+      },
+    ]);
+
+    const result = await resolveReadBranch(client, {
+      projectId: "proj_1",
+      branchName: "main",
+    });
+
+    expect(result).toEqual({
+      id: "b_master",
+      name: "master",
+      kind: "production",
+    });
+  });
+
+  it("returns null when the project has no branches", async () => {
+    const client = clientReturning([]);
+
+    const result = await resolveReadBranch(client, {
+      projectId: "proj_1",
+      branchName: "main",
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("throws when the branches request fails", async () => {
+    const client = {
+      GET: vi.fn().mockResolvedValue({
+        error: { message: "Unauthorized" },
+        response: { status: 401 },
+      }),
+    } as unknown as ManagementApiClient;
+
+    await expect(
+      resolveReadBranch(client, { projectId: "proj_1", branchName: "main" }),
+    ).rejects.toThrow();
+  });
+
+  it("follows pagination to a branch on a later page", async () => {
+    const GET = vi
+      .fn()
+      .mockResolvedValueOnce(
+        pageResponse(
+          [
+            {
+              id: "b_main",
+              gitName: "main",
+              isDefault: true,
+              role: "production",
+            },
+          ],
+          "cursor_1",
+        ),
+      )
+      .mockResolvedValueOnce(
+        pageResponse(
+          [
+            {
+              id: "b_feat",
+              gitName: "feat/x",
+              isDefault: false,
+              role: "preview",
+            },
+          ],
+          null,
+        ),
+      );
+    const client = { GET } as unknown as ManagementApiClient;
+
+    const result = await resolveReadBranch(client, {
+      projectId: "proj_1",
+      branchName: "feat/x",
+    });
+
+    expect(result).toEqual({ id: "b_feat", name: "feat/x", kind: "preview" });
+    expect(GET).toHaveBeenCalledTimes(2);
+    expect(GET).toHaveBeenNthCalledWith(
+      1,
+      "/v1/projects/{projectId}/branches",
+      expect.objectContaining({
+        params: { path: { projectId: "proj_1" }, query: { cursor: undefined } },
+      }),
+    );
+    expect(GET).toHaveBeenNthCalledWith(
+      2,
+      "/v1/projects/{projectId}/branches",
+      expect.objectContaining({
+        params: {
+          path: { projectId: "proj_1" },
+          query: { cursor: "cursor_1" },
+        },
+      }),
+    );
+  });
+});