@elench/testkit 0.1.134 → 0.1.136

package/lib/database/fingerprint.mjs

@@ -1,7 +1,9 @@
 import crypto from "crypto";
-import fs from "fs";
-import path from "path";
 import { resolveServiceCwd } from "../config/paths.mjs";
+import {
+  appendFingerprintPathToHash,
+  normalizeFingerprintPolicy,
+} from "../repo/fingerprint-policy.mjs";
 import { collectTemplateInputs } from "./template-steps.mjs";
 import { appendSourceSchemaCacheToHash } from "./schema-source.mjs";
 
@@ -11,6 +13,7 @@ const LOCAL_USER = "testkit";
 export async function computeTemplateFingerprint(config, options = {}) {
   const hash = crypto.createHash("sha256");
   const db = config.testkit.database;
+  const fingerprints = normalizeFingerprintPolicy(config.testkit.fingerprints);
   hash.update(JSON.stringify({
     provider: db.provider,
     selectedBackend: db.selectedBackend,
@@ -20,48 +23,25 @@ export async function computeTemplateFingerprint(config, options = {}) {
   }));
 
   for (const envFile of config.testkit.envFiles || []) {
-    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
+    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile), fingerprints);
   }
   for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
-    appendResolvedInputToHash(hash, config.productDir, input);
+    appendResolvedInputToHash(hash, config.productDir, input, fingerprints);
   }
   appendSourceSchemaCacheToHash(hash, config, options.sourceSchemaState || null);
 
   return hash.digest("hex");
 }
 
-export function appendInputToHash(hash, productDir, input) {
+export function appendInputToHash(hash, productDir, input, fingerprints = {}) {
   const absPath = resolveServiceCwd(productDir, input);
-  appendResolvedInputToHash(hash, productDir, absPath);
+  appendResolvedInputToHash(hash, productDir, absPath, normalizeFingerprintPolicy(fingerprints));
 }
 
-function appendResolvedInputToHash(hash, productDir, absPath) {
-  if (!fs.existsSync(absPath)) {
-    hash.update(`missing:${path.relative(productDir, absPath)}`);
-    return;
-  }
-
-  const stat = fs.statSync(absPath);
-  if (stat.isDirectory()) {
-    hash.update(`dir:${path.relative(productDir, absPath)}`);
-    for (const entry of fs.readdirSync(absPath).sort()) {
-      if (entry === ".git" || entry === "node_modules" || entry === ".testkit") continue;
-      appendResolvedInputToHash(hash, productDir, path.join(absPath, entry));
-    }
-    return;
-  }
-
-  appendFileToHash(hash, productDir, absPath);
+function appendResolvedInputToHash(hash, productDir, absPath, fingerprints) {
+  appendFingerprintPathToHash(hash, productDir, absPath, fingerprints);
 }
 
-export function appendFileToHash(hash, productDir, absPath) {
-  if (!fs.existsSync(absPath)) {
-    hash.update(`missing:${path.relative(productDir, absPath)}`);
-    return;
-  }
-  const stat = fs.statSync(absPath);
-  if (!stat.isFile()) return;
-
-  hash.update(`file:${path.relative(productDir, absPath)}:${stat.size}:${stat.mtimeMs}`);
-  hash.update(fs.readFileSync(absPath));
+export function appendFileToHash(hash, productDir, absPath, fingerprints = {}) {
+  appendFingerprintPathToHash(hash, productDir, absPath, normalizeFingerprintPolicy(fingerprints));
 }

package/lib/database/index.mjs

@@ -2,8 +2,6 @@ import fs from "fs";
 import path from "path";
 import { execa } from "execa";
 import {
-  appendFileToHash as appendFileToHashModel,
-  appendInputToHash as appendInputToHashModel,
   computeTemplateFingerprint as computeTemplateFingerprintModel,
 } from "./fingerprint.mjs";
 import {
@@ -44,6 +42,8 @@ const LOCAL_PASSWORD = "testkit";
 const LOCAL_ADMIN_DB = "postgres";
 const LOCAL_READY_TIMEOUT_MS = 60_000;
 const LOCAL_POLL_INTERVAL_MS = 1_000;
+const LOCAL_ADMIN_QUERY_RETRY_MS = 15_000;
+const LOCAL_ADMIN_QUERY_RETRY_INTERVAL_MS = 250;
 const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
 const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
@@ -603,8 +603,31 @@ async function runAdminQuery(infra, args) {
     LOCAL_ADMIN_DB,
     ...args,
   ];
-  const { stdout } = await execa("docker", commandArgs);
-  return stdout;
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      const { stdout } = await execa("docker", commandArgs);
+      return stdout;
+    } catch (error) {
+      if (
+        Date.now() - startedAt >= LOCAL_ADMIN_QUERY_RETRY_MS ||
+        !isTransientAdminQueryConnectionError(error)
+      ) {
+        throw error;
+      }
+      await sleep(LOCAL_ADMIN_QUERY_RETRY_INTERVAL_MS);
+    }
+  }
+}
+
+export function isTransientAdminQueryConnectionError(error) {
+  const text = `${error?.shortMessage || ""}\n${error?.stderr || ""}\n${error?.stdout || ""}\n${error?.message || ""}`;
+  return (
+    text.includes('connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed') ||
+    text.includes("No such file or directory") ||
+    text.includes("the database system is starting up") ||
+    text.includes("could not connect to server")
+  );
 }
 
 async function terminateDatabaseConnections(infra, dbName, runAdminQueryFn) {
@@ -642,14 +665,6 @@ async function computeTemplateFingerprint(config, options = {}) {
   return computeTemplateFingerprintModel(config, options);
 }
 
-function appendInputToHash(hash, productDir, input) {
-  return appendInputToHashModel(hash, productDir, input);
-}
-
-function appendFileToHash(hash, productDir, absPath) {
-  return appendFileToHashModel(hash, productDir, absPath);
-}
-
 function buildDatabaseUrl(infra, dbName) {
   return buildDatabaseUrlModel(infra, dbName);
 }

package/lib/database/schema-source.mjs

@@ -29,7 +29,9 @@ export function getSourceSchemaMetadataPath(config, options = {}) {
 }
 
 export function resolveSourceSchemaCacheLocation(config, options = {}) {
-  const repoState = options.repoState || collectRepoState(config.productDir);
+  const repoState = options.repoState || collectRepoState(config.productDir, {
+    fingerprints: config.testkit?.fingerprints,
+  });
   const rootDir = getSourceSchemaRootDir(config);
   const cacheDir = path.join(rootDir, ...repoState.cacheKey.split("/").map(sanitizePathSegment));
   return {
@@ -166,6 +168,7 @@ export async function verifyLocalSchemaMatchesSource(config, databaseUrl, state,
     return { status: "skipped" };
   }
 
+  clearSchemaMismatchDiagnosticsForService(config);
   const sourceSchema = readSourceSchemaCacheText(state.cachePath);
   const localSchema = await captureTemplateSnapshotText(config, databaseUrl, {
     reporter: options.reporter || null,
@@ -174,7 +177,7 @@ export async function verifyLocalSchemaMatchesSource(config, databaseUrl, state,
     return { status: "matched" };
   }
 
-  const diagnostics = await writeSchemaMismatchDiagnostics(config, state.cachePath, sourceSchema, localSchema);
+  const diagnostics = await writeSchemaMismatchDiagnostics(config, state, sourceSchema, localSchema);
   return {
     status: "mismatch",
     diagnostics,
@@ -396,21 +399,73 @@ function readJson(filePath) {
   }
 }
 
-async function writeSchemaMismatchDiagnostics(config, sourceCachePath, sourceSchema, localSchema) {
-  const dir = path.join(config.productDir, ".testkit", "results", "schema");
+function schemaMismatchDiagnosticsDir(config) {
+  return path.join(config.productDir, ".testkit", "results", "schema");
+}
+
+function schemaMismatchDiagnosticsPrefix(config) {
+  return `${sanitizePathSegment(config.runtimeLabel || config.name)}__${sanitizePathSegment(config.name)}`;
+}
+
+function clearSchemaMismatchDiagnosticsForService(config) {
+  const dir = schemaMismatchDiagnosticsDir(config);
+  if (!fs.existsSync(dir)) return;
+  const serviceSegment = sanitizePathSegment(config.name);
+  for (const entry of fs.readdirSync(dir)) {
+    if (!isSchemaMismatchDiagnosticForService(entry, serviceSegment)) continue;
+    fs.rmSync(path.join(dir, entry), { force: true });
+  }
+}
+
+function isSchemaMismatchDiagnosticForService(entry, serviceSegment) {
+  for (const suffix of [
+    "__source-schema.sql",
+    "__local-replay-schema.sql",
+    "__schema.diff",
+    "__schema.meta.json",
+  ]) {
+    if (!entry.endsWith(suffix)) continue;
+    return entry.slice(0, -suffix.length).endsWith(`__${serviceSegment}`);
+  }
+  return false;
+}
+
+async function writeSchemaMismatchDiagnostics(config, state, sourceSchema, localSchema) {
+  const dir = schemaMismatchDiagnosticsDir(config);
   fs.mkdirSync(dir, { recursive: true });
-  const prefix = `${sanitizePathSegment(config.runtimeLabel || config.name)}__${sanitizePathSegment(config.name)}`;
+  const prefix = schemaMismatchDiagnosticsPrefix(config);
   const sourcePath = path.join(dir, `${prefix}__source-schema.sql`);
   const localPath = path.join(dir, `${prefix}__local-replay-schema.sql`);
   const diffPath = path.join(dir, `${prefix}__schema.diff`);
+  const metaPath = path.join(dir, `${prefix}__schema.meta.json`);
   fs.writeFileSync(sourcePath, sourceSchema);
   fs.writeFileSync(localPath, localSchema);
   fs.writeFileSync(diffPath, await buildUnifiedDiff(sourcePath, localPath));
+  writeJson(metaPath, buildSchemaMismatchMetadata(config, state));
   return {
-    sourceCachePath,
+    sourceCachePath: state.cachePath,
     sourcePath,
     localPath,
     diffPath,
+    metaPath,
+  };
+}
+
+function buildSchemaMismatchMetadata(config, state) {
+  const sourceMetadata = readJson(state.metadataPath) || {};
+  return {
+    version: 1,
+    createdAt: new Date().toISOString(),
+    serviceName: config.name,
+    runtimeLabel: config.runtimeLabel || config.name,
+    sourceSchema: {
+      envName: state.envName || null,
+      cacheKey: state.cacheKey || null,
+      cacheKind: state.cacheKind || null,
+      cachePath: path.relative(config.productDir, state.cachePath),
+      refreshedAt: sourceMetadata.refreshedAt || null,
+    },
+    repo: state.repoState ? summarizeRepoStateForMetadata(state.repoState) : null,
   };
 }
 

package/lib/env/index.d.ts

@@ -30,6 +30,7 @@ export interface PostgresConnectionEnvValue {
 }
 
 export declare function isManagedRuntime(env?: NodeJS.ProcessEnv): boolean;
+export declare function managedRuntimeMode(env?: NodeJS.ProcessEnv): "test" | "local" | string | null;
 export declare function shouldLoadDotenv(env?: NodeJS.ProcessEnv): boolean;
 export declare function loadDotenvFiles(options?: LoadDotenvFilesOptions): {
   loaded: string[];

package/lib/env/index.mjs

@@ -9,6 +9,10 @@ export function isManagedRuntime(env = process.env) {
   return env?.TESTKIT_ACTIVE === "1";
 }
 
+export function managedRuntimeMode(env = process.env) {
+  return isManagedRuntime(env) ? env?.TESTKIT_MODE || "test" : null;
+}
+
 export function shouldLoadDotenv(env = process.env) {
   return env?.NODE_ENV !== "production" && !isManagedRuntime(env);
 }
@@ -59,7 +63,7 @@ export function assertLocalDatabaseUrl(env = process.env, consumer = "This comma
   if (!LOCAL_DATABASE_PROTOCOLS.has(parsed.protocol) || !LOCAL_DATABASE_HOSTS.has(parsed.hostname)) {
     const location = `${parsed.protocol}//${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}`;
     throw new Error(
-      `${consumer} testkit runs require a local PostgreSQL DATABASE_URL. Refusing ${location}.`
+      `${consumer} managed Testkit runtime requires a local PostgreSQL DATABASE_URL. Refusing ${location}.`
     );
   }
 }

package/lib/local/lifecycle.mjs

@@ -0,0 +1,287 @@
+import fs from "fs";
+import path from "path";
+import { destroyRuntimeDatabase, cleanupOrphanedLocalInfrastructure } from "../database/index.mjs";
+import { killProcessTree } from "../runner/processes.mjs";
+import { isPidRunning } from "../runner/lifecycle.mjs";
+
+const SCHEMA_VERSION = 1;
+const ENVIRONMENTS_DIRNAME = path.join(".testkit", "environments");
+const TERMINATION_TIMEOUT_MS = 5_000;
+
+export function getEnvironmentDir(productDir, name) {
+  return path.join(productDir, ENVIRONMENTS_DIRNAME, name);
+}
+
+export function createLocalEnvironmentLifecycle(productDir, name, options = {}) {
+  const environmentDir = getEnvironmentDir(productDir, name);
+  const manifestPath = path.join(environmentDir, "manifest.json");
+  const abortController = new AbortController();
+  const state = {
+    schemaVersion: SCHEMA_VERSION,
+    kind: "local",
+    name,
+    productDir,
+    pid: process.pid,
+    status: "starting",
+    startedAt: new Date().toISOString(),
+    target: options.target || null,
+    runtimeDir: options.runtimeDir || null,
+    runtimeStateDirs: [],
+    portOffset: options.portOffset || 0,
+    data: options.data || "reuse",
+    services: [],
+  };
+  const managedProcesses = new Set();
+
+  function persist() {
+    fs.mkdirSync(environmentDir, { recursive: true });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(state, null, 2)}\n`);
+  }
+
+  function mutate(mutator) {
+    mutator(state);
+    persist();
+  }
+
+  const api = {
+    name,
+    environmentDir,
+    manifestPath,
+    signal: abortController.signal,
+    isStopRequested() {
+      return abortController.signal.aborted;
+    },
+    markRunning(extra = {}) {
+      mutate((draft) => {
+        draft.status = "running";
+        Object.assign(draft, extra);
+      });
+    },
+    requestStop(reason = "stopped") {
+      if (!abortController.signal.aborted) {
+        abortController.abort(new Error(`testkit local environment stopped (${reason})`));
+      }
+      for (const entry of managedProcesses) {
+        try {
+          entry.terminate?.();
+        } catch {
+          // Best-effort stop only.
+        }
+      }
+      mutate((draft) => {
+        draft.status = "stopping";
+        draft.stopReason = reason;
+      });
+    },
+    registerProcess(child, terminate) {
+      if (!child) return;
+      managedProcesses.add({ child, terminate });
+    },
+    unregisterProcess(childPid) {
+      for (const entry of managedProcesses) {
+        if (entry.child?.pid === childPid) managedProcesses.delete(entry);
+      }
+    },
+    registerService(config, child, cwd, terminate) {
+      api.registerProcess(child, terminate);
+      mutate((draft) => {
+        draft.services = draft.services.filter((service) => service.pid !== child.pid);
+        draft.services.push({
+          serviceName: config.name,
+          runtimeLabel: config.runtimeLabel,
+          command: config.testkit.local?.start || null,
+          cwd,
+          pid: child.pid,
+          processGroupId: child.pid,
+          baseUrl: config.testkit.local?.baseUrl || null,
+          readyUrl: config.testkit.local?.readyUrl || null,
+          ports: collectConfigPorts(config),
+          startedAt: new Date().toISOString(),
+        });
+        for (const runtimeConfig of config.testkit?.templateContext?.stateDirByService?.values?.() || []) {
+          pushUnique(draft.runtimeStateDirs, runtimeConfig);
+        }
+      });
+    },
+    unregisterService(childPid) {
+      api.unregisterProcess(childPid);
+      mutate((draft) => {
+        draft.services = draft.services.filter((service) => service.pid !== childPid);
+      });
+    },
+    setRuntimeState(runtimeConfigs) {
+      mutate((draft) => {
+        draft.runtimeStateDirs = [...new Set(runtimeConfigs.map((config) => config.stateDir).filter(Boolean))];
+      });
+    },
+    removeManifest() {
+      fs.rmSync(manifestPath, { force: true });
+      pruneEmptyDir(environmentDir);
+      pruneEmptyDir(path.dirname(environmentDir));
+    },
+    persist,
+  };
+
+  api.persist();
+  return api;
+}
+
+export function readLocalEnvironmentManifest(productDir, name) {
+  return readManifest(path.join(getEnvironmentDir(productDir, name), "manifest.json"));
+}
+
+export function listLocalEnvironmentManifests(productDir) {
+  const root = path.join(productDir, ENVIRONMENTS_DIRNAME);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => readManifest(path.join(root, entry.name, "manifest.json")))
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export async function stopLocalEnvironment(productDir, name, options = {}) {
+  const manifest = readLocalEnvironmentManifest(productDir, name);
+  if (!manifest) return null;
+  for (const service of [...(manifest.services || [])].reverse()) {
+    await terminateOwnedProcess(service);
+  }
+  if (options.removeRuntimeState) {
+    for (const stateDir of [...new Set(manifest.runtimeStateDirs || [])].sort((a, b) => b.length - a.length)) {
+      await destroyRuntimeDatabase({ productDir, stateDir });
+    }
+    if (manifest.runtimeDir) fs.rmSync(manifest.runtimeDir, { recursive: true, force: true });
+    const environmentDir = getEnvironmentDir(productDir, name);
+    fs.rmSync(environmentDir, { recursive: true, force: true });
+    pruneEmptyDir(path.dirname(environmentDir));
+    await cleanupOrphanedLocalInfrastructure(productDir);
+    return manifest;
+  }
+  const environmentDir = getEnvironmentDir(productDir, name);
+  fs.mkdirSync(environmentDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(environmentDir, "manifest.json"),
+    `${JSON.stringify({
+      ...manifest,
+      status: "stopped",
+      stoppedAt: new Date().toISOString(),
+      services: [],
+    }, null, 2)}\n`
+  );
+  await cleanupOrphanedLocalInfrastructure(productDir);
+  return manifest;
+}
+
+export async function cleanupStaleLocalEnvironments(productDir) {
+  const cleaned = [];
+  for (const manifest of listLocalEnvironmentManifests(productDir)) {
+    if (isLocalEnvironmentActive(manifest)) continue;
+    await stopLocalEnvironment(productDir, manifest.name, { removeRuntimeState: false });
+    cleaned.push(manifest);
+  }
+  return cleaned;
+}
+
+export function findLocalPortOwner(productDir, { host, port }) {
+  for (const manifest of listLocalEnvironmentManifests(productDir)) {
+    for (const service of manifest.services || []) {
+      for (const socket of service.ports || []) {
+        if (normalizeHost(socket.host) === normalizeHost(host) && Number(socket.port) === Number(port)) {
+          return {
+            manifest,
+            service,
+            active: isLocalServiceActive(service),
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+export function isLocalEnvironmentActive(manifest) {
+  return (manifest.services || []).some(isLocalServiceActive);
+}
+
+export function formatLocalEnvironmentSummary(manifest) {
+  const ports = [
+    ...new Set(
+      (manifest.services || []).flatMap((service) =>
+        (service.ports || []).map((socket) => `${socket.host}:${socket.port}`)
+      )
+    ),
+  ];
+  return `${manifest.name}${ports.length > 0 ? ` ports=${ports.join(",")}` : ""}`;
+}
+
+function isLocalServiceActive(service) {
+  return isPidRunning(Number(service.processGroupId || service.pid));
+}
+
+async function terminateOwnedProcess(service) {
+  const pid = Number(service.processGroupId || service.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (!isPidRunning(pid)) return;
+  killProcessTree(pid, "SIGTERM");
+  const exited = await waitForPidExit(pid, TERMINATION_TIMEOUT_MS);
+  if (!exited) {
+    killProcessTree(pid, "SIGKILL");
+    await waitForPidExit(pid, TERMINATION_TIMEOUT_MS);
+  }
+}
+
+async function waitForPidExit(pid, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isPidRunning(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isPidRunning(pid);
+}
+
+function readManifest(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return parsed?.kind === "local" && parsed?.name ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function collectConfigPorts(config) {
+  const seen = new Set();
+  const ports = [];
+  for (const rawUrl of [config.testkit.local?.baseUrl, config.testkit.local?.readyUrl]) {
+    if (!rawUrl) continue;
+    try {
+      const parsed = new URL(rawUrl);
+      const host = normalizeHost(parsed.hostname);
+      const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+      const key = `${host}:${port}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      ports.push({ host, port });
+    } catch {
+      // Startup validation handles malformed URLs.
+    }
+  }
+  return ports;
+}
+
+function normalizeHost(host) {
+  if (!host || host === "localhost" || host === "::1") return "127.0.0.1";
+  return host;
+}
+
+function pushUnique(list, value) {
+  if (value && !list.includes(value)) list.push(value);
+}
+
+function pruneEmptyDir(dir) {
+  if (!dir || !fs.existsSync(dir)) return;
+  try {
+    if (fs.readdirSync(dir).length === 0) fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup only.
+  }
+}