fix(env): scope branch-override lookup by branchId (#109)

## Problem

`project env update --branch` and `project env add --branch` fail
contradictorily on any branch that already has an override for a key:

- `add --branch` → server **409** "already exists in this scope"
- `update --branch` → CLI **`ENV_VARIABLE_NOT_FOUND`** "not found in
branch:…"

One says the variable exists, the other says it doesn't. Neither path
can touch an existing branch override, so re-running a workflow that
sets a per-branch override hard-fails.

## Root cause

`findVariableByNaturalKey` listed environment variables by `(projectId,
class, key)` and filtered by branch **client-side**, inspecting only the
first page. `GET /v1/environment-variables` is paginated (default
`limit=100`, ordered `createdAt asc`). Once a project accumulates more
than a page of preview overrides for a given key, the *newest* branch's
row sorts onto a later page and the lookup returns `null` even though
the row exists on the server.

Downstream:
- `update`'s pre-lookup returns null → throws `ENV_VARIABLE_NOT_FOUND`
before it ever PATCHes.
- `add`'s existence pre-check also returns null → it POSTs → the server
(which enforces uniqueness on `projectId, branchId, class, key`) rejects
with 409.

The endpoint already supports a `branchId` filter — the lookup just
wasn't using it.

## Why this surfaced now

This is a latent bug (the branch-override lookup has never passed
`branchId`), triggered by data volume rather than a code change. In one
affected project, the count of preview-class rows for
`BUILD_RUNNER_BASE_URL` had just crossed the page limit (104 rows, 104
distinct branches, 4 past the first page) — so the freshly-created
branch override was the row that fell off page 1. First deploy of a
branch (which takes the `add`/create path) still worked; every re-deploy
(the lookup path) failed. That first-run-vs-rerun signature is exactly
what the pagination boundary produces.

## Fix

Pass `branchId` to the list query for branch-scoped lookups so the
server returns the single exact row regardless of how many branches
exist. Role-scoped lookups (`branchId === null`) are unchanged.

## Testing

- `pnpm --filter @prisma/cli exec tsc --noEmit` — clean
- `pnpm --filter @prisma/cli test` — 563 passed
- Added a regression test asserting the branch-override lookup sends
`branchId`; verified it fails without the source change and passes with
it.

## Known residual (out of scope)

Role-scoped (template) lookups still fetch a single page and filter
`branchId === null` client-side — the same pagination class of bug in
theory — but the list query type only accepts `branchId?: string`, so
there's no way to express "branchId IS NULL" as a server filter today,
and template rows are singular per key and created early (page 1). Worth
a follow-up if the API grows a null-branch filter. Separately, the
projects hitting this also have a data-hygiene problem: preview-branch
overrides (and their branches/databases) are never cleaned up, which is
what let the row count climb past the page limit in the first place.

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

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

Author: kristof-siket

packages/cli/src/controllers/app-env-api.ts

@@ -33,6 +33,7 @@ export async function findVariableByNaturalKey(
   resolved: ResolvedEnvApiScope,
   signal: AbortSignal,
 ): Promise<RawEnvironmentVariable | null> {
+  // Filter by branchId server-side — the list pages at 100, so client-side-only filtering drops branch rows past page 1.
   const { data, error, response } = await client.GET(
     "/v1/environment-variables",
     {
@@ -41,6 +42,9 @@ export async function findVariableByNaturalKey(
           projectId,
           class: resolved.apiTarget.class,
           key,
+          ...(resolved.apiTarget.branchId !== null
+            ? { branchId: resolved.apiTarget.branchId }
+            : {}),
         },
       },
       signal,

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

@@ -944,6 +944,67 @@ describe("env update", () => {
     );
   });
 
+  it("scopes the branch-override lookup by branchId so it survives pagination", async () => {
+    const client = createMockClient();
+    client.envGET
+      .mockResolvedValueOnce({
+        data: {
+          data: [makeBranchRow()],
+          pagination: { hasMore: false, nextCursor: null },
+        },
+        response: { status: 200 },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          data: [
+            makeVariableRow({
+              id: "envvar_branch",
+              key: "DATABASE_URL",
+              class: "preview",
+              branchId: "br_feature",
+            }),
+          ],
+          pagination: { hasMore: false, nextCursor: null },
+        },
+        response: { status: 200 },
+      });
+    client.PATCH.mockResolvedValueOnce({
+      data: {
+        data: makeVariableRow({
+          id: "envvar_branch",
+          key: "DATABASE_URL",
+          class: "preview",
+          branchId: "br_feature",
+        }),
+      },
+      response: { status: 200 },
+    });
+
+    const { controllers, createTempCwd, createTestCommandContext } =
+      await loadControllers(client, "proj_123");
+    const cwd = await createTempCwd();
+    await writeLocalPin(cwd);
+    const { context } = await createTestCommandContext({ cwd });
+
+    await controllers.runEnvUpdate(context, "DATABASE_URL=postgresql://new", {
+      branchName: "feature/foo",
+    });
+
+    expect(client.GET).toHaveBeenCalledWith(
+      "/v1/environment-variables",
+      expect.objectContaining({
+        params: {
+          query: expect.objectContaining({
+            projectId: "proj_123",
+            class: "preview",
+            key: "DATABASE_URL",
+            branchId: "br_feature",
+          }),
+        },
+      }),
+    );
+  });
+
   it("updates variables from a dotenv file via PATCH", async () => {
     const client = createMockClient();
     client.envGET