@elench/testkit 0.1.143 → 0.1.144

package/README.md

@@ -230,6 +230,7 @@ import {
   defineConfig,
   defineFile,
   environment,
+  resource,
   toolchain,
 } from "@elench/testkit/config";
 
@@ -257,9 +258,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 +351,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
@@ -741,6 +755,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/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,7 @@ import {
   runTemplateStage,
   runTemplateStep,
 } from "./template-steps.mjs";
+import { materializeDatabaseConfig } from "../config/database-materialization.mjs";
 import {
   applySourceSchemaCache,
   createSourceSchemaMismatchError,
@@ -49,16 +50,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;
   }
 

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/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.144",
   "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.144",
   "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.144"
   },
   "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.144",
   "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.144",
   "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.144",
   "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.144",
+    "@elench/testkit-bridge": "0.1.144",
+    "@elench/testkit-protocol": "0.1.144",
+    "@elench/ts-analysis": "0.1.144",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",