@elench/testkit 0.1.144 → 0.1.145

package/README.md

@@ -61,6 +61,7 @@ npx @elench/testkit --type int --write-status
 npx @elench/testkit status
 npx @elench/testkit destroy
 npx @elench/testkit cleanup
+npx @elench/testkit cleanup --resources --global --dry-run
 
 # Local production environment
 npx @elench/testkit local up
@@ -367,6 +368,15 @@ environment state. Testkit only supports local environments here; it does not
 copy production data and it refuses managed runtime database URLs that are not
 loopback PostgreSQL URLs.
 
+Testkit-owned Docker resources are labelled at creation time so they can be
+found again even if product-local `.testkit` state is deleted. `testkit destroy`
+removes labelled resources for the current product after service state is
+destroyed. `testkit cleanup --resources` cleans stale resources for the current
+product; add `--global` to clean labelled resources whose product directory no
+longer exists, and add `--include-legacy` only when you intentionally want to
+remove old unlabelled `testkit_pg_*` containers from pre-ownership Testkit
+versions. Use `--dry-run` first when cleaning globally.
+
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
 source database as the schema source of truth. A normal `testkit run` resolves a

package/lib/cli/commands/cleanup.mjs

@@ -19,6 +19,18 @@ export default class CleanupCommand extends Command {
       multiple: true,
       options: ["runtime", "bundles", "assistant", "all"],
     }),
+    resources: Flags.boolean({
+      description: "Clean Testkit-owned Docker resources that are stale or orphaned",
+      default: false,
+    }),
+    global: Flags.boolean({
+      description: "Find orphaned Testkit-owned resources across all products",
+      default: false,
+    }),
+    "include-legacy": Flags.boolean({
+      description: "Include old unlabelled testkit_pg_* Docker containers in resource cleanup",
+      default: false,
+    }),
   };
 
   async run() {

package/lib/cli/operations/cleanup/operation.mjs

@@ -9,5 +9,8 @@ export async function executeCleanupOperation(flags = {}) {
     serviceName: flags.service || null,
     dryRun: flags["dry-run"],
     cache: flags.cache || [],
+    resources: flags.resources,
+    globalResources: flags.global,
+    includeLegacyResources: flags["include-legacy"],
   });
 }

package/lib/cli/operations/destroy/operation.mjs

@@ -1,12 +1,17 @@
 import * as runner from "../../../runner/index.mjs";
 import { loadManagedConfigs } from "../../../app/configs.mjs";
+import { destroyOwnedLocalDatabaseResources } from "../../../database/index.mjs";
 
 export async function executeDestroyOperation(flags = {}) {
-  const { configs } = await loadManagedConfigs({ dir: flags.dir, service: flags.service });
+  const { allConfigs, configs } = await loadManagedConfigs({ dir: flags.dir, service: flags.service });
   const results = [];
   for (const config of configs) {
     await runner.destroy(config);
     results.push({ name: config.name, destroyed: true });
   }
+  const productDir = allConfigs[0]?.productDir || process.cwd();
+  if (!flags.service) {
+    await destroyOwnedLocalDatabaseResources(productDir);
+  }
   return results;
 }

package/lib/database/index.mjs

@@ -29,6 +29,19 @@ import {
   runTemplateStep,
 } from "./template-steps.mjs";
 import { materializeDatabaseConfig } from "../config/database-materialization.mjs";
+import {
+  TESTKIT_PRODUCT_DIR_LABEL,
+  TESTKIT_PRODUCT_ID_LABEL,
+  TESTKIT_RESOURCE_KIND_LABEL,
+  TESTKIT_SCOPE_LABEL,
+  buildDockerResourceLabels,
+  buildProductIdentity,
+  dockerContainerSummary,
+  dockerLabelArgs,
+  listLegacyTestkitPostgresContainers,
+  listManagedDockerContainers,
+  removeDockerContainer,
+} from "../ownership/docker.mjs";
 import {
   applySourceSchemaCache,
   createSourceSchemaMismatchError,
@@ -130,15 +143,45 @@ export async function destroyServiceDatabaseCache(productDir, serviceName) {
 
 export async function cleanupOrphanedLocalInfrastructure(productDir) {
   const infraDir = getLocalInfraDir(productDir);
-  if (!fs.existsSync(infraDir)) return;
 
   if (hasRemainingLocalArtifacts(productDir)) return;
 
-  const containerName = readStateValue(path.join(infraDir, "container_name"));
-  if (containerName) {
-    await stopAndRemoveContainer(containerName);
+  if (fs.existsSync(infraDir)) {
+    const containerName = readStateValue(path.join(infraDir, "container_name"));
+    if (containerName) {
+      await stopAndRemoveContainer(containerName);
+    }
+    fs.rmSync(infraDir, { recursive: true, force: true });
   }
-  fs.rmSync(infraDir, { recursive: true, force: true });
+
+  await cleanupOwnedLocalDatabaseResources(productDir);
+}
+
+export async function destroyOwnedLocalDatabaseResources(productDir, options = {}) {
+  return cleanupOwnedLocalDatabaseResources(productDir, {
+    ...options,
+    force: true,
+  });
+}
+
+export async function cleanupOwnedLocalDatabaseResources(productDir, options = {}) {
+  return cleanupLocalPostgresDockerResources({
+    productDir,
+    dryRun: Boolean(options.dryRun),
+    force: Boolean(options.force),
+    global: false,
+    includeLegacy: Boolean(options.includeLegacy),
+  });
+}
+
+export async function cleanupGlobalLocalDatabaseResources(options = {}) {
+  return cleanupLocalPostgresDockerResources({
+    productDir: options.productDir || process.cwd(),
+    dryRun: Boolean(options.dryRun),
+    force: false,
+    global: true,
+    includeLegacy: Boolean(options.includeLegacy),
+  });
 }
 
 export function isDatabaseStateDir(dir) {
@@ -472,11 +515,13 @@ async function ensureLocalContainer(productDir, database = {}) {
   }
 
   if (!inspect) {
+    const labels = buildLocalPostgresContainerLabels(productDir, containerName);
     await execa("docker", [
       "run",
       "-d",
       "--name",
       containerName,
+      ...dockerLabelArgs(labels),
       "-e",
       `POSTGRES_USER=${user}`,
       "-e",
@@ -865,6 +910,117 @@ function parsePostgresConnectionUrl(rawUrl) {
   };
 }
 
+async function cleanupLocalPostgresDockerResources(options = {}) {
+  const product = buildProductIdentity(options.productDir || process.cwd());
+  const managed = await listManagedDockerContainers();
+  const targets = [];
+  const kept = [];
+
+  for (const container of managed) {
+    if (!isManagedLocalPostgresContainer(container)) continue;
+    const classification = classifyManagedLocalPostgresContainer(container, product, options);
+    if (classification.remove) {
+      targets.push({ ...container, reason: classification.reason, legacy: false });
+    } else if (classification.reason) {
+      kept.push({ ...container, reason: classification.reason, legacy: false });
+    }
+  }
+
+  if (options.includeLegacy) {
+    const currentLegacyName = buildContainerName(product.dir);
+    for (const container of await listLegacyTestkitPostgresContainers()) {
+      if (!options.global && container.name !== currentLegacyName) continue;
+      targets.push({ ...container, reason: "legacy-unlabelled", legacy: true });
+    }
+  }
+
+  if (!options.dryRun) {
+    for (const container of targets) {
+      await removeDockerContainer(container.name || container.id);
+    }
+  }
+
+  return {
+    removed: options.dryRun ? [] : targets,
+    targets,
+    kept,
+  };
+}
+
+function classifyManagedLocalPostgresContainer(container, product, options) {
+  const labels = container.labels || {};
+  const containerProductId = labels[TESTKIT_PRODUCT_ID_LABEL] || "";
+  const containerProductDir = labels[TESTKIT_PRODUCT_DIR_LABEL] || "";
+  const currentProduct = containerProductId === product.id;
+
+  if (options.force && currentProduct) {
+    return { remove: true, reason: "destroy-current-product" };
+  }
+
+  if (!options.global && !currentProduct) {
+    return { remove: false, reason: "different-product" };
+  }
+
+  if (currentProduct) {
+    if (!hasRemainingLocalArtifacts(product.dir)) {
+      return { remove: true, reason: "current-product-no-local-artifacts" };
+    }
+    if (!localArtifactsReferenceContainer(product.dir, container.name)) {
+      return { remove: true, reason: "current-product-unreferenced" };
+    }
+    return { remove: false, reason: "current-product-referenced" };
+  }
+
+  if (options.global && containerProductDir && !fs.existsSync(containerProductDir)) {
+    return { remove: true, reason: "product-dir-missing" };
+  }
+
+  if (options.global && containerProductDir && !hasRemainingLocalArtifacts(containerProductDir)) {
+    return { remove: true, reason: "product-has-no-local-artifacts" };
+  }
+
+  return { remove: false, reason: options.global ? "other-product-retained" : "different-product" };
+}
+
+function isManagedLocalPostgresContainer(container) {
+  const labels = container.labels || {};
+  return (
+    labels[TESTKIT_RESOURCE_KIND_LABEL] === "postgres-container" &&
+    labels[TESTKIT_SCOPE_LABEL] === "local-postgres"
+  );
+}
+
+function buildLocalPostgresContainerLabels(productDir, containerName) {
+  return buildDockerResourceLabels(productDir, {
+    kind: "postgres-container",
+    name: containerName,
+    scope: "local-postgres",
+    cachePolicy: "product-cache",
+  });
+}
+
+function localArtifactsReferenceContainer(productDir, containerName) {
+  if (!containerName) return false;
+  const root = path.join(productDir, ".testkit");
+  let referenced = false;
+  visitDirs(root, (dir) => {
+    if (referenced) return;
+    for (const fileName of ["container_name", "local_container_name"]) {
+      if (readStateValue(path.join(dir, fileName)) === containerName) {
+        referenced = true;
+        return;
+      }
+    }
+  });
+  return referenced;
+}
+
+export function formatDatabaseResourceCleanupLine(entry, dryRun = false) {
+  const action = dryRun ? "Would remove" : "Removed";
+  const legacy = entry.legacy ? " legacy" : "";
+  return `${action}${legacy} database resource ${dockerContainerSummary(entry)} reason=${entry.reason}`;
+}
+
 function buildContainerName(productDir) {
   return buildContainerNameModel(productDir);
 }
@@ -878,9 +1034,11 @@ function buildRuntimeDatabaseName(serviceName, bindingKey, fingerprint) {
 }
 
 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);

package/lib/ownership/docker.mjs

@@ -0,0 +1,135 @@
+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 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/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,9 @@ export async function cleanup(productDir, options = {}) {
     label: "assistant session",
     dryRun,
   });
+  for (const target of resourceCleanup.targets) {
+    lines.push(formatDatabaseResourceCleanupLine(target, dryRun));
+  }
 
   if (lines.length === 0) {
     return {
@@ -118,6 +139,7 @@ export async function cleanup(productDir, options = {}) {
       bundleCleaned,
       assistantCleaned,
       localCleaned,
+      resourceCleanup,
       lines: ["No stale runs to clean."],
     };
   }
@@ -130,6 +152,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.145",
   "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.145",
   "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.145"
   },
   "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.145",
   "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.145",
   "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.145",
   "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.145",
+    "@elench/testkit-bridge": "0.1.145",
+    "@elench/testkit-protocol": "0.1.145",
+    "@elench/ts-analysis": "0.1.145",
     "@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.144",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",