codebyplan 1.13.16 → 1.13.17

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.16";
+    VERSION = "1.13.17";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -663,10 +663,8 @@ function noAuthHint() {
 Or, for the legacy 30-day shim:
   export CODEBYPLAN_API_KEY=<key>   # from https://codebyplan.com/settings/api-keys/`;
 }
-function validateApiKey() {
-  if (!legacyApiKey()) {
-    throw new Error(noAuthHint());
-  }
+async function validateAuth() {
+  await getAuthHeaders();
 }
 async function getAuthHeaders() {
   try {
@@ -3797,7 +3795,7 @@ async function eslintInit(repoId, projectPath) {
 async function runEslint() {
   const subcommand = process.argv[3];
   const flags = parseFlags(4);
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   switch (subcommand) {
@@ -7073,6 +7071,94 @@ var init_cmux_serve = __esm({
   }
 });
 
+// src/lib/worktree-port-resolver.ts
+async function resolveWorktreePortAllocations(repoId, projectPath) {
+  let resolvedWorktreeId;
+  try {
+    const deviceId = await getOrCreateDeviceId(projectPath);
+    let branch = "main";
+    try {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
+        cwd: projectPath,
+        encoding: "utf-8"
+      }).trim();
+    } catch {
+    }
+    const tupleId = await resolveWorktreeId({
+      repoId,
+      repoPath: projectPath,
+      branch,
+      deviceId
+    });
+    if (tupleId) {
+      resolvedWorktreeId = tupleId;
+    } else {
+      resolvedWorktreeId = await resolveAndCacheWorktreeId(repoId, projectPath) ?? void 0;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `  Warning: failed to cache worktree_id (self-heal skipped): ${msg}`
+    );
+  }
+  let portAllocations = [];
+  try {
+    const portsRes = await apiGet(
+      `/port-allocations`,
+      resolvedWorktreeId ? {
+        repo_id: repoId,
+        worktree_id: resolvedWorktreeId,
+        limit: PORT_ALLOCATIONS_UNFILTERED_LIMIT
+      } : {
+        repo_id: repoId,
+        worktree_id: "null",
+        limit: PORT_ALLOCATIONS_UNFILTERED_LIMIT
+      }
+    );
+    const allAllocations = portsRes.data ?? [];
+    const filtered = resolvedWorktreeId ? allAllocations.filter((a) => a.worktree_id === resolvedWorktreeId) : allAllocations.filter((a) => !a.worktree_id);
+    portAllocations = filtered.map((a) => {
+      const clean = {};
+      for (const key of ALLOWED_FIELDS) {
+        if (key in a) clean[key] = a[key];
+      }
+      return clean;
+    });
+  } catch (err) {
+    console.warn(
+      `  Warning: failed to fetch port allocations: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const matchingAlloc = portAllocations[0];
+  return { resolvedWorktreeId, portAllocations, matchingAlloc };
+}
+var PORT_ALLOCATIONS_UNFILTERED_LIMIT, ALLOWED_FIELDS;
+var init_worktree_port_resolver = __esm({
+  "src/lib/worktree-port-resolver.ts"() {
+    "use strict";
+    init_api();
+    init_resolve_worktree();
+    init_local_config();
+    PORT_ALLOCATIONS_UNFILTERED_LIMIT = "500";
+    ALLOWED_FIELDS = [
+      "id",
+      "repo_id",
+      "port",
+      "label",
+      "server_type",
+      "auto_start",
+      "command",
+      "working_dir",
+      "env_vars",
+      "external_refs",
+      "worktree_id",
+      "created_at",
+      "updated_at"
+    ];
+  }
+});
+
 // src/lib/migrate-local-config.ts
 import { mkdir as mkdir6, readFile as readFile16, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
 import { join as join24 } from "node:path";
@@ -7307,6 +7393,7 @@ __export(config_exports, {
   readGitConfig: () => readGitConfig,
   readRepoConfig: () => readRepoConfig,
   readServerConfig: () => readServerConfig,
+  readServerLocalConfig: () => readServerLocalConfig,
   readShipmentConfig: () => readShipmentConfig,
   readVendorConfig: () => readVendorConfig,
   runConfig: () => runConfig
@@ -7316,7 +7403,7 @@ import { join as join25 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   console.log(`
@@ -7346,35 +7433,12 @@ async function runConfig() {
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
   const codebyplanDir = join25(projectPath, ".codebyplan");
-  let resolvedWorktreeId;
-  try {
-    const deviceId = await getOrCreateDeviceId(projectPath);
-    let branch = "main";
-    try {
-      const { execSync: execSync11 } = await import("node:child_process");
-      branch = execSync11("git symbolic-ref --short HEAD", {
-        cwd: projectPath,
-        encoding: "utf-8"
-      }).trim();
-    } catch {
-    }
-    const tupleId = await resolveWorktreeId({
-      repoId,
-      repoPath: projectPath,
-      branch,
-      deviceId
-    });
-    if (tupleId) {
-      resolvedWorktreeId = tupleId;
-    } else {
-      resolvedWorktreeId = await resolveAndCacheWorktreeId(repoId, projectPath) ?? void 0;
-    }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(
-      `  Warning: failed to cache worktree_id (self-heal skipped): ${msg}`
-    );
-  }
+  const {
+    resolvedWorktreeId,
+    portAllocations,
+    matchingAlloc: matchingAllocRaw
+  } = await resolveWorktreePortAllocations(repoId, projectPath);
+  const matchingAlloc = matchingAllocRaw;
   let repoRes;
   try {
     repoRes = await apiGet(`/repos/${repoId}`);
@@ -7397,42 +7461,6 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     process.exit(1);
   }
   const repo = repoRes.data;
-  let portAllocations = [];
-  try {
-    const portsRes = await apiGet(
-      `/port-allocations`,
-      { repo_id: repoId }
-    );
-    const allAllocations = portsRes.data ?? [];
-    const filtered = resolvedWorktreeId ? allAllocations.filter((a) => a.worktree_id === resolvedWorktreeId) : allAllocations.filter((a) => !a.worktree_id);
-    const ALLOWED_FIELDS = [
-      "id",
-      "repo_id",
-      "port",
-      "label",
-      "server_type",
-      "auto_start",
-      "command",
-      "working_dir",
-      "env_vars",
-      "external_refs",
-      "worktree_id",
-      "created_at",
-      "updated_at"
-    ];
-    portAllocations = filtered.map((a) => {
-      const clean = {};
-      for (const key of ALLOWED_FIELDS) {
-        if (key in a) clean[key] = a[key];
-      }
-      return clean;
-    });
-  } catch (err) {
-    console.warn(
-      `  Warning: failed to fetch port allocations: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-  const matchingAlloc = portAllocations[0];
   const defaultBranchConfig = {
     protected: ["main"],
     integration: null,
@@ -7573,14 +7601,24 @@ async function readE2eConfig2(projectPath) {
     return null;
   }
 }
+async function readServerLocalConfig(projectPath) {
+  try {
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "server.local.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 var legacyBranchConfigWarned;
 var init_config = __esm({
   "src/cli/config.ts"() {
     "use strict";
     init_flags();
     init_api();
-    init_resolve_worktree();
-    init_local_config();
+    init_worktree_port_resolver();
     init_migrate_local_config();
     legacyBranchConfigWarned = false;
   }
@@ -7738,22 +7776,48 @@ var init_port_verify = __esm({
 // src/cli/ports.ts
 var ports_exports = {};
 __export(ports_exports, {
+  parseEnvFile: () => parseEnvFile,
   runPorts: () => runPorts
 });
+import { mkdir as mkdir8, readFile as readFile19, writeFile as writeFile14 } from "node:fs/promises";
+import { join as join26 } from "node:path";
 async function runPorts() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
   const fix = hasFlag("fix", 3);
-  validateApiKey();
-  const config = await resolveConfig(flags);
-  const { repoId, projectPath } = config;
+  const writeLocal = hasFlag("write-local", 3);
+  const provisionE2e = hasFlag("provision-e2e", 3);
+  if (flags["path"]?.startsWith("--")) {
+    console.warn(
+      `  Warning: --path value "${flags["path"]}" looks like a flag. Pass --path <dir> BEFORE boolean flags (e.g. --path . --provision-e2e).`
+    );
+  }
+  const provisionE2eOnly = provisionE2e && !writeLocal;
+  let repoId = "";
+  let projectPath;
+  if (provisionE2eOnly) {
+    projectPath = flags["path"] ?? process.cwd();
+  } else {
+    await validateAuth();
+    const config = await resolveConfig(flags);
+    repoId = config.repoId;
+    projectPath = config.projectPath;
+  }
   console.log(`
   CodeByPlan Ports`);
-  console.log(`  Repo: ${repoId}`);
+  if (repoId) console.log(`  Repo: ${repoId}`);
   console.log(`  Path: ${projectPath}`);
   if (dryRun) console.log(`  Mode: dry-run`);
   if (fix) console.log(`  Mode: fix`);
+  if (writeLocal) console.log(`  Mode: write-local`);
+  if (provisionE2e) console.log(`  Mode: provision-e2e`);
   console.log();
+  if (writeLocal || provisionE2e) {
+    if (writeLocal) await writeServerLocalConfig(repoId, projectPath, dryRun);
+    if (provisionE2e) await provisionE2eEnv(projectPath, dryRun);
+    console.log("\n  Ports complete.\n");
+    return;
+  }
   try {
     const portsRes = await apiGet(
       `/port-allocations`,
@@ -7822,12 +7886,135 @@ async function runPorts() {
   }
   console.log("\n  Ports complete.\n");
 }
+async function writeServerLocalConfig(repoId, projectPath, dryRun) {
+  const { resolvedWorktreeId, portAllocations, matchingAlloc } = await resolveWorktreePortAllocations(repoId, projectPath);
+  if (portAllocations.length === 0) {
+    console.warn(
+      "  Skipped .codebyplan/server.local.json \u2014 no worktree port allocations resolved (API failure or none assigned)."
+    );
+    return;
+  }
+  const payload = {
+    server_port: matchingAlloc?.port ?? null,
+    server_type: matchingAlloc?.server_type ?? null,
+    // No cast needed: resolveWorktreePortAllocations returns Partial<PortAllocation>[]
+    // and ServerLocalConfig.port_allocations is typed the same — honest end-to-end.
+    port_allocations: portAllocations
+  };
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "server.local.json");
+  const newJson = JSON.stringify(payload, null, 2) + "\n";
+  let currentJson = "";
+  try {
+    currentJson = await readFile19(filePath, "utf-8");
+  } catch {
+  }
+  if (currentJson === newJson) {
+    console.log("  server.local.json up to date.");
+    return;
+  }
+  if (dryRun) {
+    console.log("  Would update .codebyplan/server.local.json (dry-run).");
+    return;
+  }
+  await mkdir8(codebyplanDir, { recursive: true });
+  await writeFile14(filePath, newJson, "utf-8");
+  console.log(
+    `  Updated .codebyplan/server.local.json (worktree ${resolvedWorktreeId ?? "\u2014"}, ${portAllocations.length} allocation${portAllocations.length === 1 ? "" : "s"}).`
+  );
+}
+async function provisionE2eEnv(projectPath, dryRun) {
+  const relSource = join26("apps", "web", ".env.local");
+  const sourcePath = join26(projectPath, relSource);
+  let sourceRaw;
+  try {
+    sourceRaw = await readFile19(sourcePath, "utf-8");
+  } catch {
+    console.warn(
+      `  Skipped .codebyplan/e2e.env \u2014 source ${relSource} not found.`
+    );
+    return;
+  }
+  const sourceVars = parseEnvFile(sourceRaw);
+  const lines = [];
+  const missing = [];
+  for (const key of E2E_ENV_VARS) {
+    const val = sourceVars[key];
+    if (val === void 0) {
+      missing.push(key);
+      continue;
+    }
+    lines.push(`${key}=${val}`);
+  }
+  if (missing.length > 0) {
+    console.warn(
+      `  Warning: ${missing.length} E2E var(s) missing from ${relSource}: ${missing.join(", ")}`
+    );
+  }
+  if (lines.length === 0) {
+    console.warn(
+      "  Skipped .codebyplan/e2e.env \u2014 none of the expected E2E vars were found."
+    );
+    return;
+  }
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "e2e.env");
+  const newContent = lines.join("\n") + "\n";
+  let currentContent = "";
+  try {
+    currentContent = await readFile19(filePath, "utf-8");
+  } catch {
+  }
+  if (currentContent === newContent) {
+    console.log("  e2e.env up to date.");
+    return;
+  }
+  if (dryRun) {
+    console.log("  Would provision .codebyplan/e2e.env (dry-run).");
+    return;
+  }
+  await mkdir8(codebyplanDir, { recursive: true });
+  await writeFile14(filePath, newContent, "utf-8");
+  console.log(
+    `  Provisioned .codebyplan/e2e.env (${lines.length} var${lines.length === 1 ? "" : "s"}).`
+  );
+}
+function parseEnvFile(raw) {
+  const out = {};
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    if (key === "") continue;
+    let value = trimmed.slice(eq + 1).trim();
+    const quoted = value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"));
+    if (quoted) {
+      value = value.slice(1, -1);
+    } else {
+      const commentIdx = value.indexOf(" #");
+      if (commentIdx !== -1) value = value.slice(0, commentIdx).trimEnd();
+    }
+    out[key] = value;
+  }
+  return out;
+}
+var E2E_ENV_VARS;
 var init_ports = __esm({
   "src/cli/ports.ts"() {
     "use strict";
     init_flags();
     init_api();
     init_port_verify();
+    init_worktree_port_resolver();
+    E2E_ENV_VARS = [
+      "E2E_USER_EMAIL",
+      "E2E_USER_PASSWORD",
+      "NEXT_PUBLIC_SUPABASE_URL",
+      "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY",
+      "SUPABASE_SECRET_KEY"
+    ];
   }
 });
 
@@ -7845,7 +8032,7 @@ async function runTechStack() {
     await runFullTechStack(dryRun);
     return;
   }
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   console.log(`
@@ -7980,7 +8167,7 @@ async function syncTechStackForPath(repoId, projectPath, dryRun) {
   }
 }
 async function runFullTechStack(dryRun) {
-  validateApiKey();
+  await validateAuth();
   const localConfig = await readLocalConfig(process.cwd());
   if (!localConfig?.device_id) {
     console.error(
@@ -8981,6 +9168,11 @@ void (async () => {
     --repo-id <uuid>        Repository ID (or set via .codebyplan/repo.json)
     --dry-run               Preview changes without writing
     --fix                   Auto-create missing port allocations
+    --write-local           Write this worktree's port allocations to the
+                            gitignored .codebyplan/server.local.json overlay
+                            (never the committed server.json)
+    --provision-e2e         Copy E2E credentials from apps/web/.env.local into
+                            the gitignored .codebyplan/e2e.env (local, no API)
 
   Tech stack options:
     --path <dir>            Project root directory (default: cwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.16",
+  "version": "1.13.17",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -61,6 +61,6 @@
     "prettier": "^3.8.1",
     "typescript": "^5",
     "typescript-eslint": "^8.20.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.8"
   }
 }

package/templates/agents/cbp-e2e-playwright.md

@@ -26,136 +26,237 @@ pnpm exec playwright install --with-deps chromium
 
 ## playwright.config.ts
 
-Derive `baseURL` from `.codebyplan/server.json` at config-read time. Match by label
-(`"Web Dev"`) rather than array position — a monorepo can have several nextjs allocations.
+Resolve the apps/web dev-server port at config-read time via the shared resolver
+`apps/web/e2e/resolve-web-dev-port.ts` — imported by BOTH `playwright.config.ts` and
+`e2e/auth.setup.ts` (single source of truth). It reads the per-worktree
+`.codebyplan/server.local.json` overlay first, then the committed `.codebyplan/server.json`.
+Match by label rather than array position — a monorepo can have several Next.js allocations
+with similar label prefixes.
+
+**Label-matching rules** (`findWebDevPort`):
+
+- `server.local.json` overlay: each label has the worktree name appended as the last
+  parenthetical group (e.g. `"Web Dev (codebyplan-mcp-1)"`). Strip exactly ONE trailing
+  `" (…)"` group, then require the result `=== "Web Dev"`.
+  - `"Web Dev (codebyplan-mcp-1)"` → strip → `"Web Dev"` ✓
+  - `"Web Dev (codebyplan-desktop) (codebyplan-mcp-1)"` → strip → `"Web Dev (codebyplan-desktop)"` ✗
+- `server.json` committed base: require `label === "Web Dev"` exactly (do NOT strip —
+  `"Web Dev (codebyplan-desktop)"` must not match).
+
+**Resolution order** (first hit wins):
+
+0. `PLAYWRIGHT_BASE_URL` — explicit CI / local override (`parsePortFromUrl` extracts the port)
+1. `.codebyplan/server.local.json` — `findWebDevPort(…, {stripWorktreeSuffix: true})`
+2. `.codebyplan/server.json` — `findWebDevPort(…, {stripWorktreeSuffix: false})`
+3. `E2E_BASE_URL` — `parsePortFromUrl` (kept BELOW the overlay: a stale `E2E_BASE_URL` in a
+   gitignored `.env.local` must never shadow the worktree's own port — set `PLAYWRIGHT_BASE_URL`
+   to override in CI)
+4. `3010` — last resort
+
+The resolver uses `readFileSync` + `JSON.parse` with paths relative to `apps/web/e2e/`
+(`resolve(__dirname, "../../../.codebyplan/…")`). Each read is wrapped in `try/catch` — the
+overlay is gitignored and absent in CI. Do NOT import from the `codebyplan` CLI package
+(async, cross-package coupling). `findWebDevPort` + `parsePortFromUrl` are pure and unit-tested
+in `e2e/__tests__/resolve-web-dev-port.test.ts`.
 
 ```ts
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { defineConfig, devices } from "@playwright/test";
-import { execSync } from "child_process";
 
-function getBaseUrl(): string {
+import { resolveWebDevPort } from "./e2e/resolve-web-dev-port";
+
+// Load apps/web/.env.local into process.env (process.env wins on conflict)
+(function loadDotEnvLocal() {
+  try {
+    const text = readFileSync(resolve(__dirname, ".env.local"), "utf-8");
+    for (const line of text.split("\n")) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      const eq = t.indexOf("=");
+      if (eq === -1) continue;
+      const k = t.slice(0, eq).trim();
+      let v = t.slice(eq + 1).trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+        v = v.slice(1, -1);
+      if (!(k in process.env)) process.env[k] = v;
+    }
+  } catch { /* absent in CI */ }
+})();
+
+// Load .codebyplan/e2e.env — Supabase + auth credentials (process.env wins)
+(function loadE2eEnv() {
   try {
-    const raw = execSync(
-      "jq -r '.port_allocations[] | select(.label==\"Web Dev\") | .port' .codebyplan/server.json 2>/dev/null | head -1",
-      { encoding: "utf-8" }
-    ).trim();
-    const port = parseInt(raw, 10);
-    return `http://localhost:${port}`;
-  } catch {
-    return "http://localhost:3010";
-  }
-}
+    const text = readFileSync(resolve(__dirname, "../../.codebyplan/e2e.env"), "utf-8");
+    for (const line of text.split("\n")) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      const eq = t.indexOf("=");
+      if (eq === -1) continue;
+      const k = t.slice(0, eq).trim();
+      let v = t.slice(eq + 1).trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+        v = v.slice(1, -1);
+      if (!(k in process.env)) process.env[k] = v;
+    }
+  } catch { /* absent in CI — shell / CI secrets used instead */ }
+})();
+
+// findWebDevPort, parsePortFromUrl, and resolveWebDevPort live in the shared
+// module ./e2e/resolve-web-dev-port.ts (imported above) — single source of
+// truth, also consumed by e2e/auth.setup.ts. Resolution order:
+//   0. PLAYWRIGHT_BASE_URL → 1. server.local.json → 2. server.json
+//   → 3. E2E_BASE_URL → 4. 3010.
+const port = resolveWebDevPort();
 
 export default defineConfig({
-  testDir: "apps/web/e2e",
-  fullyParallel: false,
+  testDir: "./e2e",
+  testMatch: "*.spec.ts",
+  globalSetup: require.resolve("./e2e/global-setup"),
+  fullyParallel: true,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
+  retries: process.env.CI ? 1 : 0,
   workers: 1,            // serialize against shared remote Supabase — see e2e.md § Supabase Parallelism
-  reporter: process.env.CI ? "github" : "html",
-  globalSetup: "./apps/web/e2e/global-setup",
+  reporter: "list",
+  timeout: 30_000,
+  expect: {
+    toHaveScreenshot: { stylePath: "./e2e/screenshot.css" },
+  },
   use: {
-    baseURL: getBaseUrl(),
+    baseURL: `http://localhost:${port}`,
+    storageState: "e2e/.auth/refreshed-state.json",
+    actionTimeout: 15_000,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [
-    { name: "setup", testMatch: /global\.setup\.ts/ },
-    {
-      name: "web",
-      use: { ...devices["Desktop Chrome"], storageState: "apps/web/e2e/.auth/user.json" },
-      dependencies: ["setup"],
-    },
-  ],
   webServer: {
-    command: "pnpm --filter @codebyplan/web dev",
-    url: getBaseUrl(),
+    command: `pnpm --filter @codebyplan/web dev --port ${port}`,
+    url: `http://localhost:${port}`,
     reuseExistingServer: !process.env.CI,
     timeout: 120_000,
+    env: {
+      // Forward Supabase + auth vars into the spawned dev server. Only forward
+      // vars that are present in process.env (undefined would stringify to "undefined").
+      ...(process.env.NEXT_PUBLIC_SUPABASE_URL && {
+        NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
+      }),
+      ...(process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY && {
+        NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY,
+      }),
+      ...(process.env.SUPABASE_SECRET_KEY && {
+        SUPABASE_SECRET_KEY: process.env.SUPABASE_SECRET_KEY,
+      }),
+    },
   },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
 });
 ```
 
 ## Auth — Global Setup + Storage State
 
-`apps/web/e2e/global-setup.ts`:
+`apps/web/e2e/global-setup.ts` performs two phases at startup:
 
-```ts
-import { chromium, FullConfig } from "@playwright/test";
-import path from "path";
-
-const AUTH_FILE = path.join(__dirname, ".auth/user.json");
-
-export default async function globalSetup(config: FullConfig) {
-  const email = process.env.E2E_TEST_EMAIL;
-  const password = process.env.E2E_TEST_PASSWORD;
-
-  if (!email || !password) {
-    throw new Error(
-      "E2E_TEST_EMAIL and E2E_TEST_PASSWORD must be set.\n" +
-        "Copy .env.local.example to .env.local, then run: pnpm e2e:provision"
-    );
-  }
-
-  const { baseURL } = config.projects[0].use;
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-
-  await page.goto(`${baseURL}/login`);
-  await page.getByLabel(/email/i).fill(email);
-  await page.getByLabel(/password/i).fill(password);
-  await page.getByRole("button", { name: /sign in|log in/i }).click();
-  await page.waitForURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
-
-  await page.goto(baseURL!);   // cold-start warmup
-  await page.context().storageState({ path: AUTH_FILE });
-  await browser.close();
-}
-```
+**Phase 1 — Auth refresh**: reads `e2e/.auth/state.json`, finds the Supabase auth cookie
+(`sb-<projectref>-auth-token`), decodes its base64-JSON payload (`decodeAuthCookie` from the
+shared `e2e/auth-cookie.ts` module), calls `supabase.auth.refreshSession({refresh_token})` for
+fresh tokens, re-encodes via `encodeAuthCookie`, and writes the result to
+`e2e/.auth/refreshed-state.json`. No browser required — pure HTTP against Supabase auth.
 
-Gitignore storage state before first use:
+**Phase 2 — Maintainer seeding**: uses the service-role client to ensure the test user
+holds a maintainer-or-above role on at least one organization (`e2e-test-fixture` slug).
+Idempotent — if a qualifying membership already exists, phase 2 is a no-op.
 
-```bash
-mkdir -p apps/web/e2e/.auth
-echo "apps/web/e2e/.auth/" >> .gitignore
-```
+**Required env vars** (read via `readEnv(name, fallbacks)` which checks `process.env` first,
+then falls back to the parsed `.env.local` file):
+
+- `NEXT_PUBLIC_SUPABASE_URL` — both phases
+- `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` — Phase 1 refresh client
+- `SUPABASE_SECRET_KEY` — Phase 2 admin operations
+- `E2E_USER_EMAIL` — Phase 2 user lookup + seeding
+
+Because `readEnv` checks `process.env` before `.env.local`, loading these vars into
+`process.env` via `loadE2eEnv()` in `playwright.config.ts` is sufficient — global-setup
+will pick them up.
+
+### Seeding `state.json` — `e2e/auth.setup.ts` (`pnpm e2e:auth-setup`)
+
+global-setup Phase 1 only *refreshes* an existing `state.json`; the initial seed is written by
+`e2e/auth.setup.ts`. It is a pure-HTTP API seed — **no browser, no dev server, no hydration
+timing**: it loads creds from `.env.local` + `.codebyplan/e2e.env`, calls
+`supabase.auth.signInWithPassword({email, password})` with the publishable-key client, derives
+the project ref from `NEXT_PUBLIC_SUPABASE_URL`, and writes a `sb-<projectref>-auth-token`
+cookie (domain `localhost`) into `state.json` using the same `encodeAuthCookie` from
+`e2e/auth-cookie.ts` that global-setup consumes. This makes seeding deterministic in any
+worktree — run `pnpm e2e:auth-setup` (optionally `--port N`) when `state.json` is missing or
+its refresh token has expired. Do NOT reintroduce a browser-login flow (the `(auth)/login`
+page is a client component whose `onSubmit` only attaches after hydration — clicking submit
+pre-hydration falls through to a native GET and never authenticates).
 
 ## Auth Probe
 
-`apps/web/e2e/_probe/auth.spec.ts` — validates the login path directly (outside storage-
-state flow) so credential failures are diagnosed cleanly:
+`apps/web/e2e/_probe/auth.spec.ts` — verifies that the stored auth state
+(`refreshed-state.json`) grants access to the authenticated dashboard without
+redirecting to the login page. It is intentionally minimal (one test) and runs
+before the full suite to confirm the auth preflight:
 
 ```ts
 import { test, expect } from "@playwright/test";
 
-test("auth probe: can log in with E2E_TEST_EMAIL/E2E_TEST_PASSWORD", async ({ page }) => {
-  const email = process.env.E2E_TEST_EMAIL;
-  const password = process.env.E2E_TEST_PASSWORD;
-  expect(email, "E2E_TEST_EMAIL env var is required").toBeTruthy();
-  expect(password, "E2E_TEST_PASSWORD env var is required").toBeTruthy();
-
-  await page.goto("/login");
-  await page.getByLabel(/email/i).fill(email!);
-  await page.getByLabel(/password/i).fill(password!);
-  await page.getByRole("button", { name: /sign in|log in/i }).click();
+test("auth probe: authenticated user reaches /dashboard without login redirect", async ({
+  page,
+}) => {
+  const response = await page.goto("/dashboard", {
+    waitUntil: "domcontentloaded",
+    timeout: 20_000,
+  });
 
-  await expect(page).toHaveURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+  // Must NOT be redirected to /login or /auth/login.
+  const finalUrl = page.url();
+  expect(
+    finalUrl,
+    `Auth probe failed: landed on ${finalUrl} instead of /dashboard. Check state.json / refreshed-state.json.`
+  ).not.toMatch(/\/(auth\/)?login/);
+
+  // HTTP status must be < 400.
+  const status = response?.status() ?? 0;
+  expect(
+    status,
+    `Auth probe failed: /dashboard returned HTTP ${status}.`
+  ).toBeLessThan(400);
+
+  // Dashboard heading must be present.
+  await expect(
+    page.getByRole("heading", { level: 1, name: /welcome to codebyplan|dashboard/i })
+  ).toBeVisible({ timeout: 15_000 });
 });
 ```
 
-Run probe: `pnpm exec playwright test --project=web _probe/auth`
+Run probe: `pnpm exec playwright test --project=chromium _probe/auth`
 
 ## Pre-flight Probes (Step 6.5.2)
 
 **Dev server**: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/` — expect
 200/3xx. On failure:
 
-> "Dev server is not responding on port `{port}`. Please run `cd apps/{app} && pnpm dev`
+> "Dev server is not responding on port `{port}`. Please run `cd apps/web && pnpm dev --port {port}`
 > in a separate terminal, then reply 'ready' when the page loads in your browser."
 
-**Port alignment**: parse `playwright.config.ts` `baseURL` port; compare to
-`.codebyplan/server.json` `port_allocations[]`. On mismatch ask which is correct, then
-propose an Edit to align them.
+Note: Playwright's `webServer` block behaviour differs by environment. In local worktree
+runs (`reuseExistingServer: true`), Playwright reuses an already-running server and only
+auto-starts one when nothing is listening on the port — this probe is mainly a safety net.
+In CI (`reuseExistingServer: false`), Playwright always spawns a fresh server regardless of
+any already-running process, so the dev-server readiness probe is the active guard for that
+path.
+
+**Port alignment**: parse `playwright.config.ts` `baseURL` port; compare to the resolved
+port from `.codebyplan/server.local.json` (worktree overlay, checked first) then
+`.codebyplan/server.json` (committed base). On mismatch ask which is correct, then propose
+an Edit to align them.
 
 ## Spec-Writing Patterns
 
@@ -227,7 +328,7 @@ Include this in the specialist output alongside `screenshots[]`.
 ## Run Command
 
 ```bash
-pnpm exec playwright test {spec} --project=web --reporter=list
+pnpm exec playwright test {spec} --project=chromium --reporter=list
 ```
 
 ## Selector Conventions
@@ -238,13 +339,13 @@ the new page state rather than holding stale `Locator` handles.
 
 ## CI Secrets
 
-`E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
-`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+`E2E_USER_EMAIL`, `E2E_USER_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SECRET_KEY`.
 
 ## Pitfalls
 
 **Cold-start timeouts** — warmup in `globalSetup` (after `page.goto(baseURL!)`) primes
-Turbopack compilation. **Port mismatch** — compare `baseURL` port to `server.json` before
-running. **Supabase parallelism** — remote Supabase requires `workers: 1` to prevent
-auth/RLS races. **SCSS Module selectors** — use `[class*='componentName'].first()` or
-role-based selectors.
+Turbopack compilation. **Port mismatch** — compare `baseURL` port to resolved port from
+`server.local.json` / `server.json` before running. **Supabase parallelism** — remote
+Supabase requires `workers: 1` to prevent auth/RLS races. **SCSS Module selectors** — use
+`[class*='componentName'].first()` or role-based selectors.

package/templates/context/testing/e2e.md

@@ -118,11 +118,12 @@ with the blocking preflight field populated.
 
 ### 6.5.1 Environment Variables
 
-Check `apps/{app}/.env.local` and process env. Framework-specific required var names come
-from the `credential_vars` input field (the dispatching skill reads them from
-`.codebyplan/e2e.json`). Naming conventions:
+Check `apps/{app}/.env.local`, `.codebyplan/e2e.env`, and process env. Framework-specific
+required var names come from the `credential_vars` input field (the dispatching skill reads
+them from `.codebyplan/e2e.json`). Naming conventions:
 
-- Playwright uses `E2E_TEST_*` (avoids collision with non-E2E `TEST_*` vars).
+- Playwright uses `E2E_USER_EMAIL` / `E2E_USER_PASSWORD` (matches `.codebyplan/e2e.json`
+  `credentials.frameworks.playwright` and the `e2e.env` file loaded by `playwright.config.ts`).
 - Maestro/XCUITest stay on `TEST_*` per `rules/maestro-auth-state-reset.md`.
 
 For any missing var:
@@ -148,8 +149,9 @@ On any failure, `AskUserQuestion` with remediation steps; re-probe after "ready"
 silently skip a required runtime prerequisite.
 
 **Port alignment (Playwright only)**: parse `playwright.config.ts` `baseURL` and compare
-to `.codebyplan/server.json` `port_allocations[]` for the app. On mismatch ask which is
-correct before running.
+to the resolved port from `.codebyplan/server.local.json` (worktree overlay, checked first)
+then `.codebyplan/server.json` (committed base) `port_allocations[]` for the app. On
+mismatch ask which is correct before running.
 
 ### 6.5.3 Auth Probe (only when `has_auth`)
 
@@ -303,9 +305,12 @@ Every repo with Playwright auth ships:
 
 - `scripts/provision-e2e-user.ts` — idempotent script creating the canonical E2E user
   and (for multi-tenant repos) a `test` subdomain. Wired to `pnpm e2e:provision`.
-- `.env.local.example` — lists every env var `globalSetup` requires.
-- CI secrets: `E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
-  `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+- `.codebyplan/e2e.env` — gitignored per-worktree file listing every env var `globalSetup`
+  requires. Written by `codebyplan e2e:provision` or manually. Loaded by `playwright.config.ts`
+  into `process.env` so global-setup picks them up via its `readEnv` helper.
+- `.env.local.example` — lists every env var `globalSetup` requires for reference.
+- CI secrets: `E2E_USER_EMAIL`, `E2E_USER_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+  `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SECRET_KEY`.
 
 Per-repo specifics (email, vault name, remaining-spec migration list) live in the repo's
 own `docs/e2e-setup.md`, not in this shared file.

package/templates/skills/cbp-git-worktree-create/SKILL.md

@@ -142,6 +142,17 @@ cp "$MAIN_REPO/.env.local" "$WORKTREE_PATH/.env.local"
 
 Verify `.env.local` is already in `.gitignore` (it should be via `.env.local` pattern). If not, add it.
 
+Also copy the gitignored E2E credentials source (`.codebyplan/e2e.env`, referenced by `.codebyplan/e2e.json`) so the new worktree can run Playwright auth flows immediately:
+
+```bash
+mkdir -p "$WORKTREE_PATH/.codebyplan"
+if [ -f "$MAIN_REPO/.codebyplan/e2e.env" ]; then
+  cp "$MAIN_REPO/.codebyplan/e2e.env" "$WORKTREE_PATH/.codebyplan/e2e.env"
+fi
+```
+
+If the main repo has no `.codebyplan/e2e.env` yet, provision it after setup by running `codebyplan ports --path "$WORKTREE_PATH" --provision-e2e` (copies the canonical E2E vars from `apps/web/.env.local`). Pass `--path` BEFORE the boolean flag. `.codebyplan/e2e.env` is gitignored — never commit it.
+
 ### Step 8: Push Branch
 
 ```bash