@elench/testkit 0.1.116 → 0.1.117

package/README.md

@@ -346,6 +346,15 @@ is never written into the baseline. Keep schema-changing setup in its own step
 where possible; a single command that changes schema and then fails before
 exiting cannot be refreshed at the midpoint.
 
+Source schema refreshes are intentionally single-connection and pooler-safe.
+If a Neon pooled source URL is configured, Testkit rewrites it to the matching
+direct Neon endpoint before running `pg_dump` and records the original/resolved
+host classifications in `.testkit/db/<service>/source-schema.meta.json`. Unknown
+PgBouncer/pooler URLs fail closed; configure a direct source URL for those
+providers. Concurrent refreshes for the same service are serialized with a
+cache-local lock so multiple Testkit processes do not stampede the source
+database.
+
 For most repos, prefer declarative step objects directly inside
 `database.postgres({ template: ... })` and `runtime.prepare.steps`.
 The supported shapes are:

package/lib/cli/operations/db/schema/refresh/operation.mjs

@@ -48,6 +48,8 @@ export async function executeDatabaseSchemaRefreshOperation(options = {}) {
       outputPath,
       outputLabel: path.relative(productDir, outputPath) || path.basename(outputPath),
       envName: state.envName || null,
+      sourceUrl: state.refreshInfo?.metadata?.sourceUrl || null,
+      reusedExistingRefresh: Boolean(state.refreshInfo?.reusedExistingRefresh),
     };
   } finally {
     logRegistry.closeAll();

package/lib/cli/renderers/db-schema/text.mjs

@@ -1,5 +1,12 @@
 export function renderDatabaseSchemaRefreshResult(result) {
-  return [`Refreshed ${result.outputLabel}`];
+  const lines = [`Refreshed ${result.outputLabel}`];
+  if (result.sourceUrl?.rewritten && result.sourceUrl.originalClassification === "neon-pooler") {
+    lines.push("Source schema URL uses Neon pooler; Testkit used the direct endpoint for pg_dump.");
+  }
+  if (result.reusedExistingRefresh) {
+    lines.push("Another Testkit process refreshed this source schema cache first; reused that result.");
+  }
+  return lines;
 }
 
 export function renderDatabaseSchemaVerifyResult(result) {

package/lib/database/schema-source.mjs

@@ -5,6 +5,8 @@ import { execa } from "execa";
 import { resolveServiceCwd } from "../config/paths.mjs";
 import { buildExecutionEnv } from "../runner/template.mjs";
 import { dumpPostgresSchemaToFile, captureTemplateSnapshotText, runTemplateStep, sanitizeSnapshotText } from "./template-steps.mjs";
+import { getSourceSchemaRefreshLockPath, withSourceSchemaRefreshLock } from "./source-refresh-lock.mjs";
+import { resolveSourceSchemaDumpUrl } from "./source-url.mjs";
 
 const SOURCE_SCHEMA_DIR = path.join(".testkit", "db");
 const SOURCE_SCHEMA_FILE = "source-schema.sql";
@@ -57,8 +59,8 @@ export async function prepareSourceSchemaCache(config, options = {}) {
 
   if (state.sourceUrl) {
     if (shouldRefreshSourceSchema(state)) {
-      await refreshSourceSchemaCache(config, state, options);
-      return { ...state, refreshed: true, cacheExists: true };
+      const refreshInfo = await refreshSourceSchemaCache(config, state, options);
+      return { ...state, refreshed: true, cacheExists: true, refreshInfo };
     }
     options.setupRegistry?.recordCached({
       config,
@@ -93,8 +95,8 @@ export async function forceRefreshSourceSchemaCache(config, previousState, optio
     const envLabel = previousState?.envName || previousState?.sourceSchema?.env || "source schema env";
     throw new Error(`Cannot refresh source schema for service "${config.name}" because ${envLabel} is unavailable.`);
   }
-  await refreshSourceSchemaCache(config, state, options);
-  return { ...state, refreshed: true, cacheExists: true };
+  const refreshInfo = await refreshSourceSchemaCache(config, state, options);
+  return { ...state, refreshed: true, cacheExists: true, refreshInfo };
 }
 
 export async function applySourceSchemaCache(config, databaseUrl, state, options = {}) {
@@ -171,6 +173,7 @@ export function appendSourceSchemaCacheToHash(hash, config) {
 }
 
 async function refreshSourceSchemaCache(config, state, options = {}) {
+  let refreshInfo = null;
   const operation = options.setupRegistry?.start({
     config,
     stage: "source-schema:refresh",
@@ -178,16 +181,31 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
     summary: `source schema refresh: ${path.relative(config.productDir, state.cachePath)}`,
   });
   try {
-    await writeSourceSchemaCacheFromUrl(config, state.sourceUrl, state.cachePath, {
-      reporter: options.reporter || null,
-      logRecord: operation?._logRecord || null,
-    });
-    writeSourceSchemaMetadata(state.metadataPath, {
-      refreshedAt: new Date().toISOString(),
-      serviceName: config.name,
-      envName: state.envName,
-      cachePath: path.relative(config.productDir, state.cachePath),
-    });
+    refreshInfo = await withSourceSchemaRefreshLock(
+      getSourceSchemaRefreshLockPath(state.cachePath),
+      async ({ waited, requestedAt }) => {
+        const cachedAfterWaiting = readRecentSourceSchemaMetadata(state, requestedAt);
+        if (cachedAfterWaiting) {
+          return {
+            reusedExistingRefresh: true,
+            waitedForLock: waited,
+            metadata: cachedAfterWaiting,
+          };
+        }
+        const result = await writeSourceSchemaCacheFromUrl(config, state.sourceUrl, state.cachePath, {
+          reporter: options.reporter || null,
+          logRecord: operation?._logRecord || null,
+          env: options.env || process.env,
+        });
+        const metadata = buildSourceSchemaMetadata(config, state, result);
+        writeSourceSchemaMetadata(state.metadataPath, metadata);
+        return {
+          reusedExistingRefresh: false,
+          waitedForLock: waited,
+          metadata,
+        };
+      }
+    );
     const finished = operation
       ? options.setupRegistry.finish(operation, {
           status: "passed",
@@ -195,6 +213,7 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
         })
       : null;
     if (finished) options.reporter?.setupOperationFinished?.(finished);
+    return refreshInfo;
   } catch (error) {
     const finished = operation
       ? options.setupRegistry.finish(operation, {
@@ -209,17 +228,52 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
 }
 
 async function writeSourceSchemaCacheFromUrl(config, sourceUrl, cachePath, options = {}) {
+  const resolution = resolveSourceSchemaDumpUrl(sourceUrl);
   fs.mkdirSync(path.dirname(cachePath), { recursive: true });
   const tempDir = fs.mkdtempSync(path.join(path.dirname(cachePath), ".source-schema-"));
   const tempPath = path.join(tempDir, path.basename(cachePath));
   try {
-    await dumpPostgresSchemaToFile(config, tempPath, sourceUrl, options);
+    await dumpPostgresSchemaToFile(config, tempPath, resolution.dumpUrl, {
+      ...options,
+      pgApplicationName: sourceSchemaPgApplicationName(config.name),
+    });
     fs.renameSync(tempPath, cachePath);
+    return {
+      resolution,
+      pgDump: {
+        args: ["--schema-only", "--no-owner", "--no-privileges"],
+        applicationName: sourceSchemaPgApplicationName(config.name),
+      },
+    };
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 }
 
+function buildSourceSchemaMetadata(config, state, result) {
+  return {
+    refreshedAt: new Date().toISOString(),
+    serviceName: config.name,
+    envName: state.envName,
+    cachePath: path.relative(config.productDir, state.cachePath),
+    sourceUrl: result.resolution.metadata,
+    pgDump: result.pgDump,
+  };
+}
+
+function readRecentSourceSchemaMetadata(state, requestedAt) {
+  if (!fs.existsSync(state.cachePath)) return null;
+  const metadata = readJson(state.metadataPath);
+  const refreshedAt = metadata?.refreshedAt ? Date.parse(metadata.refreshedAt) : 0;
+  if (!Number.isFinite(refreshedAt) || refreshedAt < requestedAt) return null;
+  return metadata;
+}
+
+function sourceSchemaPgApplicationName(serviceName) {
+  const suffix = String(serviceName).replace(/[^a-zA-Z0-9._:-]+/g, "-").slice(0, 24) || "service";
+  return `testkit:schema-source:${suffix}`;
+}
+
 function readSourceSchemaCacheText(cachePath) {
   return sanitizeSnapshotText(fs.readFileSync(cachePath, "utf8"));
 }

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

@@ -8,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] || [];
@@ -69,14 +70,18 @@ export async function captureTemplateSnapshotText(config, databaseUrl, options =
 
 export async function dumpPostgresSchemaToFile(config, outputPath, databaseUrl, options = {}) {
   const env = {
-    ...buildTemplateExecutionEnv(config, {}, process.env),
-    ...buildPostgresConnectionEnv(databaseUrl),
+    ...buildTemplateExecutionEnv(config, {}, options.env || process.env),
+    ...buildPostgresConnectionEnv(databaseUrl, {
+      applicationName: options.pgApplicationName,
+    }),
   };
-  const result = await runPgDumpCommand(config, "pg_dump", pgDumpArgs(), env, options);
+  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, options);
+      const fallback = await runDockerizedPgDump(config, serverMajor, env, args, options);
       if (fallback.exitCode === 0) {
         fs.writeFileSync(outputPath, fallback.stdout);
         sanitizeSnapshotFile(outputPath);
@@ -92,7 +97,7 @@ export async function dumpPostgresSchemaToFile(config, outputPath, databaseUrl,
   sanitizeSnapshotFile(outputPath);
 }
 
-function pgDumpArgs() {
+export function pgDumpArgs() {
   return [
     "--schema-only",
     "--no-owner",
@@ -100,7 +105,7 @@ function pgDumpArgs() {
   ];
 }
 
-async function runDockerizedPgDump(config, serverMajor, env, options) {
+async function runDockerizedPgDump(config, serverMajor, env, pgDumpCommandArgs, options) {
   const image = `${process.env.TESTKIT_PG_DUMP_IMAGE_PREFIX || "postgres"}:${serverMajor}`;
   return runPgDumpCommand(
     config,
@@ -122,9 +127,11 @@ async function runDockerizedPgDump(config, serverMajor, env, options) {
       "PGPASSWORD",
       "-e",
       "PGSSLMODE",
+      "-e",
+      "PGAPPNAME",
       image,
       "pg_dump",
-      ...pgDumpArgs(),
+      ...pgDumpCommandArgs,
     ],
     env,
     options
@@ -169,7 +176,7 @@ function parsePgDumpServerMajor(result) {
   return match ? Number(match[1]) : null;
 }
 
-function buildPostgresConnectionEnv(databaseUrl) {
+function buildPostgresConnectionEnv(databaseUrl, options = {}) {
   const parsed = new URL(databaseUrl);
   return compactObject({
     PGHOST: parsed.hostname,
@@ -178,6 +185,7 @@ function buildPostgresConnectionEnv(databaseUrl) {
     PGUSER: decodeURIComponent(parsed.username || ""),
     PGPASSWORD: decodeURIComponent(parsed.password || ""),
     PGSSLMODE: parsed.searchParams.get("sslmode") || undefined,
+    PGAPPNAME: options.applicationName || undefined,
   });
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.116",
+  "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.116",
+  "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.116"
+    "@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.116",
+  "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.116",
+  "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.116",
+  "version": "0.1.117",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -94,10 +94,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.116",
-    "@elench/testkit-bridge": "0.1.116",
-    "@elench/testkit-protocol": "0.1.116",
-    "@elench/ts-analysis": "0.1.116",
+    "@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.115",
+  "version": "0.1.116",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",