@elench/testkit 0.1.46 → 0.1.47

package/lib/config/index.mjs

@@ -119,9 +119,12 @@ function normalizeServiceConfig({
     ...loadServiceEnv(productDir, envFiles),
     ...(explicitService.env || {}),
   };
+  if (explicitService.migrate || explicitService.seed) {
+    throw new Error(
+      `Service "${name}" uses removed migrate/seed hooks. Move template lifecycle to database.template.{migrate,seed,verify}.`
+    );
+  }
   const database = normalizeDatabaseConfig(explicitService, name);
-  const migrate = normalizeLifecycle(explicitService.migrate);
-  const seed = normalizeLifecycle(explicitService.seed);
   const runtime = normalizeRuntimeConfig(explicitService.runtime, name);
   const skip = normalizeSkipConfig(explicitService.skip, {
     name,
@@ -133,20 +136,12 @@ function normalizeServiceConfig({
     suites,
   });
 
-  if (!explicitService.databaseFrom && !database && (migrate || seed)) {
-    throw new Error(
-      `Service "${name}" defines migrate/seed hooks but no database. Add localDatabase(...) in testkit.setup.ts.`
-    );
-  }
-
   validateServiceConfig({
     name,
     local,
     database,
     databaseFrom: explicitService.databaseFrom,
     runtime,
-    migrate,
-    seed,
     dependsOn: explicitService.dependsOn || [],
     suites,
     productDir,
@@ -168,8 +163,6 @@ function normalizeServiceConfig({
       envFiles,
       requirements,
       serviceEnv,
-      migrate,
-      seed,
       skip,
       runtime,
       local,
@@ -276,9 +269,7 @@ function normalizeDatabaseConfig(explicitService, serviceName) {
     image: database.image || DEFAULT_LOCAL_IMAGE,
     user: database.user || DEFAULT_LOCAL_USER,
     password: database.password || DEFAULT_LOCAL_PASSWORD,
-    template: {
-      inputs: Array.isArray(database.template?.inputs) ? [...database.template.inputs] : [],
-    },
+    template: normalizeDatabaseTemplateConfig(database.template, serviceName),
     serviceName,
   };
 }
@@ -309,18 +300,117 @@ function normalizeOptionalString(value) {
   return normalized.length > 0 ? normalized : null;
 }
 
-function normalizeLifecycle(value) {
-  if (!value) return undefined;
-  if (!value.cmd && !value.testkitCmd) {
-    throw new Error("Lifecycle config requires cmd or testkitCmd");
+function normalizeDatabaseTemplateConfig(value, serviceName) {
+  if (value == null) {
+    return {
+      inputs: [],
+      migrate: [],
+      seed: [],
+      verify: [],
+    };
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`Service "${serviceName}" database.template must be an object`);
   }
 
   return {
-    cmd: value.testkitCmd || value.cmd,
-    cwd: value.testkitCwd || value.cwd,
+    inputs: normalizeTemplateInputs(value.inputs, serviceName),
+    migrate: normalizeTemplateLifecycleSteps(
+      value.migrate,
+      `Service "${serviceName}" database.template.migrate`
+    ),
+    seed: normalizeTemplateLifecycleSteps(
+      value.seed,
+      `Service "${serviceName}" database.template.seed`
+    ),
+    verify: normalizeTemplateLifecycleSteps(
+      value.verify,
+      `Service "${serviceName}" database.template.verify`
+    ),
   };
 }
 
+function normalizeTemplateInputs(value, serviceName) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`Service "${serviceName}" database.template.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(
+        `Service "${serviceName}" database.template.inputs[${index}] must be a non-empty string`
+      );
+    }
+    return normalized;
+  });
+}
+
+function normalizeTemplateLifecycleSteps(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+
+  return value.map((step, index) => normalizeTemplateLifecycleStep(step, `${label}[${index}]`));
+}
+
+function normalizeTemplateLifecycleStep(step, label) {
+  if (!step || typeof step !== "object") {
+    throw new Error(`${label} must be an object`);
+  }
+
+  const kind = normalizeOptionalString(step.kind);
+  if (kind === "command") {
+    const cmd = normalizeOptionalString(step.cmd);
+    if (!cmd) throw new Error(`${label}.cmd must be a non-empty string`);
+    return {
+      kind,
+      cmd,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "sql-file") {
+    const filePath = normalizeOptionalString(step.path);
+    if (!filePath) throw new Error(`${label}.path must be a non-empty string`);
+    return {
+      kind,
+      path: filePath,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "module") {
+    const specifier = normalizeOptionalString(step.specifier);
+    if (!specifier) throw new Error(`${label}.specifier must be a non-empty string`);
+    return {
+      kind,
+      specifier,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+
+  throw new Error(`${label}.kind must be one of: command, sql-file, module`);
+}
+
+function normalizeTemplateStepInputs(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label}.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(`${label}.inputs[${index}] must be a non-empty string`);
+    }
+    return normalized;
+  });
+}
+
 function normalizeSkipConfig(value, { name, productDir, suites }) {
   if (!value) return undefined;
 
@@ -587,8 +677,6 @@ function validateServiceConfig({
   database,
   databaseFrom,
   runtime,
-  migrate,
-  seed,
   dependsOn,
   suites,
   productDir,
@@ -626,11 +714,42 @@ function validateServiceConfig({
   if (local?.cwd) {
     ensureExistingPath(productDir, local.cwd, `Service "${name}" local.cwd`);
   }
-  if (migrate?.cwd) {
-    ensureExistingPath(productDir, migrate.cwd, `Service "${name}" migrate.cwd`);
+  for (const [stageName, steps] of Object.entries(database?.template || {})) {
+    if (stageName === "inputs") continue;
+    for (const step of steps || []) {
+      if (step.cwd) {
+        ensureExistingPath(
+          productDir,
+          step.cwd,
+          `Service "${name}" database.template.${stageName} step cwd`
+        );
+      }
+      if (step.kind === "sql-file") {
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          step.path,
+          `Service "${name}" database.template.${stageName} sql file`
+        );
+      }
+      if (step.kind === "module") {
+        const { modulePath } = parseModuleSpecifier(step.specifier);
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          modulePath,
+          `Service "${name}" database.template.${stageName} module`
+        );
+      }
+      for (const input of step.inputs || []) {
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          input,
+          `Service "${name}" database.template.${stageName} step input`
+        );
+      }
+    }
   }
-  if (seed?.cwd) {
-    ensureExistingPath(productDir, seed.cwd, `Service "${name}" seed.cwd`);
+  for (const input of database?.template?.inputs || []) {
+    ensureExistingPath(productDir, input, `Service "${name}" database.template input`);
   }
 }
 
@@ -687,7 +806,7 @@ function normalizePath(value) {
     .replace(/^\.\/+/, "");
 }
 
-function resolveProductDir(cwd, explicitDir) {
+export function resolveProductDir(cwd, explicitDir) {
   const dir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
   if (!fs.existsSync(dir)) {
     throw new Error(`Product directory does not exist: ${dir}`);
@@ -722,3 +841,11 @@ function detectNextApp(cwd) {
     fs.existsSync(path.join(cwd, "next.config.ts"))
   );
 }
+
+function parseModuleSpecifier(specifier) {
+  const [modulePath, exportName] = String(specifier).split("#", 2);
+  return {
+    modulePath,
+    exportName: exportName || "default",
+  };
+}

package/lib/database/fingerprint.mjs

@@ -2,6 +2,7 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { resolveServiceCwd } from "../config/index.mjs";
+import { collectTemplateInputs } from "./template-steps.mjs";
 
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
 const LOCAL_USER = "testkit";
@@ -14,15 +15,14 @@ export async function computeTemplateFingerprint(config) {
     selectedBackend: db.selectedBackend,
     image: db.image || LOCAL_IMAGE,
     user: db.user || LOCAL_USER,
-    migrate: config.testkit.migrate || null,
-    seed: config.testkit.seed || null,
+    template: db.template || null,
   }));
 
   for (const envFile of config.testkit.envFiles || []) {
     appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
   }
-  for (const input of db.template.inputs || []) {
-    appendInputToHash(hash, config.productDir, input);
+  for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
+    appendResolvedInputToHash(hash, config.productDir, input);
   }
 
   return hash.digest("hex");
@@ -30,6 +30,10 @@ export async function computeTemplateFingerprint(config) {
 
 export function appendInputToHash(hash, productDir, input) {
   const absPath = resolveServiceCwd(productDir, input);
+  appendResolvedInputToHash(hash, productDir, absPath);
+}
+
+function appendResolvedInputToHash(hash, productDir, absPath) {
   if (!fs.existsSync(absPath)) {
     hash.update(`missing:${path.relative(productDir, absPath)}`);
     return;
@@ -40,7 +44,7 @@ export function appendInputToHash(hash, productDir, input) {
     hash.update(`dir:${path.relative(productDir, absPath)}`);
     for (const entry of fs.readdirSync(absPath).sort()) {
       if (entry === ".git" || entry === "node_modules" || entry === ".testkit") continue;
-      appendInputToHash(hash, productDir, path.join(input, entry));
+      appendResolvedInputToHash(hash, productDir, path.join(absPath, entry));
     }
     return;
   }

package/lib/database/fingerprint.test.mjs

@@ -74,13 +74,19 @@ describe("database-fingerprint", () => {
           selectedBackend: "local",
           template: {
             inputs: ["schema"],
+            migrate: [
+              {
+                kind: "command",
+                cmd: "npm run migrate",
+                cwd: ".",
+                inputs: [],
+              },
+            ],
+            seed: [],
+            verify: [],
           },
         },
         envFiles: [".env.testkit"],
-        migrate: {
-          cmd: "npm run migrate",
-        },
-        seed: null,
       },
     };
 

package/lib/database/index.mjs

@@ -25,6 +25,7 @@ import {
   readStateValue as readStateValueModel,
   visitDirs as visitDirsModel,
 } from "./state.mjs";
+import { captureTemplateSnapshot, runTemplateStage } from "./template-steps.mjs";
 
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
 const LOCAL_USER = "testkit";
@@ -33,19 +34,39 @@ const LOCAL_ADMIN_DB = "postgres";
 const LOCAL_READY_TIMEOUT_MS = 60_000;
 const LOCAL_POLL_INTERVAL_MS = 1_000;
 
-export async function prepareDatabaseRuntime(config, hooks = {}) {
+export async function prepareDatabaseRuntime(config) {
   const db = config.testkit.database;
   if (!db) return;
 
   fs.mkdirSync(config.stateDir, { recursive: true });
   if (db.provider === "local") {
-    await prepareLocalDatabase(config, hooks);
+    await prepareLocalDatabase(config);
     return;
   }
 
   throw new Error(`Unsupported database provider "${db.provider}"`);
 }
 
+export async function captureDatabaseTemplateSnapshot(config, outputPath) {
+  if (!config.testkit.database || config.testkit.database.provider !== "local") {
+    throw new Error(`Service "${config.name}" does not use a local testkit database`);
+  }
+
+  await prepareDatabaseRuntime(config);
+  const cacheDir = getLocalServiceCacheDir(config.productDir, config.name);
+  const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+  if (!templateDbName) {
+    throw new Error(`Missing template database for service "${config.name}"`);
+  }
+
+  const infra = await loadExistingLocalContainer(config.productDir);
+  if (!infra) {
+    throw new Error(`Missing local database container for service "${config.name}"`);
+  }
+
+  return captureTemplateSnapshot(config, outputPath, buildDatabaseUrl(infra, templateDbName));
+}
+
 export async function destroyRuntimeDatabase({ productDir, stateDir }) {
   const backend = readStateValue(path.join(stateDir, "database_backend"));
   if (backend === "local") {
@@ -115,7 +136,7 @@ export function showServiceDatabaseStatus(productDir, serviceName) {
   return true;
 }
 
-async function prepareLocalDatabase(config, hooks) {
+async function prepareLocalDatabase(config) {
   const db = config.testkit.database;
   const productDir = config.productDir;
   const serviceName = config.name;
@@ -131,7 +152,7 @@ async function prepareLocalDatabase(config, hooks) {
   );
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
-    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, hooks);
+    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint);
   });
 
   await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
@@ -139,7 +160,7 @@ async function prepareLocalDatabase(config, hooks) {
   });
 }
 
-async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, hooks) {
+async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint) {
   const serviceName = config.name;
   const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
   const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
@@ -161,13 +182,15 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
     await dropDatabaseIfExists(infra, desiredDbName);
   }
 
-  await createEmptyDatabase(infra, desiredDbName);
   const templateUrl = buildDatabaseUrl(infra, desiredDbName);
-  if (hooks.runMigrate) {
-    await hooks.runMigrate(templateUrl);
-  }
-  if (hooks.runSeed) {
-    await hooks.runSeed(templateUrl);
+  await createEmptyDatabase(infra, desiredDbName);
+  try {
+    await runTemplateStage(config, "migrate", templateUrl);
+    await runTemplateStage(config, "seed", templateUrl);
+    await runTemplateStage(config, "verify", templateUrl);
+  } catch (error) {
+    await dropDatabaseIfExists(infra, desiredDbName);
+    throw error;
   }
 
   writeLocalCacheState(cacheDir, infra, desiredDbName, templateFingerprint);

package/lib/database/template-steps.mjs

@@ -0,0 +1,232 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { build } from "esbuild";
+import { execa, execaCommand } from "execa";
+import { fileURLToPath, pathToFileURL } from "url";
+import { resolveServiceCwd } from "../config/index.mjs";
+import { buildExecutionEnv } from "../runner/template.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ROOT_ENTRY = path.join(PACKAGE_ROOT, "lib", "index.mjs");
+const SETUP_ENTRY = path.join(PACKAGE_ROOT, "lib", "setup", "index.mjs");
+const RUNTIME_ENTRY = path.join(PACKAGE_ROOT, "lib", "runtime", "index.mjs");
+const KNOWN_FAILURES_ENTRY = path.join(PACKAGE_ROOT, "lib", "known-failures", "index.mjs");
+
+export async function runTemplateStage(config, stageName, databaseUrl) {
+  const steps = config.testkit.database?.template?.[stageName] || [];
+  if (steps.length === 0) return;
+
+  const env = {
+    ...buildExecutionEnv(config, {}, process.env),
+    DATABASE_URL: databaseUrl,
+  };
+
+  for (const [index, step] of steps.entries()) {
+    const label = `template:${stageName}:${config.name}:${index + 1}`;
+    console.log(`\n── ${label} ──`);
+    await runTemplateStep(config, stageName, step, env);
+  }
+}
+
+export function collectTemplateInputs(productDir, template = {}) {
+  const inputs = new Set();
+  for (const input of template.inputs || []) {
+    inputs.add(resolveTemplatePath(productDir, null, input));
+  }
+  for (const stageName of ["migrate", "seed", "verify"]) {
+    for (const step of template[stageName] || []) {
+      if (step.kind === "sql-file") {
+        inputs.add(resolveTemplatePath(productDir, step.cwd, step.path));
+      }
+      if (step.kind === "module") {
+        inputs.add(resolveTemplatePath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath));
+      }
+      for (const input of step.inputs || []) {
+        inputs.add(resolveTemplatePath(productDir, step.cwd, input));
+      }
+    }
+  }
+  return [...inputs].sort();
+}
+
+export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
+  const templateDbUrl = databaseUrl;
+  const absoluteOutputPath = path.resolve(config.productDir, outputPath);
+  fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
+
+  await execa("pg_dump", [
+    "--schema-only",
+    "--no-owner",
+    "--no-privileges",
+    "--file",
+    absoluteOutputPath,
+    templateDbUrl,
+  ], {
+    cwd: config.productDir,
+    env: {
+      ...buildExecutionEnv(config, {}, process.env),
+      DATABASE_URL: templateDbUrl,
+    },
+    stdio: "inherit",
+  });
+
+  sanitizeSnapshotFile(absoluteOutputPath);
+  return absoluteOutputPath;
+}
+
+function sanitizeSnapshotFile(filePath) {
+  const dump = fs.readFileSync(filePath, "utf8");
+  const sanitized = dump
+    .split("\n")
+    .filter((line) => line.trim() !== "SET transaction_timeout = 0;")
+    .join("\n");
+
+  if (sanitized !== dump) {
+    fs.writeFileSync(filePath, sanitized);
+  }
+}
+
+async function runTemplateStep(config, stageName, step, env) {
+  if (step.kind === "command") {
+    await execaCommand(step.cmd, {
+      cwd: resolveTemplateCwd(config.productDir, step.cwd),
+      env,
+      stdio: "inherit",
+      shell: true,
+    });
+    return;
+  }
+
+  if (step.kind === "sql-file") {
+    await execa("psql", [
+      env.DATABASE_URL,
+      "-v",
+      "ON_ERROR_STOP=1",
+      "-X",
+      "-f",
+      resolveTemplatePath(config.productDir, step.cwd, step.path),
+    ], {
+      cwd: resolveTemplateCwd(config.productDir, step.cwd),
+      env,
+      stdio: "inherit",
+    });
+    return;
+  }
+
+  if (step.kind === "module") {
+    const moduleRef = await loadTemplateModule(config.productDir, step);
+    const { exportName } = parseModuleSpecifier(step.specifier);
+    const fn = moduleRef[exportName];
+    if (typeof fn !== "function") {
+      throw new Error(
+        `Template module step "${step.specifier}" did not export a function named "${exportName}"`
+      );
+    }
+
+    await withProcessContext(
+      resolveTemplateCwd(config.productDir, step.cwd),
+      env,
+      async () => {
+        await fn({
+          productDir: config.productDir,
+          cwd: resolveTemplateCwd(config.productDir, step.cwd),
+          serviceName: config.name,
+          stage: stageName,
+          databaseUrl: env.DATABASE_URL,
+          env: { ...env },
+          runtimeId: config.runtimeId || null,
+          stateDir: config.stateDir,
+        });
+      }
+    );
+    return;
+  }
+
+  throw new Error(`Unsupported template step kind "${step.kind}"`);
+}
+
+function resolveTemplateCwd(productDir, stepCwd) {
+  return resolveServiceCwd(productDir, stepCwd || ".");
+}
+
+function resolveTemplatePath(productDir, stepCwd, targetPath) {
+  return path.resolve(resolveTemplateCwd(productDir, stepCwd), targetPath);
+}
+
+async function loadTemplateModule(productDir, step) {
+  const { modulePath } = parseModuleSpecifier(step.specifier);
+  const absoluteModulePath = resolveTemplatePath(productDir, step.cwd, modulePath);
+  const bundleDir = path.join(productDir, ".testkit", "_template-steps");
+  fs.mkdirSync(bundleDir, { recursive: true });
+
+  const cacheKey = buildModuleCacheKey(absoluteModulePath);
+  const outputFile = path.join(bundleDir, `${path.basename(modulePath).replace(/\W+/g, "-")}-${cacheKey.slice(0, 12)}.mjs`);
+
+  await build({
+    absWorkingDir: productDir,
+    bundle: true,
+    entryPoints: [absoluteModulePath],
+    format: "esm",
+    legalComments: "none",
+    outfile: outputFile,
+    platform: "node",
+    sourcemap: "inline",
+    target: "es2020",
+    plugins: [testkitAliasPlugin()],
+  });
+
+  return import(`${pathToFileURL(outputFile).href}?v=${cacheKey}`);
+}
+
+function buildModuleCacheKey(modulePath) {
+  const content = fs.readFileSync(modulePath, "utf8");
+  return crypto.createHash("sha256").update(modulePath).update("\0").update(content).digest("hex");
+}
+
+function testkitAliasPlugin() {
+  return {
+    name: "testkit-template-step-alias",
+    setup(buildApi) {
+      buildApi.onResolve({ filter: /^@elench\/testkit(?:\/.*)?$/ }, (args) => ({
+        namespace: "file",
+        path: resolvePackageSubpath(args.path),
+      }));
+    },
+  };
+}
+
+function resolvePackageSubpath(specifier) {
+  const subpath = specifier.slice("@elench/testkit".length);
+  if (!subpath) return ROOT_ENTRY;
+  if (subpath === "/setup") return SETUP_ENTRY;
+  if (subpath === "/runtime") return RUNTIME_ENTRY;
+  if (subpath === "/known-failures") return KNOWN_FAILURES_ENTRY;
+
+  throw new Error(`Unsupported @elench/testkit import "${specifier}" while loading template step`);
+}
+
+function parseModuleSpecifier(specifier) {
+  const [modulePath, exportName] = String(specifier).split("#", 2);
+  return {
+    modulePath,
+    exportName: exportName || "default",
+  };
+}
+
+async function withProcessContext(cwd, env, fn) {
+  const previousCwd = process.cwd();
+  const previousEnv = process.env;
+  process.chdir(cwd);
+  process.env = {
+    ...previousEnv,
+    ...env,
+  };
+
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previousCwd);
+    process.env = previousEnv;
+  }
+}