@databricks-solutions/lakebase-scm-utils 0.3.0 → 0.3.2

package/dist/scripts/lakebase/scm-merge.cli.cjs

@@ -88825,8 +88825,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";
@@ -89010,26 +89010,43 @@ init_cjs_shims();
 var import_node_child_process5 = require("child_process");
 var fs8 = __toESM(require("fs"), 1);
 var path7 = __toESM(require("path"), 1);
-function resolveAlembicBin(projectDir) {
-  const candidates = [
+var uvOnPath;
+function hasUv() {
+  if (uvOnPath !== void 0) return uvOnPath;
+  try {
+    (0, import_node_child_process5.execFileSync)("uv", ["--version"], { stdio: "ignore" });
+    uvOnPath = true;
+  } catch {
+    uvOnPath = false;
+  }
+  return uvOnPath;
+}
+function resolveAlembicInvocation(projectDir, uvAvailable = hasUv()) {
+  const venvCandidates = [
     path7.join(projectDir, ".venv", "bin", "alembic"),
     path7.join(projectDir, "venv", "bin", "alembic")
   ];
-  for (const candidate of candidates) {
+  for (const candidate of venvCandidates) {
     try {
-      if (fs8.existsSync(candidate)) return candidate;
+      if (fs8.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs8.existsSync(path7.join(projectDir, "pyproject.toml"))) {
+      return { bin: "uv", prefixArgs: ["run", "alembic"] };
+    }
+  } catch {
+  }
+  return { bin: "alembic", prefixArgs: [] };
 }
 function spawnAlembic(projectDir, args, dsn) {
   return new Promise((resolve2, reject) => {
-    const bin = resolveAlembicBin(projectDir);
+    const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
     const env = { ...process.env };
     env.PYTHONPATH = [projectDir, process.env.PYTHONPATH].filter(Boolean).join(path7.delimiter);
     if (dsn) env.DATABASE_URL = dsn;
-    const child = (0, import_node_child_process5.spawn)(bin, args, {
+    const child = (0, import_node_child_process5.spawn)(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"]

package/dist/scripts/lakebase/scm-merge.cli.js

@@ -9978,8 +9978,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";
@@ -10160,29 +10160,46 @@ import * as path9 from "path";
 
 // scripts/lakebase/schema-migrate-runners/alembic.ts
 init_esm_shims();
-import { spawn } from "child_process";
+import { spawn, execFileSync as execFileSync5 } from "child_process";
 import * as fs7 from "fs";
 import * as path8 from "path";
-function resolveAlembicBin(projectDir) {
-  const candidates = [
+var uvOnPath;
+function hasUv() {
+  if (uvOnPath !== void 0) return uvOnPath;
+  try {
+    execFileSync5("uv", ["--version"], { stdio: "ignore" });
+    uvOnPath = true;
+  } catch {
+    uvOnPath = false;
+  }
+  return uvOnPath;
+}
+function resolveAlembicInvocation(projectDir, uvAvailable = hasUv()) {
+  const venvCandidates = [
     path8.join(projectDir, ".venv", "bin", "alembic"),
     path8.join(projectDir, "venv", "bin", "alembic")
   ];
-  for (const candidate of candidates) {
+  for (const candidate of venvCandidates) {
     try {
-      if (fs7.existsSync(candidate)) return candidate;
+      if (fs7.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs7.existsSync(path8.join(projectDir, "pyproject.toml"))) {
+      return { bin: "uv", prefixArgs: ["run", "alembic"] };
+    }
+  } catch {
+  }
+  return { bin: "alembic", prefixArgs: [] };
 }
 function spawnAlembic(projectDir, args, dsn) {
   return new Promise((resolve2, reject) => {
-    const bin = resolveAlembicBin(projectDir);
+    const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
     const env = { ...process.env };
     env.PYTHONPATH = [projectDir, process.env.PYTHONPATH].filter(Boolean).join(path8.delimiter);
     if (dsn) env.DATABASE_URL = dsn;
-    const child = spawn(bin, args, {
+    const child = spawn(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"]

package/dist/scripts/lakebase/scm-reconcile-tier.cli.cjs

@@ -79288,8 +79288,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";
@@ -79547,26 +79547,43 @@ init_cjs_shims();
 var import_node_child_process3 = require("child_process");
 var fs7 = __toESM(require("fs"), 1);
 var path5 = __toESM(require("path"), 1);
-function resolveAlembicBin(projectDir) {
-  const candidates = [
+var uvOnPath;
+function hasUv() {
+  if (uvOnPath !== void 0) return uvOnPath;
+  try {
+    (0, import_node_child_process3.execFileSync)("uv", ["--version"], { stdio: "ignore" });
+    uvOnPath = true;
+  } catch {
+    uvOnPath = false;
+  }
+  return uvOnPath;
+}
+function resolveAlembicInvocation(projectDir, uvAvailable = hasUv()) {
+  const venvCandidates = [
     path5.join(projectDir, ".venv", "bin", "alembic"),
     path5.join(projectDir, "venv", "bin", "alembic")
   ];
-  for (const candidate of candidates) {
+  for (const candidate of venvCandidates) {
     try {
-      if (fs7.existsSync(candidate)) return candidate;
+      if (fs7.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs7.existsSync(path5.join(projectDir, "pyproject.toml"))) {
+      return { bin: "uv", prefixArgs: ["run", "alembic"] };
+    }
+  } catch {
+  }
+  return { bin: "alembic", prefixArgs: [] };
 }
 function spawnAlembic(projectDir, args, dsn) {
   return new Promise((resolve2, reject) => {
-    const bin = resolveAlembicBin(projectDir);
+    const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
     const env = { ...process.env };
     env.PYTHONPATH = [projectDir, process.env.PYTHONPATH].filter(Boolean).join(path5.delimiter);
     if (dsn) env.DATABASE_URL = dsn;
-    const child = (0, import_node_child_process3.spawn)(bin, args, {
+    const child = (0, import_node_child_process3.spawn)(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"]

package/dist/scripts/lakebase/scm-reconcile-tier.cli.js

@@ -389,8 +389,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";
@@ -640,29 +640,46 @@ import * as fs7 from "fs";
 import * as path6 from "path";
 
 // scripts/lakebase/schema-migrate-runners/alembic.ts
-import { spawn } from "child_process";
+import { spawn, execFileSync as execFileSync3 } from "child_process";
 import * as fs6 from "fs";
 import * as path5 from "path";
-function resolveAlembicBin(projectDir) {
-  const candidates = [
+var uvOnPath;
+function hasUv() {
+  if (uvOnPath !== void 0) return uvOnPath;
+  try {
+    execFileSync3("uv", ["--version"], { stdio: "ignore" });
+    uvOnPath = true;
+  } catch {
+    uvOnPath = false;
+  }
+  return uvOnPath;
+}
+function resolveAlembicInvocation(projectDir, uvAvailable = hasUv()) {
+  const venvCandidates = [
     path5.join(projectDir, ".venv", "bin", "alembic"),
     path5.join(projectDir, "venv", "bin", "alembic")
   ];
-  for (const candidate of candidates) {
+  for (const candidate of venvCandidates) {
     try {
-      if (fs6.existsSync(candidate)) return candidate;
+      if (fs6.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs6.existsSync(path5.join(projectDir, "pyproject.toml"))) {
+      return { bin: "uv", prefixArgs: ["run", "alembic"] };
+    }
+  } catch {
+  }
+  return { bin: "alembic", prefixArgs: [] };
 }
 function spawnAlembic(projectDir, args, dsn) {
   return new Promise((resolve2, reject) => {
-    const bin = resolveAlembicBin(projectDir);
+    const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
     const env = { ...process.env };
     env.PYTHONPATH = [projectDir, process.env.PYTHONPATH].filter(Boolean).join(path5.delimiter);
     if (dsn) env.DATABASE_URL = dsn;
-    const child = spawn(bin, args, {
+    const child = spawn(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"]
@@ -2137,7 +2154,7 @@ async function reconcileTierBranch(args, deps = {}) {
 // scripts/lakebase/scm-workflow-state.ts
 import * as fs13 from "fs";
 import * as path14 from "path";
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",

package/dist/scripts/util/index.cjs

@@ -1667,8 +1667,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.0".length > 0) {
-    cached = "0.3.0";
+  if ("0.3.2".length > 0) {
+    cached = "0.3.2";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,

package/scripts/lakebase/client-lockfile.ts

@@ -0,0 +1,102 @@
+// Generate + normalize the client's package-lock.json at scaffold time, so a
+// scaffolded UI project ships a COMMITTED lockfile that resolves from the
+// public npm registry.
+//
+// WHY: createProject writes the client template + wires Playwright but never
+// runs `npm install` in client/, so no package-lock.json exists at the initial
+// commit. The user had to generate it by hand (README: `cd client && npm
+// install`), and when they did it on the Databricks network the lock pinned
+// npm-proxy.cloud.databricks.com in its `resolved` URLs — which hangs a cold
+// install off-network (the lockfile-registry-guard hazard: the proxy host
+// resolves but never accepts a TCP connection off the Databricks network).
+//
+// WHAT: `npm install --package-lock-only` resolves the dep tree and writes
+// client/package-lock.json WITHOUT installing node_modules (fast, no tarball
+// downloads), then we host-swap any Databricks-proxy `resolved` host to
+// registry.npmjs.org (integrity hashes are unchanged — the proxy is a
+// passthrough mirror of the same tarballs). The scaffold's `git add -A` initial
+// commit then picks the normalized lock up for free.
+//
+// Non-fatal: a resolve failure (offline, registry down) is a warning, not a
+// create abort — the user can still `cd client && npm install` as before.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { exec } from "../util/exec.js";
+import { withProxyEnv } from "../util/proxy-env.js";
+
+/** The Databricks npm proxy host a cold off-network install hangs on. */
+const PROXY_HOST = "npm-proxy.cloud.databricks.com";
+/** The public registry every tracked lockfile must resolve from. */
+const PUBLIC_HOST = "registry.npmjs.org";
+
+export interface EnsureClientLockfileArgs {
+  /** The project root (the client dir lives at <projectDir>/<clientDir>). */
+  projectDir: string;
+  /** The client dir name under projectDir. Default "client". */
+  clientDir?: string;
+}
+
+export interface EnsureClientLockfileResult {
+  /** True when a package-lock.json exists in the client dir after this ran. */
+  generated: boolean;
+  /** Count of proxy-host `resolved` URLs rewritten to the public registry. */
+  swaps: number;
+  /** Why it did not run / generate (no client package.json, exec error). */
+  reason?: string;
+}
+
+/**
+ * Host-swap any Databricks-proxy `resolved` URL to the public registry. A pure
+ * string substitution — integrity hashes are left untouched because the proxy
+ * is a passthrough mirror of the same tarballs. Returns the rewritten text and
+ * the number of swaps.
+ */
+export function normalizeLockfileRegistry(lockText: string): { text: string; swaps: number } {
+  let swaps = 0;
+  const text = lockText.replace(new RegExp(PROXY_HOST.replace(/\./g, "\\."), "g"), () => {
+    swaps++;
+    return PUBLIC_HOST;
+  });
+  return { text, swaps };
+}
+
+/**
+ * For a UI project, generate client/package-lock.json (lock only, no install)
+ * and normalize its registry host. Idempotent, non-fatal: callers push the
+ * reason onto their warnings and continue.
+ */
+export async function ensureClientLockfile(
+  args: EnsureClientLockfileArgs,
+): Promise<EnsureClientLockfileResult> {
+  const clientDir = path.join(args.projectDir, args.clientDir ?? "client");
+  const pkg = path.join(clientDir, "package.json");
+  if (!fs.existsSync(pkg)) {
+    return { generated: false, swaps: 0, reason: "no client package.json" };
+  }
+  const lockPath = path.join(clientDir, "package-lock.json");
+  try {
+    // --package-lock-only resolves the dep tree + writes the lock, skipping
+    // node_modules (no tarball downloads), so the scaffold stays fast.
+    await exec("npm install --package-lock-only", {
+      cwd: clientDir,
+      env: withProxyEnv(),
+      timeout: 180_000,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { generated: fs.existsSync(lockPath), swaps: 0, reason: `npm resolve failed: ${msg}` };
+  }
+  if (!fs.existsSync(lockPath)) {
+    return { generated: false, swaps: 0, reason: "npm wrote no package-lock.json" };
+  }
+  // Normalize proxy -> public registry so a cold off-network install never hangs.
+  try {
+    const { text, swaps } = normalizeLockfileRegistry(fs.readFileSync(lockPath, "utf8"));
+    if (swaps > 0) fs.writeFileSync(lockPath, text);
+    return { generated: true, swaps };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { generated: true, swaps: 0, reason: `lock normalize failed: ${msg}` };
+  }
+}

package/scripts/lakebase/create-project.ts

@@ -28,6 +28,7 @@ import { scaffoldAll, substrateVersion } from "./scaffold.js";
 import type { ClientFramework } from "./scaffold-language.js";
 import { createLongRunningBranch } from "./long-running-branch.js";
 import { enableE2eForProject } from "./enable-e2e.js";
+import { ensureClientLockfile } from "./client-lockfile.js";
 import { enableInfraForProject } from "./enable-infra.js";
 import { setupRunner } from "./runner-setup.js";
 import { syncCiSecrets, missingCiSecrets } from "../util/ci-secrets.js";
@@ -587,6 +588,24 @@ export async function createProject(
     dotnet: `.NET/ASP.NET Core (${input.migrationTool === "flyway" ? "Flyway" : "EF Core"})`,
   };
   const langLabel = langLabels[language] ?? language;
+
+  // ── Step 7f: client lockfile (UI projects) ───────────────────
+  // Generate + registry-normalize client/package-lock.json BEFORE the commit so
+  // `git add -A` tracks it. Without this the scaffold ships no client lock, and
+  // the user's hand-generated one (made on the Databricks network) pins the npm
+  // proxy and hangs a cold off-network install. Non-fatal: warn + continue.
+  if (clientFramework !== "none") {
+    report("Generating client package-lock.json (registry-normalized)...");
+    const lock = await ensureClientLockfile({ projectDir });
+    if (lock.generated) {
+      report(`  wrote client/package-lock.json${lock.swaps > 0 ? ` (normalized ${lock.swaps} proxy URL(s) to the public registry)` : ""}`);
+    } else {
+      const m = `Could not generate client/package-lock.json (${lock.reason ?? "unknown"}). Generate it with: (cd client && npm install) — the lock is committed on first push.`;
+      warnings.push(m);
+      report(`WARNING: ${m}`);
+    }
+  }
+
   report("Creating initial commit...");
   await commitAndPush({
     projectDir,

package/scripts/lakebase/schema-migrate-runners/alembic.ts

@@ -14,7 +14,7 @@
 // stdout/stderr is not load-bearing here, which keeps the runner robust
 // to logger config drift in the consumer's `alembic.ini`.
 
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
@@ -32,26 +32,70 @@ interface RunnerCtx {
 }
 
 /**
- * Resolve the `alembic` binary path. uv-managed Python projects install
- * alembic into a per-project `.venv/bin/alembic`, which is NOT on the
- * runner's PATH. Spawning bare `alembic` fails with ENOENT in CI even
- * after `uv sync` succeeded. Prefer the project-local venv when it
- * exists; fall back to bare `alembic` for projects with a pre-activated
- * shell venv or a system-wide install.
+ * Whether `uv` is on PATH. Memoized: resolution runs per alembic subcommand and
+ * the answer cannot change within a process.
  */
-export function resolveAlembicBin(projectDir: string): string {
-  const candidates = [
+let uvOnPath: boolean | undefined;
+function hasUv(): boolean {
+  if (uvOnPath !== undefined) return uvOnPath;
+  try {
+    execFileSync("uv", ["--version"], { stdio: "ignore" });
+    uvOnPath = true;
+  } catch {
+    uvOnPath = false;
+  }
+  return uvOnPath;
+}
+
+/**
+ * Resolve HOW to invoke alembic in a project: an executable plus the args that
+ * must PREFIX the alembic subcommand.
+ *
+ * uv-managed Python projects install alembic into a per-project `.venv/bin/alembic`,
+ * which is NOT on the runner's PATH, so that venv-local bin is preferred when it
+ * exists (it is also what CI has after `uv sync`). But a FRESH clone / rehydrated
+ * project has no `.venv` yet (nothing has run `uv sync`), and spawning bare
+ * `alembic` then fails ENOENT — the failure the `lk lakebase-new-migration` path
+ * hit on a never-synced project, before any test run created the venv. For such a
+ * uv project (pyproject.toml present and `uv` on PATH) invoke via `uv run alembic`,
+ * which auto-creates the venv and syncs the declared deps (alembic is a top-level
+ * dep) BEFORE running — exactly what scripts/run-tests.sh relies on. CI is
+ * unaffected: it hits the venv-local bin first. Last resort is bare `alembic`
+ * (a pre-activated shell venv or a system-wide install).
+ */
+export function resolveAlembicInvocation(
+  projectDir: string,
+  uvAvailable: boolean = hasUv()
+): { bin: string; prefixArgs: string[] } {
+  const venvCandidates = [
     path.join(projectDir, ".venv", "bin", "alembic"),
     path.join(projectDir, "venv", "bin", "alembic"),
   ];
-  for (const candidate of candidates) {
+  for (const candidate of venvCandidates) {
     try {
-      if (fs.existsSync(candidate)) return candidate;
+      if (fs.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
       // best-effort; keep checking
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs.existsSync(path.join(projectDir, "pyproject.toml"))) {
+      return { bin: "uv", prefixArgs: ["run", "alembic"] };
+    }
+  } catch {
+    // best-effort; fall through to bare alembic
+  }
+  return { bin: "alembic", prefixArgs: [] };
+}
+
+/**
+ * Back-compat: the executable that would run alembic (the venv-local path or bare
+ * `alembic`). Prefer resolveAlembicInvocation, which also models the `uv run`
+ * prefix for a never-synced uv project.
+ */
+export function resolveAlembicBin(projectDir: string): string {
+  const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
+  return prefixArgs.length ? `${bin} ${prefixArgs.join(" ")}` : bin;
 }
 
 /**
@@ -65,7 +109,7 @@ function spawnAlembic(
   dsn?: string
 ): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
-    const bin = resolveAlembicBin(projectDir);
+    const { bin, prefixArgs } = resolveAlembicInvocation(projectDir);
     // Put the project root on PYTHONPATH so `app` is importable for EVERY alembic
     // subcommand. `upgrade` runs env.py (which prepends sys.path), but `history`
     // and other read-only commands do not, yet they still import every migration
@@ -74,7 +118,7 @@ function spawnAlembic(
     const env: NodeJS.ProcessEnv = { ...process.env };
     env.PYTHONPATH = [projectDir, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter);
     if (dsn) env.DATABASE_URL = dsn;
-    const child = spawn(bin, args, {
+    const child = spawn(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"],

package/templates/project/client/playwright.config.ts

@@ -1,21 +1,47 @@
 import { defineConfig, devices } from "@playwright/test";
 import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 
+// The backend lives at the project root, one level up from this client/ config
+// (Playwright runs from client/, hence cwd:".." on the webServers below).
+const ROOT = join(process.cwd(), "..");
+
 // End-to-end tests drive the rendered SPA through a real browser against the
 // real backend, backed by the paired Lakebase branch. Playwright boots BOTH
 // servers: the backend FIRST (so Vite's /api proxy has a target), then Vite.
 // Adapt the backend `command`/`url` to your stack if it is not Python/FastAPI.
 //
-// Resiliency: the ports are env-driven (E2E_BACKEND_PORT / E2E_CLIENT_PORT) with
-// the conventional defaults. In CI (reuseExistingServer:false), a stale server
-// left on 8000/5173 by a prior run would otherwise make webServer hard-fail with
-// "port already used". So CI's E2E step allocates FREE ports (scripts/port-utils.sh,
-// the same probe run-dev.sh uses) and hands them in here , the run moves off a
-// busy port instead of colliding. The Vite proxy is pointed at the resolved
-// backend port via VITE_PROXY_TARGET so /api + /health still reach the backend.
-const BACKEND_PORT = process.env.E2E_BACKEND_PORT ?? "8000";
-const CLIENT_PORT = process.env.E2E_CLIENT_PORT ?? "5173";
+// Resiliency: the ports are env-driven (E2E_BACKEND_PORT / E2E_CLIENT_PORT).
+// run-tests.sh and CI pre-allocate FREE ports (scripts/port-utils.sh) and hand them
+// in via those vars, so a stale server left on 8000/5173 by a prior run never makes
+// webServer hard-fail with "port already used". When NOTHING hands them in — a direct
+// `npx playwright test` (e.g. the build driver running a targeted spec, not through
+// run-tests.sh) — resolve a free port HERE the SAME way, by sourcing that one shared
+// free_port helper, so a direct run is just as collision-proof and never defaults onto
+// a busy :8000 / :5173. One free-port owner (port-utils.sh), two entry points. The Vite
+// proxy is pointed at the resolved backend port via VITE_PROXY_TARGET so /api + /health
+// still reach the backend wherever it landed.
+function resolvePort(envVar: string, fallback: number): string {
+  const fromEnv = process.env[envVar];
+  if (fromEnv) return fromEnv;
+  const portUtils = join(ROOT, "scripts", "port-utils.sh");
+  if (existsSync(portUtils)) {
+    try {
+      const out = execFileSync(
+        "bash",
+        ["-c", `source ${JSON.stringify(portUtils)} && free_port ${fallback}`],
+        { encoding: "utf8" }
+      ).trim();
+      if (/^\d+$/.test(out)) return out;
+    } catch {
+      // fall through to the conventional default
+    }
+  }
+  return String(fallback);
+}
+const BACKEND_PORT = resolvePort("E2E_BACKEND_PORT", 8000);
+const CLIENT_PORT = resolvePort("E2E_CLIENT_PORT", 5173);
 // Use 127.0.0.1, NOT localhost, and bind both servers to it (below). `localhost`
 // is ambiguous: on macOS it resolves to IPv6 ::1 first, but uvicorn binds IPv4
 // 127.0.0.1 only (its default) and Vite's dev server is likewise IPv4 — so a
@@ -31,7 +57,6 @@ const CLIENT_URL = `http://127.0.0.1:${CLIENT_PORT}`;
 // one level up from this client/ config (Playwright runs from client/, hence cwd:".." below). Pick
 // the migrate-before-serve command + health URL for the detected stack so E2E boots on ANY language
 // , a nodejs scaffold otherwise inherited the Python (alembic/uvicorn) command and could not start.
-const ROOT = join(process.cwd(), "..");
 function backendWebServer(): { command: string; url: string } {
   if (existsSync(join(ROOT, "pom.xml"))) {
     // Java/Kotlin (Spring): flyway migrate, then boot on the resolved port.