@elench/testkit 0.1.143 → 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
@@ -230,6 +231,7 @@ import {
   defineConfig,
   defineFile,
   environment,
+  resource,
   toolchain,
 } from "@elench/testkit/config";
 
@@ -257,9 +259,17 @@ export default defineConfig({
     }),
   },
   environments: {
-    local: environment.local({
+    local: environment.productionLike({
       target: "frontend",
       data: "reuse",
+      resources: {
+        databases: {
+          api: resource.postgres({
+            version: "16",
+            extensions: ["vector"],
+          }),
+        },
+      },
     }),
   },
   services: {
@@ -342,10 +352,15 @@ right way to move expensive browser targets from `next dev` / watch mode to
 stable build-and-start flows.
 
 `testkit local` starts the same service graph as a persistent local production
-environment instead of a test run. It provisions local databases, runs template
-setup, runs `runtime.prepare`, starts dependent services, and records state
-under `.testkit/environments/<name>/` rather than `.testkit/_runs`. Local
-environment processes receive `TESTKIT_ACTIVE=1`, `TESTKIT_MODE=local`, and
+environment instead of a test run. Service database declarations stay logical:
+`database.postgres(...)` says the service needs Postgres, while the selected
+environment decides where that database is materialized. Normal `testkit run`
+uses transient host Docker Postgres. `environment.productionLike(...)` uses the
+Kiln driver by default and maps `resources.databases.<serviceName>` to durable
+Postgres appliances for `testkit local up`. It runs template setup,
+`runtime.prepare`, starts dependent services, and records state under
+`.testkit/environments/<name>/` rather than `.testkit/_runs`. Local environment
+processes receive `TESTKIT_ACTIVE=1`, `TESTKIT_MODE=local`, and
 `TESTKIT_LOCAL_ENV=<name>`. Use `data: "reuse"` for fast restarts against the
 existing local runtime database, `data: "reset"` to refresh runtime databases
 from their templates on each launch, or `--rebuild` to destroy and recreate the
@@ -353,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
@@ -741,6 +765,9 @@ Git metadata.
 `@elench/testkit` provisions Docker-managed local Postgres automatically for
 services that define `database: database.postgres(...)`.
 
+- normal test runs always use transient host-managed Postgres
+- named production-like local environments can place the same logical service
+  database on a Kiln Postgres appliance via `resources.databases.<serviceName>`
 - template databases are cached
 - runtime databases are cloned from templates when binding is `per-runtime`
 - shared databases are reused when binding is `shared`

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/config/database-materialization.mjs

@@ -0,0 +1,62 @@
+const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
+const DEFAULT_LOCAL_USER = "testkit";
+const DEFAULT_LOCAL_PASSWORD = "testkit";
+
+export function buildEnvironmentDatabaseMaterialization(environment = {}) {
+  const databases = environment.resources?.databases || {};
+  return {
+    resourcesByService: Object.fromEntries(
+      Object.keys(databases).map((serviceName) => [serviceName, serviceName])
+    ),
+  };
+}
+
+export function materializeDatabaseConfig(database, serviceName, materialization = {}) {
+  if (!database) return undefined;
+  if (database.provider) {
+    return materializeExplicitProviderDatabaseConfig(database, serviceName);
+  }
+
+  const resourceName = materialization.resourcesByService?.[serviceName] || null;
+  if (resourceName) {
+    return {
+      ...database,
+      provider: "resource",
+      selectedBackend: "resource",
+      resource: resourceName,
+    };
+  }
+
+  return {
+    ...database,
+    provider: "local",
+    selectedBackend: "local",
+    image: database.image || DEFAULT_LOCAL_IMAGE,
+    user: database.user || DEFAULT_LOCAL_USER,
+    password: database.password || DEFAULT_LOCAL_PASSWORD,
+  };
+}
+
+function materializeExplicitProviderDatabaseConfig(database, serviceName) {
+  if (database.provider === "resource") {
+    const resource = String(database.resource || "").trim();
+    if (!resource) {
+      throw new Error(`Service "${serviceName}" database.resource must be a non-empty string`);
+    }
+    return {
+      ...database,
+      resource,
+      selectedBackend: "resource",
+    };
+  }
+  if (database.provider === "local") {
+    return {
+      ...database,
+      selectedBackend: "local",
+      image: database.image || DEFAULT_LOCAL_IMAGE,
+      user: database.user || DEFAULT_LOCAL_USER,
+      password: database.password || DEFAULT_LOCAL_PASSWORD,
+    };
+  }
+  throw new Error(`Service "${serviceName}" database.provider must be "local" or "resource"`);
+}

package/lib/config/database.mjs

@@ -4,50 +4,30 @@ import {
   normalizeConfiguredSteps,
 } from "../shared/configured-steps.mjs";
 
-const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
-const DEFAULT_LOCAL_USER = "testkit";
-const DEFAULT_LOCAL_PASSWORD = "testkit";
-
 export function normalizeDatabaseConfig(explicitService, serviceName) {
   if (explicitService.databaseFrom) return undefined;
   if (!explicitService.database) return undefined;
 
   const rawDatabase = explicitService.database;
-  const provider = rawDatabase.provider || (rawDatabase.resource ? "resource" : "local");
-  if (!["local", "resource"].includes(provider)) {
-    throw new Error(`Service "${serviceName}" database.provider must be "local" or "resource"`);
+  if (Object.prototype.hasOwnProperty.call(rawDatabase, "provider")) {
+    throw new Error(
+      `Service "${serviceName}" database.provider has been removed. Configure database placement in environments.<name>.resources.databases instead.`
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(rawDatabase, "resource")) {
+    throw new Error(
+      `Service "${serviceName}" database.resource has been removed. Configure database placement in environments.<name>.resources.databases instead.`
+    );
   }
 
-  const base = {
+  return {
     ...rawDatabase,
-    provider,
     binding: normalizeDatabaseBinding(rawDatabase.binding || "per-runtime", `Service "${serviceName}" database.binding`),
     reset: rawDatabase.reset !== false,
     sourceSchema: normalizeSourceSchemaConfig(rawDatabase.sourceSchema, serviceName),
     template: normalizeDatabaseTemplateConfig(rawDatabase.template, serviceName),
     serviceName,
   };
-
-  if (provider === "resource") {
-    const resource = String(rawDatabase.resource || "").trim();
-    if (!resource) {
-      throw new Error(`Service "${serviceName}" database.resource must be a non-empty string`);
-    }
-    return {
-      ...base,
-      resource,
-      selectedBackend: "resource",
-    };
-  }
-
-  return {
-    ...base,
-    provider: "local",
-    selectedBackend: "local",
-    image: rawDatabase.image || DEFAULT_LOCAL_IMAGE,
-    user: rawDatabase.user || DEFAULT_LOCAL_USER,
-    password: rawDatabase.password || DEFAULT_LOCAL_PASSWORD,
-  };
 }
 
 export function normalizeDatabaseTemplateConfig(value, serviceName) {

package/lib/config/index.mjs

@@ -244,19 +244,39 @@ function normalizeEnvironmentConfig(name, environment) {
 }
 
 function normalizeEnvironmentResources(environmentName, resources = {}) {
-  if (resources == null) return {};
+  if (resources == null) return { databases: {}, servers: {} };
   if (typeof resources !== "object" || Array.isArray(resources)) {
     throw new Error(`Environment "${environmentName}" resources must be an object`);
   }
+  const allowedKeys = new Set(["databases", "servers"]);
+  const unexpectedKeys = Object.keys(resources).filter((key) => !allowedKeys.has(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(
+      `Environment "${environmentName}" resources only supports "databases" and "servers". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
+    );
+  }
+  return {
+    databases: normalizeEnvironmentResourceGroup(environmentName, "databases", resources.databases, ["postgres"]),
+    servers: normalizeEnvironmentResourceGroup(environmentName, "servers", resources.servers, ["server"]),
+  };
+}
+
+function normalizeEnvironmentResourceGroup(environmentName, groupName, group = {}, allowedKinds) {
+  if (group == null) return {};
+  if (typeof group !== "object" || Array.isArray(group)) {
+    throw new Error(`Environment "${environmentName}" resources.${groupName} must be an object`);
+  }
   return Object.fromEntries(
-    Object.entries(resources).map(([name, resource]) => {
-      const normalizedName = normalizeDatabaseEnvToken(name, `Environment "${environmentName}" resource name`, false);
+    Object.entries(group).map(([name, resource]) => {
+      const normalizedName = normalizeDatabaseEnvToken(name, `Environment "${environmentName}" resources.${groupName} name`, false);
       if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
-        throw new Error(`Environment "${environmentName}" resource "${name}" must be an object`);
+        throw new Error(`Environment "${environmentName}" resources.${groupName}.${name} must be an object`);
       }
       const kind = String(resource.kind || "").trim();
-      if (!["postgres", "server"].includes(kind)) {
-        throw new Error(`Environment "${environmentName}" resource "${name}" kind must be "postgres" or "server"`);
+      if (!allowedKinds.includes(kind)) {
+        throw new Error(
+          `Environment "${environmentName}" resources.${groupName}.${name} kind must be ${allowedKinds.map((entry) => `"${entry}"`).join(" or ")}`
+        );
       }
       return [normalizedName, { ...resource, kind }];
     })
@@ -310,7 +330,7 @@ function normalizeEnvironmentEnv(env) {
   const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
   if (unexpectedKeys.length > 0) {
     throw new Error(
-      `Environment env only supports "values" and "databases". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
+      `Environment env only supports "values", "databases", and "resources". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
     );
   }
   const values = env.values && typeof env.values === "object" && !Array.isArray(env.values) ? env.values : {};

package/lib/config-api/index.d.ts

@@ -85,8 +85,7 @@ export interface StepsBuildConfig {
 
 export type BuildConfig = TscBuildConfig | ScriptBuildConfig | NextBuildConfig | StepsBuildConfig;
 
-export interface LocalDatabaseConfig {
-  provider: "local";
+export interface PostgresDatabaseConfig {
   binding?: "shared" | "per-runtime";
   image?: string;
   password?: string;
@@ -96,17 +95,15 @@ export interface LocalDatabaseConfig {
   user?: string;
 }
 
-export interface ResourceDatabaseConfig {
+export interface MaterializedLocalDatabaseConfig extends PostgresDatabaseConfig {
+  provider: "local";
+}
+
+export interface MaterializedResourceDatabaseConfig extends PostgresDatabaseConfig {
   provider: "resource";
-  binding?: "shared" | "per-runtime";
-  reset?: boolean;
   resource: string;
-  sourceSchema?: DatabaseSourceSchemaConfig | null;
-  template?: DatabaseTemplateConfig;
 }
 
-export type PostgresDatabaseConfig = LocalDatabaseConfig | ResourceDatabaseConfig;
-
 export interface SkipFileRule {
   path: string;
   reason: string;
@@ -324,7 +321,10 @@ export interface ServerResourceConfig {
   vm?: KilnVMResourceConfig;
 }
 
-export type ResourceConfig = PostgresResourceConfig | ServerResourceConfig;
+export interface EnvironmentResourceConfig {
+  databases?: Record<string, PostgresResourceConfig>;
+  servers?: Record<string, ServerResourceConfig>;
+}
 
 export interface LocalEnvironmentConfig {
   kind: "local";
@@ -335,7 +335,7 @@ export interface LocalEnvironmentConfig {
   portOffset?: number;
   productionLike?: boolean;
   publicHost?: string;
-  resources?: Record<string, ResourceConfig>;
+  resources?: EnvironmentResourceConfig;
   target: string;
 }
 
@@ -625,36 +625,16 @@ export declare const database: {
     postgresConnectionFromEnv(prefix: string): unknown;
   };
   postgres(
-    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+    options?: Omit<PostgresDatabaseConfig, "template"> & {
       inputs?: string[];
       migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       template?: DatabaseTemplateOptions;
       verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
     }
-  ): LocalDatabaseConfig;
-  postgres(
-    options?: Omit<ResourceDatabaseConfig, "provider" | "template"> & {
-      inputs?: string[];
-      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-      template?: DatabaseTemplateOptions;
-      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-    }
-  ): ResourceDatabaseConfig;
-  fixture(
-    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
-      inputs?: string[];
-      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-      template?: DatabaseTemplateOptions;
-      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
-      discovery?: DiscoveryConfig;
-      envFiles?: string[];
-    }
-  ): ServiceConfig;
+  ): PostgresDatabaseConfig;
   fixture(
-    options?: Omit<ResourceDatabaseConfig, "provider" | "template"> & {
+    options?: Omit<PostgresDatabaseConfig, "template"> & {
       inputs?: string[];
       migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];

package/lib/config-api/index.mjs

@@ -27,9 +27,14 @@ export function defineFile(metadata) {
 }
 
 function postgresDatabase(options = {}) {
-  const provider = options.resource ? "resource" : options.provider || "local";
+  for (const removedKey of ["provider", "resource"]) {
+    if (Object.prototype.hasOwnProperty.call(options, removedKey)) {
+      throw new Error(
+        `database.postgres(...) no longer accepts "${removedKey}". Configure database placement in environments.<name>.resources.databases instead.`
+      );
+    }
+  }
   return {
-    provider,
     ...options,
   };
 }
@@ -561,7 +566,7 @@ function normalizePresetEnv(env) {
   const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
   if (unexpectedKeys.length > 0) {
     throw new Error(
-      `Preset env only supports "values" and "databases". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
+      `Preset env only supports "values", "databases", and "resources". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
     );
   }
 

package/lib/database/index.mjs

@@ -28,6 +28,20 @@ import {
   runTemplateStage,
   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,
@@ -49,16 +63,29 @@ const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
 const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
 export async function prepareDatabaseRuntime(config, options = {}) {
-  const db = config.testkit.database;
+  const db = materializeDatabaseConfig(
+    config.testkit.database,
+    config.name,
+    options.databaseMaterialization || {}
+  );
   if (!db) return;
+  const runtimeConfig = db === config.testkit.database
+    ? config
+    : {
+        ...config,
+        testkit: {
+          ...config.testkit,
+          database: db,
+        },
+      };
 
-  fs.mkdirSync(config.stateDir, { recursive: true });
+  fs.mkdirSync(runtimeConfig.stateDir, { recursive: true });
   if (db.provider === "local") {
-    await prepareLocalDatabase(config, options);
+    await prepareLocalDatabase(runtimeConfig, options);
     return;
   }
   if (db.provider === "resource") {
-    await prepareResourceDatabase(config, options);
+    await prepareResourceDatabase(runtimeConfig, options);
     return;
   }
 
@@ -116,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) {
@@ -458,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",
@@ -851,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);
 }
@@ -864,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/local/kiln-driver.mjs

@@ -250,7 +250,7 @@ async function attachExistingVMs(client, network, vmRefs) {
 }
 
 async function ensureResources(client, environment, network) {
-	const configured = environment.resources || {};
+	const configured = flattenEnvironmentResources(environment.resources || {});
 	const manifest = {};
 	const connections = {};
 	for (const [name, resource] of Object.entries(configured)) {
@@ -282,6 +282,13 @@ async function ensureResources(client, environment, network) {
 	return { manifest, connections };
 }
 
+export function flattenEnvironmentResources(resources = {}) {
+  return {
+    ...(resources.databases || {}),
+    ...(resources.servers || {}),
+  };
+}
+
 export function buildPostgresApplianceRequest(name, resource, environment, network) {
 	const extensions = normalizePostgresExtensions(resource.extensions);
 	const image = resolvePostgresResourceImage(resource, name);

package/lib/local/orchestrator.mjs

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { spawn } from "child_process";
+import { buildEnvironmentDatabaseMaterialization } from "../config/database-materialization.mjs";
 import { loadConfigContext } from "../config/index.mjs";
 import { prepareDatabaseRuntime } from "../database/index.mjs";
 import { prepareRuntimeServices } from "../runner/runtime-preparation.mjs";
@@ -186,6 +187,7 @@ export function buildLocalRuntimeConfigs(allConfigs, environment, runtimeDir) {
     graphDirName: runtimeConfigs.map((config) => config.name).sort().join("__"),
     portOffset: environment.portOffset || 0,
     publicHost: environment.publicHost || null,
+    databaseMaterialization: buildEnvironmentDatabaseMaterialization(environment),
   }).map((config) => applyLocalEnvironmentConfig(config, environment));
 }
 

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/lib/runner/results.mjs

@@ -8,7 +8,7 @@ export function buildServiceTrackers(servicePlans, startedAt) {
     if (plan.skipped) {
       trackers.set(plan.config.name, {
         name: plan.config.name,
-        dbBackend: plan.config.testkit.database?.selectedBackend || null,
+        dbBackend: inferDatabaseBackend(plan.config),
         skipped: true,
         suiteCount: 0,
         suites: [],
@@ -73,7 +73,7 @@ export function buildServiceTrackers(servicePlans, startedAt) {
 
     trackers.set(plan.config.name, {
       name: plan.config.name,
-      dbBackend: plan.config.testkit.database?.selectedBackend || null,
+      dbBackend: inferDatabaseBackend(plan.config),
       skipped: false,
       suiteCount: suites.length,
       suites,
@@ -90,6 +90,12 @@ export function buildServiceTrackers(servicePlans, startedAt) {
   return trackers;
 }
 
+function inferDatabaseBackend(config) {
+  const database = config.testkit.database;
+  if (!database) return null;
+  return database.selectedBackend || database.provider || "local";
+}
+
 export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now()) {
   const tracker = trackers.get(task.serviceName);
   if (!tracker || tracker.skipped) return;

package/lib/runner/template.mjs

@@ -3,6 +3,7 @@ import {
   finalizeConfiguredInputs,
   finalizeConfiguredSteps,
 } from "../shared/configured-steps.mjs";
+import { materializeDatabaseConfig } from "../config/database-materialization.mjs";
 import { readDatabaseInfo } from "./state-io.mjs";
 
 const PORT_STRIDE = 100;
@@ -75,7 +76,8 @@ export function resolveRuntimeInstanceConfigs(runtimeConfigs, runtimeId, runtime
       publicBaseUrlByService,
       options.publicHost || null,
       stateDirByService,
-      urlMappings
+      urlMappings,
+      options.databaseMaterialization || {}
     )
   );
 }
@@ -123,7 +125,8 @@ export function resolveRuntimeConfig(
   publicBaseUrlByService,
   publicHost,
   stateDirByService,
-  urlMappings
+  urlMappings,
+  databaseMaterialization = {}
 ) {
   const stateDir = resolveServiceStateDir(runtimeDir, config);
   const prepareDir = resolveServicePrepareDir(runtimeDir, config);
@@ -147,11 +150,15 @@ export function resolveRuntimeConfig(
   };
 
   const database = config.testkit.database
-    ? {
-        ...config.testkit.database,
-        sourceSchema: finalizeSourceSchema(config.testkit.database.sourceSchema, context),
-        template: finalizeDatabaseTemplate(config.testkit.database.template, context),
-      }
+    ? materializeDatabaseConfig(
+        {
+          ...config.testkit.database,
+          sourceSchema: finalizeSourceSchema(config.testkit.database.sourceSchema, context),
+          template: finalizeDatabaseTemplate(config.testkit.database.template, context),
+        },
+        config.name,
+        databaseMaterialization
+      )
     : undefined;
 
   const runtime = {

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.143",
+  "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.143",
+  "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.143"
+    "@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.143",
+  "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.143",
+  "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.143",
+  "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.143",
-    "@elench/testkit-bridge": "0.1.143",
-    "@elench/testkit-protocol": "0.1.143",
-    "@elench/ts-analysis": "0.1.143",
+    "@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",