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

package/scripts/lakebase/create-project.ts

@@ -20,6 +20,8 @@ import {
 import {
   checkDatabricksAuth,
   databricksAuthPrereqMessage,
+  checkGitHubWorkflowScope,
+  githubWorkflowScopePrereqMessage,
   withLakebaseRollback,
   validateCreateInputs,
   dirIsEmpty,
@@ -289,6 +291,19 @@ export async function createProject(
     throw new Error(databricksAuthPrereqMessage(host, auth.reason));
   }
 
+  // ── GitHub token `workflow` scope precondition ────────────────
+  // The scaffold's final push commits .github/workflows/*, which GitHub rejects
+  // unless the token carries the `workflow` OAuth scope. Check it HERE, before any
+  // GitHub repo or Lakebase project exists, so a missing scope fails in seconds with
+  // a fix instead of at the final push after all provisioning (which then rolls back).
+  if (useGithub) {
+    report("Checking GitHub token scopes...");
+    const scope = await checkGitHubWorkflowScope();
+    if (!scope.ok) {
+      throw new Error(githubWorkflowScopePrereqMessage(scope.reason));
+    }
+  }
+
   // ── Step 1+2: GitHub repo + clone, OR local-only setup ────────
   if (useGithub) {
     report("Creating GitHub repository...", fullRepoName);

package/scripts/lakebase/doctor.ts

@@ -14,6 +14,7 @@ import { listBranches } from "./branch-utils.js";
 import { verifyHooks } from "./project-verify.js";
 import { detectLanguage } from "./schema-migrate.js";
 import { detectWorkflowDrift } from "./workflow-drift.js";
+import { checkGitHubScopes } from "../github/repo.js";
 
 export type CheckStatus = "ok" | "warn" | "fail" | "skip";
 
@@ -593,6 +594,53 @@ async function checkGitRemote(projectDir: string): Promise<CheckResult> {
   }
 }
 
+/**
+ * Probe whether the GitHub token carries the `workflow` scope needed to push
+ * `.github/workflows/*`. A missing scope is exactly why a scaffold push (or any
+ * later workflow edit) gets rejected at the very end and rolls back. Best-effort:
+ * no token, OR a fine-grained / GitHub App token (no visible OAuth scopes), OR
+ * an API error → `skip`, never a false `fail`. `probe` is injectable for tests.
+ */
+export async function checkGitHubTokenScope(
+  probe: () => Promise<{ granted: string[] | null; missing: string[] }> = () =>
+    checkGitHubScopes(["workflow"])
+): Promise<CheckResult> {
+  try {
+    const { granted, missing } = await probe();
+    if (granted === null) {
+      return {
+        name: "github-token-scope",
+        status: "skip",
+        message:
+          "GitHub token scopes not visible (fine-grained PAT / App token) - `workflow` scope unverified",
+      };
+    }
+    if (missing.includes("workflow")) {
+      return {
+        name: "github-token-scope",
+        status: "fail",
+        message:
+          "GitHub token lacks the `workflow` scope - pushes touching .github/workflows/* will be rejected",
+        detail: { granted },
+        hint: "Grant it with `gh auth refresh -h github.com -s workflow`, re-sign in to GitHub in VS Code and approve the workflow scope, or set GITHUB_TOKEN to a PAT that includes `workflow`.",
+      };
+    }
+    return {
+      name: "github-token-scope",
+      status: "ok",
+      message: "GitHub token has the `workflow` scope",
+      detail: { granted },
+    };
+  } catch (err) {
+    return {
+      name: "github-token-scope",
+      status: "skip",
+      message: "GitHub token scope check skipped (no token resolved, or GitHub unreachable)",
+      detail: { error: (err as Error).message },
+    };
+  }
+}
+
 function checkLanguage(projectDir: string): CheckResult {
   try {
     const lang = detectLanguage(projectDir);
@@ -732,6 +780,7 @@ export async function runDoctor(args: DoctorArgs = {}): Promise<DoctorReport> {
     host
   );
   const gitRemote = await checkGitRemote(projectDir);
+  const githubTokenScope = await checkGitHubTokenScope();
   const language = checkLanguage(projectDir);
   const hooks = checkHooks(projectDir);
   const workflowDrift = checkWorkflowDrift(projectDir);
@@ -763,6 +812,7 @@ export async function runDoctor(args: DoctorArgs = {}): Promise<DoctorReport> {
     configProfile,
     lakebaseProject,
     gitRemote,
+    githubTokenScope,
     language,
     hooks,
     workflowDrift,

package/templates/project/client/consort-vitest-reporter.ts

@@ -0,0 +1,96 @@
+// Consort per-test "green as it runs" reporter for Vitest (client component/hook tests).
+//
+// Mirrors the Playwright reporter: a test whose name carries `@T<id>` streams its lifecycle to
+// `.consort/test-run.jsonl` so the Consort dashboard lights that bubble. Reuses the single
+// `emitTestRun` writer from the shared Playwright reporter one directory up (`../consort-test-reporter`)
+// — one writer, one JSONL shape, one `.consort` resolver.
+//
+// Recent Vitest (the "Reported Tasks" reporter API, v2.1+) fires per-test hooks, so we stream
+// `running` the moment a test starts and the final status when it ends. OLDER Vitest does not fire
+// those hooks — so `onFinished` is a BATCH BACKSTOP that emits any test the per-test hooks did not
+// already handle (tracked in `handled`), giving a correct end-of-run signal on any version. Typed
+// structurally (not against vitest's own types) so a vitest major bump can't break the build;
+// everything is wrapped so a reporter error can never fail the suite.
+import { emitTestRun, type TestRunStatus } from "../consort-capture";
+
+const TEST_ID = /@(T\d+(?:-[a-z0-9-]+)?)/;
+
+// NOTE: per-test TABLE-STATE capture does NOT live here — it is in `tests/setup.ts`'s afterEach,
+// which runs in the WORKER process where the booted backend's base URL (`.consort/.vitest-backend`)
+// actually resolves. This reporter runs in the MAIN process, where that base did not resolve, so a
+// capture here silently no-op'd. This reporter is purely the per-test STATUS stream (test-run.jsonl).
+
+function idOf(name: string | undefined): string | undefined {
+  return TEST_ID.exec(name ?? "")?.[1];
+}
+
+function stateToStatus(state: string | undefined): TestRunStatus {
+  return state === "pass" || state === "passed" ? "green" : state === "skip" || state === "skipped" ? "skipped" : "red";
+}
+
+// --- Modern "Reported Tasks" shapes (duck-typed) ---------------------------------------------
+interface ReportedTestCase {
+  name?: string;
+  module?: { moduleId?: string; id?: string };
+  result?: (() => { state?: string } | undefined) | { state?: string };
+}
+
+function moduleIdOf(tc: ReportedTestCase): string {
+  return tc.module?.moduleId ?? tc.module?.id ?? "";
+}
+
+function resultStateOf(tc: ReportedTestCase): string | undefined {
+  const r = typeof tc.result === "function" ? tc.result() : tc.result;
+  return r?.state;
+}
+
+// --- Legacy onFinished task tree (duck-typed) ------------------------------------------------
+interface VitestTaskLike {
+  type?: string;
+  name?: string;
+  mode?: string;
+  result?: { state?: string };
+  tasks?: VitestTaskLike[];
+  filepath?: string;
+}
+
+export default class ConsortVitestReporter {
+  // Keys (`file\0name`) already emitted by the per-test hooks, so the onFinished backstop skips
+  // them on recent Vitest and only fires for versions where the per-test hooks never ran.
+  private handled = new Set<string>();
+
+  onTestCaseReady(testCase: ReportedTestCase): void {
+    const id = idOf(testCase.name);
+    if (id) emitTestRun(id, "running", moduleIdOf(testCase), "client");
+  }
+
+  onTestCaseResult(testCase: ReportedTestCase): void {
+    const id = idOf(testCase.name);
+    if (!id) return;
+    const file = moduleIdOf(testCase);
+    this.handled.add(`${file}\u0000${testCase.name ?? ""}`);
+    emitTestRun(id, stateToStatus(resultStateOf(testCase)), file, "client");
+  }
+
+  onFinished(files: VitestTaskLike[] = []): void {
+    try {
+      for (const f of files) this.walk(f, f.filepath ?? "");
+    } catch {
+      /* best-effort: a per-test reporter write must never fail the suite */
+    }
+  }
+
+  private walk(task: VitestTaskLike, file: string): void {
+    const isLeaf = task.type === "test" || task.type === "custom" || (!task.tasks && !!task.result);
+    if (isLeaf) {
+      const id = idOf(task.name);
+      if (!id) return;
+      if (this.handled.has(`${file}\u0000${task.name ?? ""}`)) return; // already streamed by the per-test hooks
+      const st = task.result?.state;
+      const status: TestRunStatus = st === "pass" ? "green" : st === "skip" || task.mode === "skip" ? "skipped" : "red";
+      emitTestRun(id, status, file, "client");
+      return;
+    }
+    for (const child of task.tasks ?? []) this.walk(child, file);
+  }
+}

package/templates/project/client/package.json

@@ -23,6 +23,7 @@
     "@testing-library/jest-dom": "^6.4.8",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^20.14.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.1",

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

@@ -101,7 +101,12 @@ export default defineConfig({
   workers: 1,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  reporter: process.env.CI ? [["list"], ["html", { open: "never" }]] : "list",
+  // `../consort-test-reporter.ts` (shared with the root config) appends each `@T<id>`-tagged test
+  // to `.consort/test-run.jsonl` as it finishes, for the dashboard's per-test live signal. It walks
+  // up from cwd to the project `.consort`, so running from client/ still finds the right ledger.
+  reporter: process.env.CI
+    ? [["list"], ["html", { open: "never" }], ["../consort-test-reporter.ts"]]
+    : [["list"], ["../consort-test-reporter.ts"]],
   use: {
     baseURL: CLIENT_URL,
     trace: "on-first-retry",

package/templates/project/client/tests/e2e/about.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { test, expect } from "./consort-fixtures";
 
 // The reachability pattern proven end-to-end: a feature page is reachable by
 // NAVIGATING the real app (a navbar link / a route), not just by mounting the

package/templates/project/client/tests/e2e/consort-fixtures.ts

@@ -0,0 +1,23 @@
+// Consort e2e test fixture: tag every spec's browser requests with the X-Consort-Test-Id header,
+// derived from the test title's @T<id>. The backend's per-test capture (app/consort_capture.py) uses
+// it to attribute the rows this spec RETRIEVES/STORES — the same per-test key the Vitest fetch shim
+// and the pytest client fixture set, so the dashboard's per-test table view works for e2e specs too.
+//
+// Import { test, expect } from THIS module in e2e specs instead of "@playwright/test" — nothing else
+// changes. (The header rides through Vite's /api proxy to the backend; it's inert in production.)
+import { test as base } from "@playwright/test";
+
+// Re-export EVERYTHING from @playwright/test (expect, devices, types like APIRequestContext, …) so a
+// spec imports solely from here; the local `test` below overrides the re-exported one (an explicit
+// export shadows a star re-export of the same name).
+export * from "@playwright/test";
+
+const TEST_ID = /@(T\d+(?:-[a-z0-9-]+)?)/;
+
+export const test = base.extend({
+  page: async ({ page }, use, testInfo) => {
+    const id = TEST_ID.exec(testInfo.title)?.[1];
+    if (id) await page.setExtraHTTPHeaders({ "X-Consort-Test-Id": id });
+    await use(page);
+  },
+});

package/templates/project/client/tests/e2e/home.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { test, expect } from "./consort-fixtures";
 
 // The one behavior a fresh scaffold can prove end-to-end: the SPA loads, calls
 // the backend /health through the Vite proxy, and shows the result as an

package/templates/project/client/tests/setup.ts

@@ -1,10 +1,85 @@
-// Vitest global setup: extends expect() with jest-dom matchers and clears the
-// DOM + mocks between tests so each test starts from a known state.
+// Vitest setup: extends expect() with jest-dom matchers and clears the DOM between tests.
+//
+// Kit principle — never mock when a real counterpart exists: component tests hit the REAL backend
+// over the REAL `/api` boundary. jsdom has no origin, so a relative `fetch("/api/stock")` throws
+// "Failed to parse URL"; this shim prefixes relative `/api` + `/health` with the backend the global
+// setup (`vitest.globalSetup.ts`) booted and published to `.consort/.vitest-backend`. The component
+// still only speaks HTTP — it never touches the DB. When no backend was booted (no base file) the
+// shim is inert, so a pure-presentation component test is unaffected.
 import "@testing-library/jest-dom/vitest";
-import { afterEach, vi } from "vitest";
+import { afterEach, beforeEach, vi } from "vitest";
 import { cleanup } from "@testing-library/react";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { captureTablesFromRoute } from "../../consort-capture";
 
-afterEach(() => {
+const TEST_ID = /@(T\d+(?:-[a-z0-9-]+)?)/;
+
+// The @T<id> of the test currently running, so the fetch shim can tag each /api request with it (the
+// backend attributes the rows the request RETRIEVES/STORED to this test — app/consort_capture.py).
+let currentTestId: string | null = null;
+beforeEach((ctx: { task?: { name?: string } }) => {
+  currentTestId = TEST_ID.exec(ctx?.task?.name ?? "")?.[1] ?? null;
+});
+
+function backendBase(): string {
+  let d = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    try {
+      return readFileSync(join(d, ".consort", ".vitest-backend"), "utf8").trim();
+    } catch {
+      /* walk up to the project root */
+    }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return "";
+}
+
+const BACKEND_BASE = backendBase();
+if (BACKEND_BASE) {
+  const realFetch = globalThis.fetch.bind(globalThis);
+  const isApi = (u: string): boolean => u.startsWith("/api") || u.startsWith("/health");
+  const reroute = (url: string): string => (isApi(url) ? BACKEND_BASE + url : url);
+  // Add the X-Consort-Test-Id header to each /api request so the backend's per-test capture can key
+  // the rows this request reads/writes to the running test.
+  const tag = (url: string, init?: RequestInit): RequestInit | undefined => {
+    if (!currentTestId || !isApi(url)) return init;
+    const headers = new Headers(init?.headers);
+    headers.set("X-Consort-Test-Id", currentTestId);
+    return { ...init, headers };
+  };
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    if (typeof input === "string") return realFetch(reroute(input), tag(input, init));
+    if (input instanceof URL) {
+      const u = input.toString();
+      return realFetch(reroute(u), tag(u, init));
+    }
+    if (input instanceof Request && input.url.startsWith("/")) {
+      const r = new Request(reroute(input.url), input);
+      if (currentTestId && isApi(input.url)) r.headers.set("X-Consort-Test-Id", currentTestId);
+      return realFetch(r, init);
+    }
+    return realFetch(input, init);
+  }) as typeof fetch;
+}
+
+// Per-test table-state capture lives HERE (the worker), not in the reporter: `BACKEND_BASE` is
+// resolved in the worker after globalSetup booted the backend (same read the shim above proved
+// works), whereas the reporter runs in the MAIN process where that base did not resolve — so the
+// reporter's capture silently no-op'd. Running it in afterEach is also version-independent (always
+// fires) and has the current test in context. Captures the DB state THIS component test left, keyed
+// by its @T<id>, via the app's snapshot route (shared writer with the pytest/Playwright reporters).
+afterEach(async (ctx: { task?: { name?: string; file?: { filepath?: string } } }) => {
   cleanup();
   vi.restoreAllMocks();
+  if (!BACKEND_BASE) return;
+  const id = TEST_ID.exec(ctx?.task?.name ?? "")?.[1];
+  if (!id) return;
+  try {
+    await captureTablesFromRoute(BACKEND_BASE, id, ctx?.task?.file?.filepath ?? "");
+  } catch {
+    /* best-effort: a snapshot write must never fail the test */
+  }
 });

package/templates/project/client/tsconfig.json

@@ -15,7 +15,7 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
-    "types": ["vitest/globals", "@testing-library/jest-dom"]
+    "types": ["vitest/globals", "@testing-library/jest-dom", "node"]
   },
   "include": ["src", "tests/setup.ts"]
 }

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

@@ -33,6 +33,14 @@ export default defineConfig({
     environment: "jsdom",
     globals: true,
     setupFiles: "./tests/setup.ts",
+    // Boot a REAL backend (migrated, against the paired branch) for the whole component run, so
+    // component tests hit the real `/api` service — never a mock (kit principle). The fetch shim in
+    // tests/setup.ts routes relative `/api` to it. Torn down after. See vitest.globalSetup.ts.
+    globalSetup: "./vitest.globalSetup.ts",
+    // Keep Vitest's own `default` reporter for humans, and add the Consort per-test reporter:
+    // it appends each `@T<id>`-named test to `.consort/test-run.jsonl` as it finishes, so the
+    // dashboard lights client tests live alongside the backend (pytest) and E2E (Playwright) ones.
+    reporters: ["default", "./consort-vitest-reporter.ts"],
     include: ["src/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
     exclude: [...configDefaults.exclude, "tests/e2e/**"],
     css: false,

package/templates/project/client/vitest.globalSetup.ts

@@ -0,0 +1,121 @@
+// Vitest global setup — boot a REAL backend for the component suite.
+//
+// Kit principle: never mock when a real counterpart exists. Client component tests must hit the
+// REAL backend over the REAL `/api` boundary (which hits the real paired-branch DB), exactly like
+// production — the client never gets direct DB access. This mirrors `playwright.config.ts`'s backend
+// webServer: migrate the branch, serve the app on a free 127.0.0.1 port, wait for health, and
+// publish the base URL to `.consort/.vitest-backend` for the fetch shim in `tests/setup.ts`. Torn
+// down after the run. Language-aware (python / node / java), same detection as the Playwright config.
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+
+const ROOT = join(process.cwd(), ".."); // vitest runs from client/
+const CLIENT = join(ROOT, "client");
+const BASE_FILE = join(ROOT, ".consort", ".vitest-backend");
+
+// True iff the project has at least one component test (`*.test.tsx|ts` under client/src or
+// client/tests, excluding the Playwright `tests/e2e/` dir). When there are none, booting a backend
+// is pure waste and an avoidable failure surface — so the setup is a no-op (returns early). This is
+// what keeps a component-less project (e.g. one whose UI is all Playwright E2E) from paying for, or
+// failing on, a backend boot it never uses.
+function hasComponentTests(): boolean {
+  const stack: string[] = [join(CLIENT, "src"), join(CLIENT, "tests")];
+  while (stack.length) {
+    const dir = stack.pop()!;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const abs = join(dir, e);
+      if (abs.replace(/\\/g, "/").includes("/tests/e2e")) continue; // Playwright's, not Vitest's
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) stack.push(abs);
+      else if (/\.test\.(ts|tsx|js|jsx)$/.test(e)) return true;
+    }
+  }
+  return false;
+}
+
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+// migrate-before-serve command + health URL for the detected stack (mirrors the Playwright config).
+function backend(port: number): { shell: string; health: string } {
+  if (existsSync(join(ROOT, "pom.xml"))) {
+    return {
+      shell: `./mvnw -q flyway:migrate && ./mvnw -q spring-boot:run -Dspring-boot.run.arguments=--server.port=${port}`,
+      health: `http://127.0.0.1:${port}/actuator/health`,
+    };
+  }
+  if (
+    existsSync(join(ROOT, "package.json")) &&
+    !existsSync(join(ROOT, "pyproject.toml")) &&
+    !existsSync(join(ROOT, "requirements.txt"))
+  ) {
+    return { shell: `npm run migrate && PORT=${port} npm run start`, health: `http://127.0.0.1:${port}/health` };
+  }
+  return {
+    shell: `uv run alembic upgrade head && uv run uvicorn app.main:app --host 127.0.0.1 --port ${port}`,
+    health: `http://127.0.0.1:${port}/health`,
+  };
+}
+
+let proc: ChildProcess | undefined;
+
+export default async function setup(ctx?: { provide?: (k: string, v: unknown) => void }): Promise<() => Promise<void>> {
+  if (!hasComponentTests()) {
+    // No component tests → nothing to serve a backend for. No-op teardown.
+    return async () => {};
+  }
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const { shell, health } = backend(port);
+  proc = spawn("bash", ["-c", shell], { cwd: ROOT, stdio: "ignore", env: { ...process.env } });
+
+  const deadline = Date.now() + 120_000;
+  for (;;) {
+    try {
+      const r = await fetch(health);
+      if (r.ok) break;
+    } catch {
+      /* backend not up yet */
+    }
+    if (Date.now() > deadline) {
+      if (proc && !proc.killed) proc.kill("SIGTERM");
+      throw new Error(`vitest: backend did not become healthy at ${health} within 120s`);
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  mkdirSync(join(ROOT, ".consort"), { recursive: true });
+  writeFileSync(BASE_FILE, base); // the fetch shim reads this (pool-agnostic)
+  ctx?.provide?.("consortApiBase", base);
+
+  return async () => {
+    try {
+      rmSync(BASE_FILE);
+    } catch {
+      /* already gone */
+    }
+    if (proc && !proc.killed) proc.kill("SIGTERM");
+  };
+}

package/templates/project/common/.github/workflows/pr.yml

@@ -148,11 +148,6 @@ jobs:
       # the CI branch is provisioned and fail fast. `--if-present` no-ops a
       # client with no `test` script. The client's Playwright E2E runs later
       # (its own step, gated on client/playwright.config.ts).
-      - name: Run client unit tests
-        if: hashFiles('client/package.json') != ''
-        working-directory: client
-        run: npm run test --if-present
-
       # The official action installs to a user-writable path (no sudo). It's
       # a no-op if a compatible databricks CLI is already on PATH.
       - name: Install Databricks CLI
@@ -384,6 +379,20 @@ jobs:
             --pretty
           echo "Migrations completed."
 
+      - name: Run client unit tests
+        # The kit's client/vitest.globalSetup.ts boots a REAL backend over the /api
+        # boundary (never mock when a real counterpart exists), so the component suite
+        # NEEDS the CI Lakebase branch + DATABASE_URL. Run it AFTER datasource config +
+        # migrations, not before. No-op when there are no component tests (globalSetup
+        # returns early); skipped when there is no CI Lakebase branch (url empty).
+        if: hashFiles('client/package.json') != '' && steps.lakebase-db.outputs.url != ''
+        working-directory: client
+        env:
+          DATABASE_URL: ${{ env.DATABASE_URL }}
+          DB_USERNAME: ${{ env.DB_USERNAME }}
+          DB_PASSWORD: ${{ env.DB_PASSWORD }}
+        run: npm run test --if-present
+
       - name: Run tests
         env:
           DATABASE_URL: ${{ env.DATABASE_URL }}

package/templates/project/common/consort-capture.ts

@@ -0,0 +1,87 @@
+// Consort per-test capture writers — FRAMEWORK-AGNOSTIC (no Playwright, no Vitest import).
+//
+// These are the shared, pure Node helpers the three test reporters use to stream per-test signals to
+// `.consort/`: the status trail (`test-run.jsonl`) the dashboard tails to light bubbles, and the
+// per-test table snapshots (`table-snapshots.jsonl`) the dashboard reads for its table view. They
+// live in their OWN module (not in `consort-test-reporter.ts`) precisely because that file imports
+// `@playwright/test/reporter` for the Playwright Reporter class — and the Vitest client compile
+// (`tests/setup.ts` captures table state in an afterEach) must NOT drag Playwright's types through
+// the client's bundler-resolution tsconfig. Importing these from here keeps the client Playwright-free.
+//
+// Pure observability: everything is wrapped so a write can NEVER fail a test/suite.
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Walk up from `start` to the project's `.consort` dir (tests run from root OR client/, so cwd
+ *  varies); fall back to `<cwd>/.consort` (created on write) if none is found. */
+export function findConsortDir(start: string): string {
+  let d = start;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(d, ".consort"))) return join(d, ".consort");
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return join(start, ".consort");
+}
+
+export type TestRunStatus = "running" | "green" | "red" | "skipped";
+
+export function emitTestRun(id: string, status: TestRunStatus, absFile: string, kind: string): void {
+  try {
+    const dir = findConsortDir(process.cwd());
+    mkdirSync(dir, { recursive: true });
+    const root = dirname(dir);
+    const file = (absFile || "").replace(`${root}/`, "");
+    appendFileSync(
+      join(dir, "test-run.jsonl"),
+      JSON.stringify({ ts: new Date().toISOString(), test_id: id, status, file, kind }) + "\n",
+    );
+  } catch {
+    /* best-effort: a per-test reporter write must never fail the suite */
+  }
+}
+
+/** Append a per-test TABLE snapshot (one line per table) to `.consort/table-snapshots.jsonl`, keyed
+ *  by test id — parallel to `emitTestRun`. Best-effort. */
+export function emitTableSnapshot(id: string, absFile: string, table: string, rows: unknown[], rowCount: number | null): void {
+  try {
+    const dir = findConsortDir(process.cwd());
+    mkdirSync(dir, { recursive: true });
+    const root = dirname(dir);
+    const file = (absFile || "").replace(`${root}/`, "");
+    appendFileSync(
+      join(dir, "table-snapshots.jsonl"),
+      JSON.stringify({ ts: new Date().toISOString(), test_id: id, file, table, rows, row_count: rowCount }) + "\n",
+    );
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Capture the DB state a test left — for the dashboard's per-test table view — by asking the app's
+ *  read-only `/api/_consort/table-snapshot` route (the client never touches the DB; the app, which the
+ *  test hit over `/api`, reports its rows). Writes one `emitTableSnapshot` per table, keyed by test id.
+ *  Shared by the Playwright (e2e) AND Vitest (component) paths — both drive the DB THROUGH the app.
+ *  Best-effort + time-boxed: a missing route (prod app) or a slow/unreachable endpoint just skips it. */
+export async function captureTablesFromRoute(baseURL: string, id: string, absFile: string): Promise<void> {
+  if (!baseURL) return;
+  try {
+    // Time-box with Promise.race, NOT an AbortController signal: this runs in BOTH Node (Playwright /
+    // pytest reporters) and jsdom (Vitest component afterEach), and a jsdom-realm AbortSignal is not an
+    // instance of the AbortSignal Node's undici fetch expects ("Expected signal to be an instance of
+    // AbortSignal") — it throws there and the capture silently no-ops. A dangling GET on timeout is a
+    // harmless read-only best-effort call.
+    const res = await Promise.race([
+      fetch(`${baseURL.replace(/\/$/, "")}/api/_consort/table-snapshot`),
+      new Promise<Response>((_, reject) => setTimeout(() => reject(new Error("snapshot timeout")), 4000)),
+    ]);
+    if (!res.ok) return;
+    const tables = (await res.json()) as Record<string, { rows?: unknown[]; row_count?: number | null }>;
+    for (const [table, data] of Object.entries(tables)) {
+      emitTableSnapshot(id, absFile, table, data.rows ?? [], data.row_count ?? null);
+    }
+  } catch {
+    /* route absent (prod) / unreachable / timed out — skip the snapshot */
+  }
+}