@elench/testkit 0.1.116 → 0.1.118

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/lib/repo/state.mjs

@@ -0,0 +1,164 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import { parseGitHubRepoSlug } from "../regressions/github.mjs";
+
+const IGNORED_DIRS = new Set([".git", ".testkit", "node_modules"]);
+
+export function collectRepoState(productDir) {
+  const repoRoot = readGit(productDir, ["rev-parse", "--show-toplevel"]);
+  if (!repoRoot) {
+    const fingerprint = fingerprintDirectory(productDir);
+    return {
+      kind: "nogit",
+      repoRoot: null,
+      worktreePath: path.resolve(productDir),
+      branch: null,
+      detached: false,
+      commitSha: null,
+      remoteUrl: null,
+      repoSlug: null,
+      dirty: false,
+      dirtyFingerprint: null,
+      contentFingerprint: fingerprint,
+      cacheKey: `nogit/${fingerprint}`,
+    };
+  }
+
+  const commitSha = readGit(productDir, ["rev-parse", "--verify", "HEAD"]);
+  const branchName = readGit(productDir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const remoteUrl = readGit(productDir, ["remote", "get-url", "origin"]);
+  const detached = branchName === "HEAD";
+  const dirtyFingerprint = fingerprintGitDirtyState(productDir);
+  const dirty = Boolean(dirtyFingerprint);
+  const baseCommit = commitSha || "unborn";
+
+  return {
+    kind: dirty ? "dirty" : "commit",
+    repoRoot,
+    worktreePath: path.resolve(repoRoot),
+    branch: detached ? null : branchName,
+    detached,
+    commitSha,
+    remoteUrl,
+    repoSlug: parseGitHubRepoSlug(remoteUrl),
+    dirty,
+    dirtyFingerprint,
+    contentFingerprint: null,
+    cacheKey: dirty
+      ? `dirty/${baseCommit}-${dirtyFingerprint}`
+      : `commits/${baseCommit}`,
+  };
+}
+
+export function summarizeRepoStateForMetadata(repoState) {
+  if (!repoState) return null;
+  return {
+    kind: repoState.kind,
+    cacheKey: repoState.cacheKey,
+    branch: repoState.branch,
+    detached: repoState.detached,
+    commitSha: repoState.commitSha,
+    dirty: repoState.dirty,
+    dirtyFingerprint: repoState.dirtyFingerprint,
+    contentFingerprint: repoState.contentFingerprint,
+    repoRoot: repoState.repoRoot,
+    worktreePath: repoState.worktreePath,
+    remoteUrl: repoState.remoteUrl,
+    repoSlug: repoState.repoSlug,
+  };
+}
+
+function fingerprintGitDirtyState(productDir) {
+  const hash = crypto.createHash("sha256");
+  let hasChanges = false;
+
+  const trackedStatus = readGit(productDir, ["status", "--porcelain=v1", "-uno"]) || "";
+  if (trackedStatus.trim()) {
+    hasChanges = true;
+    hash.update("tracked-status\0");
+    hash.update(trackedStatus);
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--no-ext-diff"]);
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--cached", "--no-ext-diff"]);
+  }
+
+  const untracked = readGit(productDir, ["ls-files", "--others", "--exclude-standard", "-z"]) || "";
+  const untrackedFiles = untracked
+    .split("\0")
+    .filter(Boolean)
+    .filter((entry) => !hasIgnoredPathSegment(entry))
+    .sort();
+  if (untrackedFiles.length > 0) {
+    hasChanges = true;
+    hash.update("untracked\0");
+    for (const relativePath of untrackedFiles) {
+      const absPath = path.join(productDir, relativePath);
+      if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) continue;
+      hash.update(`file:${normalizePath(relativePath)}\0`);
+      const stat = fs.statSync(absPath);
+      hash.update(`${stat.size}\0`);
+      hash.update(fs.readFileSync(absPath));
+    }
+  }
+
+  return hasChanges ? hash.digest("hex").slice(0, 24) : null;
+}
+
+function appendGitOutput(hash, cwd, args) {
+  const output = readGit(cwd, args) || "";
+  hash.update(args.join(" "));
+  hash.update("\0");
+  hash.update(output);
+  hash.update("\0");
+}
+
+function fingerprintDirectory(rootDir) {
+  const hash = crypto.createHash("sha256");
+  appendDirectoryToHash(hash, rootDir, rootDir);
+  return hash.digest("hex").slice(0, 24);
+}
+
+function appendDirectoryToHash(hash, rootDir, absPath) {
+  if (!fs.existsSync(absPath)) {
+    hash.update(`missing:${normalizePath(path.relative(rootDir, absPath))}`);
+    return;
+  }
+  const stat = fs.statSync(absPath);
+  if (stat.isDirectory()) {
+    const relative = path.relative(rootDir, absPath);
+    if (relative && hasIgnoredPathSegment(relative)) return;
+    hash.update(`dir:${normalizePath(relative)}`);
+    for (const entry of fs.readdirSync(absPath).sort()) {
+      if (IGNORED_DIRS.has(entry)) continue;
+      appendDirectoryToHash(hash, rootDir, path.join(absPath, entry));
+    }
+    return;
+  }
+  if (!stat.isFile()) return;
+  const relative = normalizePath(path.relative(rootDir, absPath));
+  hash.update(`file:${relative}:${stat.size}:${stat.mtimeMs}`);
+  hash.update(fs.readFileSync(absPath));
+}
+
+function hasIgnoredPathSegment(relativePath) {
+  return normalizePath(relativePath)
+    .split("/")
+    .some((segment) => IGNORED_DIRS.has(segment));
+}
+
+function normalizePath(value) {
+  return String(value).split(path.sep).join("/");
+}
+
+function readGit(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}

package/lib/runner/metadata.mjs

@@ -1,27 +1,22 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
-import { parseGitHubRepoSlug } from "../regressions/github.mjs";
+import { collectRepoState } from "../repo/state.mjs";
 
 export function collectGitMetadata(productDir) {
-  const read = (args) => {
-    try {
-      return execaSyncCompat("git", args, { cwd: productDir }).trim() || null;
-    } catch {
-      return null;
-    }
-  };
-
-  const remoteUrl = read(["remote", "get-url", "origin"]);
+  const state = collectRepoState(productDir);
 
   return {
-    branch: read(["rev-parse", "--abbrev-ref", "HEAD"]),
-    commitSha: read(["rev-parse", "HEAD"]),
-    repoRoot: read(["rev-parse", "--show-toplevel"]),
-    remoteUrl,
-    repoSlug: parseGitHubRepoSlug(remoteUrl),
+    branch: state.branch || (state.detached ? "HEAD" : null),
+    commitSha: state.commitSha,
+    repoRoot: state.repoRoot,
+    remoteUrl: state.remoteUrl,
+    repoSlug: state.repoSlug,
+    detached: state.detached,
+    dirty: state.dirty,
+    dirtyFingerprint: state.dirtyFingerprint,
+    worktreePath: state.worktreePath,
   };
 }
 
@@ -50,11 +45,3 @@ export function safeUsername() {
     return process.env.USER || process.env.USERNAME || null;
   }
 }
-
-function execaSyncCompat(command, args, options) {
-  return execFileSync(command, args, {
-    cwd: options?.cwd,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-}

package/lib/runner/template.mjs

@@ -202,9 +202,6 @@ function finalizeSourceSchema(sourceSchema, context) {
   return {
     ...sourceSchema,
     ...(typeof sourceSchema.env === "string" ? { env: finalizeString(sourceSchema.env, context) } : {}),
-    ...(typeof sourceSchema.cachePath === "string"
-      ? { cachePath: finalizeString(sourceSchema.cachePath, context) }
-      : {}),
   };
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.116",
+  "version": "0.1.118",
   "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.118",
   "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.118"
   },
   "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.118",
   "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.118",
   "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.118",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -65,6 +65,7 @@
     "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:github": "node scripts/test-live-github-fixture.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",
@@ -94,10 +95,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.118",
+    "@elench/testkit-bridge": "0.1.118",
+    "@elench/testkit-protocol": "0.1.118",
+    "@elench/ts-analysis": "0.1.118",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",