@databricks-solutions/lakebase-scm-utils 0.3.1 → 0.3.3

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

@@ -88240,8 +88240,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     return cached;
   }
   cached = "unknown";
@@ -89118,26 +89118,43 @@ init_cjs_shims();
 var import_node_child_process6 = require("child_process");
 var fs9 = __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_process6.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 (fs9.existsSync(candidate)) return candidate;
+      if (fs9.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs9.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((resolve3, 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_process6.spawn)(bin, args, {
+    const child = (0, import_node_child_process6.spawn)(bin, [...prefixArgs, ...args], {
       cwd: projectDir,
       env,
       stdio: ["ignore", "pipe", "pipe"]

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

@@ -9393,8 +9393,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     return cached;
   }
   cached = "unknown";
@@ -10268,29 +10268,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 execFileSync6 } from "child_process";
 import * as fs8 from "fs";
 import * as path8 from "path";
-function resolveAlembicBin(projectDir) {
-  const candidates = [
+var uvOnPath;
+function hasUv() {
+  if (uvOnPath !== void 0) return uvOnPath;
+  try {
+    execFileSync6("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 (fs8.existsSync(candidate)) return candidate;
+      if (fs8.existsSync(candidate)) return { bin: candidate, prefixArgs: [] };
     } catch {
     }
   }
-  return "alembic";
+  try {
+    if (uvAvailable && fs8.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((resolve3, 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-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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     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.1".length > 0) {
-    cached = "0.3.1";
+  if ("0.3.3".length > 0) {
+    cached = "0.3.3";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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/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,57 @@
 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;
+  let resolved = String(fallback);
+  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)) resolved = out;
+    } catch {
+      // fall through to the conventional default
+    }
+  }
+  // PERSIST the chosen port into the environment so Playwright's WORKER processes reuse it.
+  // Playwright evaluates this config in the main process AND re-evaluates it in each test
+  // worker. Without this, a worker re-runs resolvePort with E2E_CLIENT_PORT still unset, finds
+  // the port the main process picked (e.g. 5173) now TAKEN by the Vite webServer, allocates a
+  // DIFFERENT free port (5174), and points `baseURL` at 5174 where nothing listens — so the
+  // browser specs fail "not reachable" even though the app is healthy on the real port. Workers
+  // are spawned AFTER the main-process config load and inherit its process.env, so recording the
+  // resolution here makes every worker read it back via `fromEnv` above: resolve once, share it.
+  process.env[envVar] = resolved;
+  return resolved;
+}
+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 +67,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.

package/templates/project/python/app/database.py

@@ -118,9 +118,9 @@ class Base(DeclarativeBase):
     pass
 
 
-def get_db():
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
+# The request-scoped session DEPENDENCY (`get_session`) lives in the repository layer,
+# at `app/repositories/session.py` — NOT here. This module is pure infrastructure (engine,
+# SessionLocal, Base); keeping the per-request session door out of it is what lets a
+# service-backed feature's boundary stay off infrastructure (the layering contract). A route
+# that needs a session depends on the session a SERVICE exposes (sourced from the repository
+# layer), never `from app.database import ...` a session dependency.

package/templates/project/python/app/repositories/__init__.py

@@ -0,0 +1,8 @@
+"""Repository layer: the ONLY layer that touches the ORM / database session.
+
+Each feature's repositories (data access for one aggregate) live here, alongside
+the shared request-session door `session.get_session`. Business logic lives in the
+service layer above; persistence lives only here. A service-backed feature's
+boundary (routes) therefore never imports the DB session from infrastructure
+(`app.database`) — it depends on a session the service exposes, sourced here.
+"""