@elench/testkit 0.1.115 → 0.1.117

package/lib/database/source-refresh-lock.mjs

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+
+const DEFAULT_STALE_MS = 10 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 120 * 1000;
+const DEFAULT_POLL_MS = 100;
+
+export async function withSourceSchemaRefreshLock(lockPath, task, options = {}) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const staleMs = options.staleMs || DEFAULT_STALE_MS;
+  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const pollMs = options.pollMs || DEFAULT_POLL_MS;
+  const startedAt = Date.now();
+
+  let waited = false;
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, "wx");
+      try {
+        fs.writeFileSync(
+          fd,
+          `${JSON.stringify(
+            {
+              pid: process.pid,
+              createdAt: new Date().toISOString(),
+            },
+            null,
+            2
+          )}\n`
+        );
+      } finally {
+        fs.closeSync(fd);
+      }
+
+      try {
+        return await task({ waited, requestedAt: startedAt });
+      } finally {
+        fs.rmSync(lockPath, { force: true });
+      }
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      waited = true;
+      removeStaleLock(lockPath, staleMs);
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Timed out waiting for source schema refresh lock: ${lockPath}`);
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+export function getSourceSchemaRefreshLockPath(cachePath) {
+  return path.join(path.dirname(cachePath), "source-schema.refresh.lock");
+}
+
+function removeStaleLock(lockPath, staleMs) {
+  try {
+    const stat = fs.statSync(lockPath);
+    if (Date.now() - stat.mtimeMs > staleMs) {
+      fs.rmSync(lockPath, { force: true });
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/database/source-url.mjs

@@ -0,0 +1,110 @@
+const NEON_HOST_SUFFIX = ".neon.tech";
+const NEON_POOLER_MARKER = "-pooler.";
+const UNSUPPORTED_POOLER_PATTERN = /(^|[-.])(pgbouncer|pooler)([-.]|$)/i;
+
+export function resolveSourceSchemaDumpUrl(databaseUrl) {
+  const original = parseDatabaseUrl(databaseUrl);
+  const originalClassification = classifyDatabaseHost(original.hostname);
+
+  if (originalClassification.kind === "neon-pooler") {
+    const resolved = new URL(original.url.href);
+    resolved.hostname = original.hostname.replace(NEON_POOLER_MARKER, ".");
+    return buildResolution({
+      original,
+      resolved,
+      originalClassification,
+      resolvedClassification: classifyDatabaseHost(resolved.hostname),
+      rewritten: true,
+      notice: "Source schema URL uses Neon pooler; Testkit is using the direct endpoint for pg_dump.",
+    });
+  }
+
+  if (originalClassification.kind === "unsupported-pooler") {
+    throw new Error(
+      [
+        "Refusing to run pg_dump through a pooled source database URL.",
+        `Host: ${original.hostname}`,
+        "Configure a direct source database URL.",
+      ].join("\n")
+    );
+  }
+
+  return buildResolution({
+    original,
+    resolved: original.url,
+    originalClassification,
+    resolvedClassification: originalClassification,
+    rewritten: false,
+    notice: null,
+  });
+}
+
+export function classifyDatabaseHost(hostname) {
+  const host = String(hostname || "").toLowerCase();
+  if (host.endsWith(NEON_HOST_SUFFIX) && host.includes(NEON_POOLER_MARKER)) {
+    return { kind: "neon-pooler", host };
+  }
+  if (host.endsWith(NEON_HOST_SUFFIX)) {
+    return { kind: "neon-direct", host };
+  }
+  if (UNSUPPORTED_POOLER_PATTERN.test(host)) {
+    return { kind: "unsupported-pooler", host };
+  }
+  return { kind: "unknown-direct", host };
+}
+
+export function redactDatabaseUrl(databaseUrl) {
+  try {
+    const parsed = new URL(databaseUrl);
+    if (parsed.username) parsed.username = "REDACTED";
+    if (parsed.password) parsed.password = "REDACTED";
+    return parsed.toString();
+  } catch {
+    return "[invalid database URL]";
+  }
+}
+
+export function assertPgDumpArgsAreSourceSafe(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index]);
+    if (arg === "-j" || arg === "--jobs" || arg.startsWith("--jobs=")) {
+      throw new Error("Source schema pg_dump must not use parallel jobs.");
+    }
+  }
+}
+
+function parseDatabaseUrl(databaseUrl) {
+  try {
+    const url = new URL(databaseUrl);
+    if (!url.hostname) throw new Error("missing host");
+    return {
+      url,
+      hostname: url.hostname.toLowerCase(),
+    };
+  } catch (error) {
+    throw new Error(`Invalid source database URL: ${error?.message || error}`);
+  }
+}
+
+function buildResolution({
+  original,
+  resolved,
+  originalClassification,
+  resolvedClassification,
+  rewritten,
+  notice,
+}) {
+  return {
+    originalUrl: original.url.href,
+    dumpUrl: resolved.href,
+    rewritten,
+    notice,
+    metadata: {
+      originalHost: original.hostname,
+      originalClassification: originalClassification.kind,
+      resolvedHost: resolved.hostname.toLowerCase(),
+      resolvedClassification: resolvedClassification.kind,
+      rewritten,
+    },
+  };
+}

package/lib/database/template-steps.mjs

@@ -1,4 +1,5 @@
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { execa } from "execa";
 import { buildTemplateExecutionEnv } from "../runner/template.mjs";
@@ -7,6 +8,7 @@ import {
   runConfiguredSteps,
 } from "../runner/template-steps.mjs";
 import { captureOutput } from "../runner/processes.mjs";
+import { assertPgDumpArgsAreSourceSafe } from "./source-url.mjs";
 
 export async function runTemplateStage(config, stageName, databaseUrl, options = {}) {
   const steps = config.testkit.database?.template?.[stageName] || [];
@@ -25,6 +27,25 @@ export async function runTemplateStage(config, stageName, databaseUrl, options =
     reporter: options.reporter || null,
     setupRegistry: options.setupRegistry || null,
     parentOperation: options.parentOperation || null,
+    afterStep: options.afterStep || null,
+  });
+}
+
+export async function runTemplateStep(config, stageName, step, stepIndex, databaseUrl, options = {}) {
+  const env = {
+    ...buildTemplateExecutionEnv(config, {}, process.env),
+    DATABASE_URL: databaseUrl,
+  };
+
+  await runConfiguredSteps({
+    config,
+    steps: [step],
+    env,
+    labelPrefix: `template:${stageName}`,
+    reporter: options.reporter || null,
+    setupRegistry: options.setupRegistry || null,
+    parentOperation: options.parentOperation || null,
+    startIndex: stepIndex,
   });
 }
 
@@ -36,45 +57,101 @@ export function collectTemplateInputs(productDir, template = {}) {
   });
 }
 
-export async function captureTemplateSnapshot(config, outputPath, databaseUrl, options = {}) {
-  const templateDbUrl = databaseUrl;
-  const absoluteOutputPath = path.resolve(config.productDir, outputPath);
-  fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
+export async function captureTemplateSnapshotText(config, databaseUrl, options = {}) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-schema-snapshot-"));
+  const tempPath = path.join(tempDir, "schema.sql");
+  try {
+    await dumpPostgresSchemaToFile(config, tempPath, databaseUrl, options);
+    return fs.readFileSync(tempPath, "utf8");
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
 
-  const child = execa(
-    "pg_dump",
+export async function dumpPostgresSchemaToFile(config, outputPath, databaseUrl, options = {}) {
+  const env = {
+    ...buildTemplateExecutionEnv(config, {}, options.env || process.env),
+    ...buildPostgresConnectionEnv(databaseUrl, {
+      applicationName: options.pgApplicationName,
+    }),
+  };
+  const args = pgDumpArgs();
+  assertPgDumpArgsAreSourceSafe(args);
+  const result = await runPgDumpCommand(config, "pg_dump", args, env, options);
+  if (result.exitCode !== 0 && isPgDumpServerVersionMismatch(result)) {
+    const serverMajor = parsePgDumpServerMajor(result);
+    if (serverMajor) {
+      const fallback = await runDockerizedPgDump(config, serverMajor, env, args, options);
+      if (fallback.exitCode === 0) {
+        fs.writeFileSync(outputPath, fallback.stdout);
+        sanitizeSnapshotFile(outputPath);
+        return;
+      }
+      throw new Error(fallback.shortMessage || fallback.stderr || fallback.stdout || "dockerized pg_dump failed");
+    }
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(result.shortMessage || result.stderr || result.stdout || "pg_dump failed");
+  }
+  fs.writeFileSync(outputPath, result.stdout);
+  sanitizeSnapshotFile(outputPath);
+}
+
+export function pgDumpArgs() {
+  return [
+    "--schema-only",
+    "--no-owner",
+    "--no-privileges",
+  ];
+}
+
+async function runDockerizedPgDump(config, serverMajor, env, pgDumpCommandArgs, options) {
+  const image = `${process.env.TESTKIT_PG_DUMP_IMAGE_PREFIX || "postgres"}:${serverMajor}`;
+  return runPgDumpCommand(
+    config,
+    "docker",
     [
-      "--schema-only",
-      "--no-owner",
-      "--no-privileges",
-      "--file",
-      absoluteOutputPath,
-      templateDbUrl,
+      "run",
+      "--rm",
+      "--network",
+      "host",
+      "-e",
+      "PGHOST",
+      "-e",
+      "PGPORT",
+      "-e",
+      "PGDATABASE",
+      "-e",
+      "PGUSER",
+      "-e",
+      "PGPASSWORD",
+      "-e",
+      "PGSSLMODE",
+      "-e",
+      "PGAPPNAME",
+      image,
+      "pg_dump",
+      ...pgDumpCommandArgs,
     ],
-    {
-      cwd: config.productDir,
-      env: {
-        ...buildTemplateExecutionEnv(config, {}, process.env),
-        DATABASE_URL: templateDbUrl,
-      },
-      stdout: "pipe",
-      stderr: "pipe",
-      reject: false,
-    }
+    env,
+    options
   );
+}
+
+async function runPgDumpCommand(config, command, args, env, options = {}) {
+  const child = execa(command, args, {
+    cwd: config.productDir,
+    env,
+    stdout: "pipe",
+    stderr: "pipe",
+    reject: false,
+  });
   const liveWriter =
     options.reporter?.outputMode === "debug"
       ? (line) => options.reporter.writeDebugLine?.(line)
       : null;
   const logRecord = options.logRecord || null;
   const drains = [
-    captureOutput(child.stdout, {
-      livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
-      liveWriter,
-      onLine(line) {
-        if (logRecord) logRecord.stream.write(`${new Date().toISOString()} [stdout] ${line}\n`);
-      },
-    }),
     captureOutput(child.stderr, {
       livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
       liveWriter,
@@ -85,29 +162,80 @@ export async function captureTemplateSnapshot(config, outputPath, databaseUrl, o
   ];
   const result = await child;
   await Promise.all(drains);
-  if (result.exitCode !== 0) {
-    throw new Error(result.shortMessage || result.stderr || result.stdout || "pg_dump failed");
-  }
+  return result;
+}
+
+function isPgDumpServerVersionMismatch(result) {
+  const text = `${result.stderr || ""}\n${result.stdout || ""}`;
+  return text.includes("server version mismatch");
+}
 
-  sanitizeSnapshotFile(absoluteOutputPath);
-  return absoluteOutputPath;
+function parsePgDumpServerMajor(result) {
+  const text = `${result.stderr || ""}\n${result.stdout || ""}`;
+  const match = text.match(/server version:\s*([0-9]+)/i);
+  return match ? Number(match[1]) : null;
+}
+
+function buildPostgresConnectionEnv(databaseUrl, options = {}) {
+  const parsed = new URL(databaseUrl);
+  return compactObject({
+    PGHOST: parsed.hostname,
+    PGPORT: parsed.port || "5432",
+    PGDATABASE: decodeURIComponent(parsed.pathname.replace(/^\//, "")),
+    PGUSER: decodeURIComponent(parsed.username || ""),
+    PGPASSWORD: decodeURIComponent(parsed.password || ""),
+    PGSSLMODE: parsed.searchParams.get("sslmode") || undefined,
+    PGAPPNAME: options.applicationName || undefined,
+  });
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([_key, entry]) => entry !== undefined && entry !== null && entry !== "")
+  );
 }
 
 export function sanitizeSnapshotFile(filePath) {
   const dump = fs.readFileSync(filePath, "utf8");
-  const sanitized = dump
-    .split("\n")
+  const sanitized = sanitizeSnapshotText(dump);
+
+  if (sanitized !== dump) {
+    fs.writeFileSync(filePath, sanitized);
+  }
+}
+
+export function sanitizeSnapshotText(dump) {
+  return removePublicSchemaInitdbBlock(String(dump).split("\n"))
     .filter((line) => {
       const trimmed = line.trim();
       return (
+        !trimmed.startsWith("-- Dumped from database version ") &&
+        !trimmed.startsWith("-- Dumped by pg_dump version ") &&
         trimmed !== "SET transaction_timeout = 0;" &&
         !trimmed.startsWith("\\restrict ") &&
         !trimmed.startsWith("\\unrestrict ")
       );
     })
     .join("\n");
+}
 
-  if (sanitized !== dump) {
-    fs.writeFileSync(filePath, sanitized);
+function removePublicSchemaInitdbBlock(lines) {
+  const normalized = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index]?.trim() === "--" && lines[index + 1]?.startsWith("-- Name: public; Type: SCHEMA;")) {
+      let cursor = index + 1;
+      while (cursor < lines.length && !lines[cursor]?.includes("*not* creating schema")) {
+        cursor += 1;
+      }
+      if (cursor < lines.length) {
+        while (cursor + 1 < lines.length && lines[cursor + 1]?.trim() === "") {
+          cursor += 1;
+        }
+        index = cursor;
+        continue;
+      }
+    }
+    normalized.push(lines[index]);
   }
+  return normalized;
 }

package/lib/runner/orchestrator.mjs

@@ -146,9 +146,10 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
         runtimeOptions: {
           reporter,
           logRegistry,
-          setupRegistry,
-        },
-      });
+        setupRegistry,
+        skipSchemaSourceVerify: opts.skipSchemaSourceVerify,
+      },
+    });
       const timingUpdates = [];
 
       try {

package/lib/runner/template-steps.mjs

@@ -51,13 +51,16 @@ export async function runConfiguredSteps({
   reporter = null,
   setupRegistry = null,
   parentOperation = null,
+  startIndex = 0,
+  afterStep = null,
 }) {
   if (steps.length === 0) return;
   const resolvedToolchain = await resolveConfiguredToolchain(config);
   await announceResolvedToolchain(config, resolvedToolchain, reporter);
 
   for (const [index, step] of steps.entries()) {
-    const label = `${labelPrefix}:${config.name}:${index + 1}`;
+    const stepNumber = startIndex + index + 1;
+    const label = `${labelPrefix}:${config.name}:${stepNumber}`;
     const stepOperation = setupRegistry?.start({
       config,
       stage: label,
@@ -89,6 +92,14 @@ export async function runConfiguredSteps({
       if (finished) reporter?.setupOperationFinished?.(finished);
       throw error;
     }
+    if (afterStep) {
+      await afterStep({
+        step,
+        index: startIndex + index,
+        stepNumber,
+        label,
+      });
+    }
   }
 }
 

package/lib/runner/template.mjs

@@ -1,5 +1,8 @@
 import path from "path";
-import { finalizeConfiguredInputs, finalizeConfiguredSteps } from "../shared/configured-steps.mjs";
+import {
+  finalizeConfiguredInputs,
+  finalizeConfiguredSteps,
+} from "../shared/configured-steps.mjs";
 import { readDatabaseInfo } from "./state-io.mjs";
 
 const PORT_STRIDE = 100;
@@ -135,6 +138,7 @@ export function resolveRuntimeConfig(
   const database = config.testkit.database
     ? {
         ...config.testkit.database,
+        sourceSchema: finalizeSourceSchema(config.testkit.database.sourceSchema, context),
         template: finalizeDatabaseTemplate(config.testkit.database.template, context),
       }
     : undefined;
@@ -193,6 +197,17 @@ function finalizeDatabaseTemplate(template, context) {
   };
 }
 
+function finalizeSourceSchema(sourceSchema, context) {
+  if (!sourceSchema) return null;
+  return {
+    ...sourceSchema,
+    ...(typeof sourceSchema.env === "string" ? { env: finalizeString(sourceSchema.env, context) } : {}),
+    ...(typeof sourceSchema.cachePath === "string"
+      ? { cachePath: finalizeString(sourceSchema.cachePath, context) }
+      : {}),
+  };
+}
+
 export function resolveServiceStateDir(runtimeDir, config) {
   return path.join(runtimeDir, "services", config.name);
 }

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.115"
+    "@elench/testkit-protocol": "0.1.117"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -62,7 +62,10 @@
     "test": "npm run build:assistant && npm run build:packages && vitest run && npm run test:live",
     "test:audit": "node scripts/test-boundary-audit.mjs",
     "test:compat:node20": "volta run --node 20.19.5 --npm 10.8.2 npm test",
+    "test:database-version:compat": "node scripts/test-database-version-compat.mjs",
+    "test:engine-version:compat": "node scripts/test-engine-version-compat.mjs",
     "test:live": "node scripts/live-sandbox/harness.mjs",
+    "test:live:neon": "node scripts/test-database-version-compat.mjs --neon-only",
     "test:unit": "npm run build:assistant && npm run build:packages && npm run test:audit && vitest run --config vitest.unit.config.mjs",
     "test:integration": "npm run build:assistant && npm run build:packages && vitest run test/integration",
     "test:system": "npm run build:assistant && npm run build:packages && vitest run test/system"
@@ -91,10 +94,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.115",
-    "@elench/testkit-bridge": "0.1.115",
-    "@elench/testkit-protocol": "0.1.115",
-    "@elench/ts-analysis": "0.1.115",
+    "@elench/next-analysis": "0.1.117",
+    "@elench/testkit-bridge": "0.1.117",
+    "@elench/testkit-protocol": "0.1.117",
+    "@elench/ts-analysis": "0.1.117",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",

package/packages/testkit-bridge/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.114",
+  "version": "0.1.116",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/lib/cli/commands/db/snapshot/capture.mjs

@@ -1,26 +0,0 @@
-import { Command, Flags } from "@oclif/core";
-import { sharedFlags } from "../../../command-flags.mjs";
-import { executeDatabaseSnapshotCaptureOperation } from "../../../operations/db/snapshot/capture/operation.mjs";
-import { renderDatabaseSnapshotCaptureResult } from "../../../renderers/db-snapshot-capture/text.mjs";
-
-export default class DbSnapshotCaptureCommand extends Command {
-  static summary = "Capture a database schema snapshot";
-
-  static enableJsonFlag = true;
-
-  static flags = {
-    ...sharedFlags,
-    output: Flags.string({
-      description: "Output path for the snapshot",
-    }),
-  };
-
-  async run() {
-    const { flags } = await this.parse(DbSnapshotCaptureCommand);
-    const result = await executeDatabaseSnapshotCaptureOperation(flags);
-    if (!this.jsonEnabled()) {
-      for (const line of renderDatabaseSnapshotCaptureResult(result)) this.log(line);
-    }
-    return result;
-  }
-}

package/lib/cli/renderers/db-snapshot-capture/text.mjs

@@ -1,3 +0,0 @@
-export function renderDatabaseSnapshotCaptureResult(result) {
-  return [`Wrote ${result.outputLabel}`];
-}