@elench/testkit 0.1.144 → 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

@@ -0,0 +1,144 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { execa } from "execa";
+
+export const TESTKIT_MANAGED_LABEL = "com.elench.testkit.managed";
+export const TESTKIT_RESOURCE_KIND_LABEL = "com.elench.testkit.resource.kind";
+export const TESTKIT_RESOURCE_NAME_LABEL = "com.elench.testkit.resource.name";
+export const TESTKIT_PRODUCT_DIR_LABEL = "com.elench.testkit.product.dir";
+export const TESTKIT_PRODUCT_ID_LABEL = "com.elench.testkit.product.id";
+export const TESTKIT_SCOPE_LABEL = "com.elench.testkit.scope";
+export const TESTKIT_CACHE_POLICY_LABEL = "com.elench.testkit.cache.policy";
+export const TESTKIT_CREATED_AT_LABEL = "com.elench.testkit.created-at";
+
+const TESTKIT_POSTGRES_CONTAINER_PREFIX = "testkit_pg_";
+
+export function buildProductIdentity(productDir) {
+  const canonicalDir = canonicalizeProductDir(productDir);
+  return {
+    dir: canonicalDir,
+    id: hashString(canonicalDir, 24),
+  };
+}
+
+export function buildDockerResourceLabels(productDir, resource) {
+  const product = buildProductIdentity(productDir);
+  return {
+    [TESTKIT_MANAGED_LABEL]: "true",
+    [TESTKIT_RESOURCE_KIND_LABEL]: resource.kind,
+    [TESTKIT_RESOURCE_NAME_LABEL]: resource.name,
+    [TESTKIT_PRODUCT_DIR_LABEL]: product.dir,
+    [TESTKIT_PRODUCT_ID_LABEL]: product.id,
+    [TESTKIT_SCOPE_LABEL]: resource.scope || resource.kind,
+    [TESTKIT_CACHE_POLICY_LABEL]: resource.cachePolicy || "ephemeral",
+    [TESTKIT_CREATED_AT_LABEL]: resource.createdAt || new Date().toISOString(),
+  };
+}
+
+export function dockerLabelArgs(labels) {
+  return Object.entries(labels).flatMap(([key, value]) => ["--label", `${key}=${String(value)}`]);
+}
+
+export async function inspectDockerContainer(containerRef) {
+  try {
+    const { stdout } = await execa("docker", ["inspect", containerRef]);
+    const parsed = JSON.parse(stdout);
+    return parsed[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listManagedDockerContainers() {
+  return listDockerContainers([
+    "--filter",
+    `label=${TESTKIT_MANAGED_LABEL}=true`,
+  ]);
+}
+
+export async function listLegacyTestkitPostgresContainers() {
+  const containers = await listDockerContainers([]);
+  return containers.filter((container) => {
+    if (!container.name.startsWith(TESTKIT_POSTGRES_CONTAINER_PREFIX)) return false;
+    return container.labels[TESTKIT_MANAGED_LABEL] !== "true";
+  });
+}
+
+export async function removeDockerContainer(containerRef) {
+  try {
+    await execa("docker", ["rm", "-f", containerRef]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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})`;
+}
+
+async function listDockerContainers(filters) {
+  let stdout = "";
+  try {
+    const result = await execa("docker", [
+      "ps",
+      "-a",
+      "--format",
+      "{{.ID}}",
+      ...filters,
+    ]);
+    stdout = result.stdout;
+  } catch {
+    return [];
+  }
+
+  const ids = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (ids.length === 0) return [];
+
+  const containers = [];
+  for (const id of ids) {
+    const inspect = await inspectDockerContainer(id);
+    if (inspect) containers.push(inspect);
+  }
+  return containers.map(normalizeInspectContainer).filter(Boolean);
+}
+
+function normalizeInspectContainer(inspect) {
+  if (!inspect?.Id) return null;
+  const name = String(inspect.Name || "").replace(/^\//, "");
+  const labels = inspect.Config?.Labels || {};
+  return {
+    id: inspect.Id,
+    shortId: inspect.Id.slice(0, 12),
+    name,
+    image: inspect.Config?.Image || "",
+    createdAt: inspect.Created || null,
+    running: Boolean(inspect.State?.Running),
+    status: inspect.State?.Status || "unknown",
+    labels,
+  };
+}
+
+function canonicalizeProductDir(productDir) {
+  const resolved = path.resolve(productDir || process.cwd());
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function hashString(value, length = 24) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, length);
+}

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

@@ -1,9 +1,12 @@
 import fs from "fs";
 import path from "path";
 import {
+  cleanupGlobalLocalDatabaseResources,
+  cleanupOwnedLocalDatabaseResources,
   cleanupOrphanedLocalInfrastructure,
   destroyRuntimeDatabase,
   destroyServiceDatabaseCache,
+  formatDatabaseResourceCleanupLine,
   isDatabaseStateDir,
 } from "../database/index.mjs";
 import { cleanupRuns, formatRunSummary, isPidRunning, listRunManifests } from "./lifecycle.mjs";
@@ -51,6 +54,7 @@ export async function cleanup(productDir, options = {}) {
   const allConfigs = options.allConfigs || [];
   const serviceName = options.serviceName || null;
   const cache = normalizeCacheSelection(options.cache);
+  const cleanResources = Boolean(options.resources || options.globalResources || options.includeLegacyResources);
   const summary = dryRun
     ? collectRunCleanupPreview(productDir)
     : await cleanupRuns(productDir, { includeActive: false });
@@ -66,6 +70,7 @@ export async function cleanup(productDir, options = {}) {
   const runtimeCleaned = [];
   const bundleCleaned = [];
   const assistantCleaned = [];
+  let resourceCleanup = { targets: [], removed: [], kept: [] };
 
   if (!dryRun) {
     for (const target of targets.runtime) {
@@ -83,6 +88,19 @@ export async function cleanup(productDir, options = {}) {
     pruneKnownEmptyDirs(productDir);
   }
 
+  if (cleanResources) {
+    resourceCleanup = options.globalResources
+      ? await cleanupGlobalLocalDatabaseResources({
+          productDir,
+          dryRun,
+          includeLegacy: Boolean(options.includeLegacyResources),
+        })
+      : await cleanupOwnedLocalDatabaseResources(productDir, {
+          dryRun,
+          includeLegacy: Boolean(options.includeLegacyResources),
+        });
+  }
+
   const lines = [];
   for (const manifest of summary.cleaned) {
     lines.push(`${dryRun ? "Would clean" : "Cleaned"} stale run ${formatRunSummary(manifest)}`);
@@ -108,6 +126,12 @@ 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));
+  }
 
   if (lines.length === 0) {
     return {
@@ -118,6 +142,7 @@ export async function cleanup(productDir, options = {}) {
       bundleCleaned,
       assistantCleaned,
       localCleaned,
+      resourceCleanup,
       lines: ["No stale runs to clean."],
     };
   }
@@ -130,6 +155,7 @@ export async function cleanup(productDir, options = {}) {
     bundleCleaned,
     assistantCleaned,
     localCleaned,
+    resourceCleanup,
     lines,
   };
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.144",
+  "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.144",
+  "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.144"
+    "@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.144",
+  "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.144",
+  "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.144",
+  "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.144",
-    "@elench/testkit-bridge": "0.1.144",
-    "@elench/testkit-protocol": "0.1.144",
-    "@elench/ts-analysis": "0.1.144",
+    "@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.142",
+  "version": "0.1.145",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",