@elench/testkit 0.1.145 → 0.1.146

package/lib/database/local-postgres.mjs

@@ -0,0 +1,158 @@
+import fs from "fs";
+import path from "path";
+import { execa } from "execa";
+import {
+  LOCAL_ADMIN_DB,
+  LOCAL_IMAGE,
+  LOCAL_PASSWORD,
+  LOCAL_POLL_INTERVAL_MS,
+  LOCAL_READY_TIMEOUT_MS,
+  LOCAL_USER,
+} from "./constants.mjs";
+import { buildContainerName } from "./naming.mjs";
+import { getLocalInfraDir, readStateValue } from "./state.mjs";
+import { buildDockerResourceLabels, dockerLabelArgs } from "../ownership/docker.mjs";
+import { writeLocalInfraState } from "./state-files.mjs";
+
+export async function ensureLocalContainer(productDir, database = {}) {
+  const infraDir = getLocalInfraDir(productDir);
+  fs.mkdirSync(infraDir, { recursive: true });
+
+  const containerName =
+    readStateValue(path.join(infraDir, "container_name")) || buildContainerName(productDir);
+  const image = database.image || readStateValue(path.join(infraDir, "image")) || LOCAL_IMAGE;
+  const user = database.user || readStateValue(path.join(infraDir, "user")) || LOCAL_USER;
+  const password =
+    database.password || readStateValue(path.join(infraDir, "password")) || LOCAL_PASSWORD;
+
+  let inspect = await inspectContainer(containerName);
+  if (inspect && inspect.Config?.Image !== image) {
+    await stopAndRemoveContainer(containerName);
+    inspect = null;
+  }
+
+  if (!inspect) {
+    const labels = buildLocalPostgresContainerLabels(productDir, containerName);
+    await execa("docker", [
+      "run",
+      "-d",
+      "--name",
+      containerName,
+      ...dockerLabelArgs(labels),
+      "-e",
+      `POSTGRES_USER=${user}`,
+      "-e",
+      `POSTGRES_PASSWORD=${password}`,
+      "-e",
+      `POSTGRES_DB=${LOCAL_ADMIN_DB}`,
+      "-p",
+      "127.0.0.1::5432",
+      image,
+    ]);
+    inspect = await inspectContainer(containerName);
+  } else if (!inspect.State?.Running) {
+    await execa("docker", ["start", containerName]);
+    inspect = await inspectContainer(containerName);
+  }
+
+  const hostPort = inspect?.NetworkSettings?.Ports?.["5432/tcp"]?.[0]?.HostPort;
+  if (!hostPort) {
+    throw new Error(`Could not determine published port for local database container ${containerName}`);
+  }
+
+  const infra = {
+    containerName,
+    containerId: inspect.Id,
+    image,
+    user,
+    password,
+    host: "127.0.0.1",
+    port: Number(hostPort),
+  };
+
+  await waitForLocalContainerReady(infra);
+  writeLocalInfraState(infraDir, infra);
+  return infra;
+}
+
+export async function loadExistingLocalContainer(productDir) {
+  const infraDir = getLocalInfraDir(productDir);
+  const containerName = readStateValue(path.join(infraDir, "container_name"));
+  if (!containerName) return null;
+
+  const inspect = await inspectContainer(containerName);
+  if (!inspect) return null;
+
+  if (!inspect.State?.Running) {
+    await execa("docker", ["start", containerName]);
+  }
+
+  const nextInspect = await inspectContainer(containerName);
+  const hostPort = nextInspect?.NetworkSettings?.Ports?.["5432/tcp"]?.[0]?.HostPort;
+  if (!hostPort) return null;
+
+  const infra = {
+    containerName,
+    containerId: nextInspect.Id,
+    image: nextInspect.Config?.Image || readStateValue(path.join(infraDir, "image")) || LOCAL_IMAGE,
+    user: readStateValue(path.join(infraDir, "user")) || LOCAL_USER,
+    password: readStateValue(path.join(infraDir, "password")) || LOCAL_PASSWORD,
+    host: "127.0.0.1",
+    port: Number(hostPort),
+  };
+  await waitForLocalContainerReady(infra);
+  return infra;
+}
+
+export async function inspectContainer(containerName) {
+  try {
+    const { stdout } = await execa("docker", ["inspect", containerName]);
+    const parsed = JSON.parse(stdout);
+    return parsed[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function stopAndRemoveContainer(containerName) {
+  try {
+    await execa("docker", ["rm", "-f", containerName]);
+  } catch {
+    // Already gone.
+  }
+}
+
+async function waitForLocalContainerReady(infra) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < LOCAL_READY_TIMEOUT_MS) {
+    try {
+      await execa("docker", [
+        "exec",
+        infra.containerName,
+        "pg_isready",
+        "-U",
+        infra.user,
+        "-d",
+        LOCAL_ADMIN_DB,
+      ]);
+      return;
+    } catch {
+      await sleep(LOCAL_POLL_INTERVAL_MS);
+    }
+  }
+
+  throw new Error(`Timed out waiting for local database container ${infra.containerName}`);
+}
+
+function buildLocalPostgresContainerLabels(productDir, containerName) {
+  return buildDockerResourceLabels(productDir, {
+    kind: "postgres-container",
+    name: containerName,
+    scope: "local-postgres",
+    cachePolicy: "product-cache",
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/database/locks.mjs

@@ -0,0 +1,31 @@
+import fs from "fs";
+import path from "path";
+
+export async function withLock(lockPath, fn) {
+  const lockDir = `${lockPath}.dir`;
+  const timeoutMs = 60_000;
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir, { recursive: false });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Timed out waiting for lock ${path.basename(lockPath)}`);
+      }
+      await sleep(200);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/database/resource-postgres.mjs

@@ -0,0 +1,72 @@
+import path from "path";
+import { LOCAL_ADMIN_DB } from "./constants.mjs";
+import { readResourceConnectionState } from "./state-files.mjs";
+
+export function resolveResourcePostgresInfra(config, processEnv = process.env) {
+  const resourceName = String(config.testkit?.database?.resource || "").trim();
+  if (!resourceName) {
+    throw new Error("Resource-backed Postgres database requires database.resource");
+  }
+  const connections = parseResourceConnections(processEnv.TESTKIT_RESOURCE_CONNECTIONS_JSON);
+  const connection = connections[resourceName];
+  if (!connection) {
+    const available = Object.keys(connections).sort().join(", ") || "none";
+    throw new Error(`Postgres resource "${resourceName}" is not available. Available resources: ${available}`);
+  }
+  return normalizeResourcePostgresConnection(resourceName, connection);
+}
+
+export function resolveResourcePostgresInfraFromState(stateDir, readStateValue, processEnv = process.env) {
+  const resourceName = readStateValue(path.join(stateDir, "resource_name"));
+  if (!resourceName) return null;
+  const connections = parseResourceConnections(processEnv.TESTKIT_RESOURCE_CONNECTIONS_JSON);
+  const connection = connections[resourceName] || readResourceConnectionState(stateDir, readStateValue);
+  return connection ? normalizeResourcePostgresConnection(resourceName, connection) : null;
+}
+
+function parseResourceConnections(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    throw new Error(`Invalid TESTKIT_RESOURCE_CONNECTIONS_JSON: ${error.message}`);
+  }
+}
+
+function normalizeResourcePostgresConnection(resourceName, connection) {
+  const fromUrl = connection.url ? parsePostgresConnectionUrl(connection.url) : {};
+  const host = connection.host || fromUrl.host;
+  const port = Number(connection.port || fromUrl.port || 5432);
+  const user = connection.user || fromUrl.user;
+  const password = connection.password || fromUrl.password || "";
+  const adminDatabase = connection.adminDatabase || connection.admin_database || fromUrl.database || LOCAL_ADMIN_DB;
+  const sslMode = connection.sslMode || connection.sslmode || fromUrl.sslMode || "disable";
+  if (!host) throw new Error(`Postgres resource "${resourceName}" connection is missing host`);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`Postgres resource "${resourceName}" connection has invalid port`);
+  }
+  if (!user) throw new Error(`Postgres resource "${resourceName}" connection is missing user`);
+  return {
+    backend: "resource",
+    resourceName,
+    host,
+    port,
+    user,
+    password,
+    adminDatabase,
+    sslMode,
+  };
+}
+
+function parsePostgresConnectionUrl(rawUrl) {
+  const parsed = new URL(rawUrl);
+  return {
+    host: parsed.hostname,
+    port: parsed.port ? Number(parsed.port) : 5432,
+    database: decodeURIComponent(parsed.pathname.replace(/^\//, "")) || LOCAL_ADMIN_DB,
+    user: decodeURIComponent(parsed.username || ""),
+    password: decodeURIComponent(parsed.password || ""),
+    sslMode: parsed.searchParams.get("sslmode") || undefined,
+  };
+}

package/lib/database/state-files.mjs

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import { LOCAL_ADMIN_DB } from "./constants.mjs";
+import { buildProductIdentity } from "../ownership/docker.mjs";
+
+export function writeLocalInfraState(infraDir, infra) {
+  const product = buildProductIdentity(path.resolve(infraDir, "..", "..", ".."));
+  fs.writeFileSync(path.join(infraDir, "database_backend"), "local");
+  fs.writeFileSync(path.join(infraDir, "container_name"), infra.containerName);
+  fs.writeFileSync(path.join(infraDir, "container_id"), infra.containerId);
+  fs.writeFileSync(path.join(infraDir, "ownership_product_id"), product.id);
+  fs.writeFileSync(path.join(infraDir, "image"), infra.image);
+  fs.writeFileSync(path.join(infraDir, "user"), infra.user);
+  fs.writeFileSync(path.join(infraDir, "password"), infra.password);
+  fs.writeFileSync(path.join(infraDir, "host"), infra.host);
+  fs.writeFileSync(path.join(infraDir, "port"), String(infra.port));
+}
+
+export function writeCacheState(cacheDir, config, infra, templateDbName, fingerprint) {
+  const backend = config.testkit.database.provider;
+  fs.writeFileSync(path.join(cacheDir, "database_backend"), backend);
+  fs.writeFileSync(path.join(cacheDir, "template_database_name"), templateDbName);
+  fs.writeFileSync(path.join(cacheDir, "template_fingerprint"), fingerprint);
+  if (backend === "local") {
+    fs.writeFileSync(path.join(cacheDir, "container_name"), infra.containerName);
+  } else {
+    fs.writeFileSync(path.join(cacheDir, "resource_name"), infra.resourceName);
+    writeResourceConnectionState(cacheDir, infra);
+  }
+}
+
+export function writeResourceConnectionState(stateDir, infra) {
+  fs.writeFileSync(path.join(stateDir, "resource_host"), infra.host);
+  fs.writeFileSync(path.join(stateDir, "resource_port"), String(infra.port));
+  fs.writeFileSync(path.join(stateDir, "resource_user"), infra.user);
+  fs.writeFileSync(path.join(stateDir, "resource_password"), infra.password);
+  fs.writeFileSync(path.join(stateDir, "resource_admin_database"), infra.adminDatabase || LOCAL_ADMIN_DB);
+  fs.writeFileSync(path.join(stateDir, "resource_sslmode"), infra.sslMode || "disable");
+}
+
+export function readResourceConnectionState(stateDir, readStateValue) {
+  const host = readStateValue(path.join(stateDir, "resource_host"));
+  const user = readStateValue(path.join(stateDir, "resource_user"));
+  if (!host || !user) return null;
+  return {
+    host,
+    port: Number(readStateValue(path.join(stateDir, "resource_port")) || 5432),
+    user,
+    password: readStateValue(path.join(stateDir, "resource_password")) || "",
+    adminDatabase: readStateValue(path.join(stateDir, "resource_admin_database")) || LOCAL_ADMIN_DB,
+    sslMode: readStateValue(path.join(stateDir, "resource_sslmode")) || "disable",
+  };
+}

package/lib/ownership/docker.mjs

@@ -74,6 +74,15 @@ export async function removeDockerContainer(containerRef) {
   }
 }
 
+export async function stopDockerContainer(containerRef) {
+  try {
+    await execa("docker", ["stop", "--time", "5", containerRef]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function dockerContainerSummary(container) {
   const status = container.running ? "running" : "stopped";
   return `${container.name} (${status})`;

package/lib/runner/lifecycle.mjs

@@ -189,7 +189,7 @@ export async function cleanupRuns(productDir, { includeActive = false } = {}) {
     summary.cleaned.push(manifest);
   }
 
-  await cleanupOrphanedLocalInfrastructure(productDir);
+  summary.resourceCleanup = await cleanupOrphanedLocalInfrastructure(productDir);
   return summary;
 }
 

package/lib/runner/maintenance.mjs

@@ -126,6 +126,9 @@ export async function cleanup(productDir, options = {}) {
     label: "assistant session",
     dryRun,
   });
+  for (const target of summary.resourceCleanup?.targets || []) {
+    lines.push(formatDatabaseResourceCleanupLine(target, dryRun));
+  }
   for (const target of resourceCleanup.targets) {
     lines.push(formatDatabaseResourceCleanupLine(target, dryRun));
   }

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.145",
+  "version": "0.1.146",
   "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.145",
+  "version": "0.1.146",
   "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.145"
+    "@elench/testkit-protocol": "0.1.146"
   },
   "private": false
 }

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

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