@elench/testkit 0.1.48 → 0.1.49

package/README.md

@@ -119,7 +119,9 @@ export default defineTestkitSetup({
       ...nextService({
         cwd: "frontend",
         port: 3000,
+        start: "exec ./node_modules/.bin/next start --port {port}",
         env: {
+          NEXT_DIST_DIR: "{prepareDir}/dist",
           NEXT_PUBLIC_API_URL: "{baseUrl:api}",
         },
       }),
@@ -127,6 +129,11 @@ export default defineTestkitSetup({
       envFiles: ["frontend/.env.testkit"],
       runtime: {
         instances: 1,
+        maxConcurrentTasks: 2,
+        prepare: {
+          inputs: ["frontend/src", "frontend/public", "frontend/package.json"],
+          steps: [commandStep("npm run build", { cwd: "frontend" })],
+        },
       },
     }),
     billing: service({
@@ -157,6 +164,7 @@ for:
 - multi-service graphs
 - local runtime instance counts
 - per-runtime concurrent task caps
+- one-time runtime preparation steps for stable shared servers
 - local DB binding configuration
 - template database migrate / seed / verify stages
 - template schema snapshot capture
@@ -167,6 +175,12 @@ for:
 - repo-declared suite/file skip policies with explicit reasons
 - telemetry upload configuration
 
+`runtime.prepare` is the generic build-once hook for shared runtimes. It runs
+once per runtime generation before local services start, fingerprints declared
+inputs, and writes cache state under the service runtime directory. This is the
+right way to move expensive browser targets from `next dev` / watch mode to
+stable build-and-start flows.
+
 If `reporting.knownFailuresFile` is configured, `testkit` enriches
 `.testkit/results/latest.json` and `testkit.status.json` with:
 

package/lib/config/index.mjs

@@ -279,6 +279,10 @@ function normalizeRuntimeConfig(value, serviceName) {
     return {
       instances: 1,
       maxConcurrentTasks: Number.POSITIVE_INFINITY,
+      prepare: {
+        inputs: [],
+        steps: [],
+      },
     };
   }
 
@@ -291,6 +295,27 @@ function normalizeRuntimeConfig(value, serviceName) {
       value.maxConcurrentTasks,
       `Service "${serviceName}" runtime.maxConcurrentTasks`
     ),
+    prepare: normalizeRuntimePrepareConfig(value.prepare, serviceName),
+  };
+}
+
+function normalizeRuntimePrepareConfig(value, serviceName) {
+  if (value == null) {
+    return {
+      inputs: [],
+      steps: [],
+    };
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`Service "${serviceName}" runtime.prepare must be an object`);
+  }
+
+  return {
+    inputs: normalizeTemplateInputs(value.inputs, `Service "${serviceName}" runtime.prepare`),
+    steps: normalizeTemplateLifecycleSteps(
+      value.steps,
+      `Service "${serviceName}" runtime.prepare.steps`
+    ),
   };
 }
 
@@ -751,6 +776,36 @@ function validateServiceConfig({
   for (const input of database?.template?.inputs || []) {
     ensureExistingPath(productDir, input, `Service "${name}" database.template input`);
   }
+  for (const step of runtime.prepare?.steps || []) {
+    if (step.cwd) {
+      ensureExistingPath(productDir, step.cwd, `Service "${name}" runtime.prepare step cwd`);
+    }
+    if (step.kind === "sql-file") {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        step.path,
+        `Service "${name}" runtime.prepare sql file`
+      );
+    }
+    if (step.kind === "module") {
+      const { modulePath } = parseModuleSpecifier(step.specifier);
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        modulePath,
+        `Service "${name}" runtime.prepare module`
+      );
+    }
+    for (const input of step.inputs || []) {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        input,
+        `Service "${name}" runtime.prepare step input`
+      );
+    }
+  }
+  for (const input of runtime.prepare?.inputs || []) {
+    ensureExistingPath(productDir, input, `Service "${name}" runtime.prepare input`);
+  }
 }
 
 function ensureExistingPath(productDir, relativePath, label) {

package/lib/database/template-steps.mjs

@@ -1,17 +1,11 @@
-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 { execa } from "execa";
 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");
+import {
+  collectConfiguredInputs,
+  runConfiguredSteps,
+} from "../runner/template-steps.mjs";
 
 export async function runTemplateStage(config, stageName, databaseUrl) {
   const steps = config.testkit.database?.template?.[stageName] || [];
@@ -22,32 +16,20 @@ export async function runTemplateStage(config, stageName, databaseUrl) {
     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);
-  }
+  await runConfiguredSteps({
+    config,
+    steps,
+    env,
+    labelPrefix: `template:${stageName}`,
+  });
 }
 
 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();
+  const steps = ["migrate", "seed", "verify"].flatMap((stageName) => template[stageName] || []);
+  return collectConfiguredInputs(productDir, {
+    inputs: template.inputs || [],
+    steps,
+  });
 }
 
 export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
@@ -55,21 +37,25 @@ export async function captureTemplateSnapshot(config, outputPath, 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",
-  });
+  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;
@@ -86,147 +72,3 @@ function sanitizeSnapshotFile(filePath) {
     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;
-  }
-}

package/lib/runner/runtime-contexts.mjs

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import { prepareDatabaseRuntime } from "../database/index.mjs";
 import { taskNeedsLocalRuntime } from "./planning.mjs";
+import { prepareRuntimeServices } from "./runtime-preparation.mjs";
 import { writeGraphMetadata } from "./state.mjs";
 import { startLocalServices, stopLocalServices } from "./services.mjs";
 import { resolveRuntimeInstanceConfigs } from "./template.mjs";
@@ -39,6 +40,7 @@ export async function ensureRuntimeInstanceReady(context, task, lifecycle) {
     if (!context.preparationPromise) {
       context.preparationPromise = (async () => {
         await prepareDatabases(context.runtimeConfigs);
+        await prepareRuntimeServices(context.runtimeConfigs);
         context.prepared = true;
       })().finally(() => {
         context.preparationPromise = null;

package/lib/runner/runtime-preparation.mjs

@@ -0,0 +1,107 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { resolveServiceCwd } from "../config/index.mjs";
+import { appendFileToHash, appendInputToHash } from "../database/fingerprint.mjs";
+import { readDatabaseUrl } from "./state-io.mjs";
+import { buildExecutionEnv } from "./template.mjs";
+import {
+  collectConfiguredInputs,
+  runConfiguredSteps,
+} from "./template-steps.mjs";
+
+const MANIFEST_FILE = "prepare-manifest.json";
+
+export async function prepareRuntimeServices(runtimeConfigs) {
+  for (const config of runtimeConfigs) {
+    await prepareRuntimeService(config);
+  }
+}
+
+export async function prepareRuntimeService(config) {
+  const prepare = config.testkit.runtime.prepare;
+  if (!prepare || prepare.steps.length === 0) return;
+
+  const prepareDir = config.testkit.prepareDir;
+  const fingerprint = await computeRuntimePrepareFingerprint(config);
+  const manifestPath = path.join(prepareDir, MANIFEST_FILE);
+  const existingManifest = readPrepareManifest(manifestPath);
+  if (existingManifest?.fingerprint === fingerprint) {
+    return;
+  }
+
+  fs.rmSync(prepareDir, { recursive: true, force: true });
+  fs.mkdirSync(prepareDir, { recursive: true });
+
+  const env = {
+    ...buildExecutionEnv(config, config.testkit.local?.env || {}, process.env),
+  };
+  const databaseUrl = readDatabaseUrl(config.stateDir);
+  if (databaseUrl) {
+    env.DATABASE_URL = databaseUrl;
+  }
+
+  try {
+    await runConfiguredSteps({
+      config,
+      steps: prepare.steps,
+      env,
+      labelPrefix: "runtime:prepare",
+    });
+    writePrepareManifest(manifestPath, {
+      fingerprint,
+      preparedAt: new Date().toISOString(),
+      runtimeId: config.runtimeId || null,
+      serviceName: config.name,
+    });
+  } catch (error) {
+    fs.rmSync(prepareDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function computeRuntimePrepareFingerprint(config) {
+  const hash = crypto.createHash("sha256");
+  hash.update(
+    JSON.stringify({
+      prepare: config.testkit.runtime.prepare || null,
+      serviceEnv: config.testkit.serviceEnv || {},
+      local: config.testkit.local
+        ? {
+            baseUrl: config.testkit.local.baseUrl,
+            cwd: config.testkit.local.cwd,
+            env: config.testkit.local.env || {},
+            readyUrl: config.testkit.local.readyUrl,
+            start: config.testkit.local.start,
+          }
+        : null,
+    })
+  );
+
+  for (const envFile of config.testkit.envFiles || []) {
+    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
+  }
+  for (const input of collectConfiguredInputs(config.productDir, config.testkit.runtime.prepare)) {
+    appendResolvedInputToHash(hash, config.productDir, input);
+  }
+
+  return hash.digest("hex");
+}
+
+function appendResolvedInputToHash(hash, productDir, absPath) {
+  const relative = path.relative(productDir, absPath);
+  appendInputToHash(hash, productDir, relative);
+}
+
+function readPrepareManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writePrepareManifest(manifestPath, manifest) {
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}

package/lib/runner/runtime-preparation.test.mjs

@@ -0,0 +1,141 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { prepareRuntimeService } from "./runtime-preparation.mjs";
+import { resolveRuntimeInstanceConfigs } from "./template.mjs";
+
+const tempDirs = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function writeFile(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents);
+}
+
+function makeResolvedRuntimeConfig(productDir, prepareConfig) {
+  const rawConfig = {
+    name: "api",
+    productDir,
+    testkit: {
+      envFiles: [],
+      serviceEnv: {},
+      runtime: {
+        instances: 1,
+        maxConcurrentTasks: 1,
+        prepare: prepareConfig,
+      },
+      local: {
+        cwd: ".",
+        start: "node {prepareDir}/server.mjs",
+        port: 3010,
+        baseUrl: "http://127.0.0.1:{port}",
+        readyUrl: "http://127.0.0.1:{port}/health",
+        env: {},
+      },
+    },
+  };
+
+  const runtimeDir = path.join(productDir, ".testkit", "_graphs", "api", "runtimes", "runtime-1");
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  return resolveRuntimeInstanceConfigs([rawConfig], "runtime-1", runtimeDir, {
+    graphDirName: "api",
+    portNamespaceIndex: 0,
+    portNamespaceStride: 1,
+  })[0];
+}
+
+describe("runtime preparation", () => {
+  it("runs prepare steps once and reuses the manifest until inputs change", async () => {
+    const productDir = makeTempDir("testkit-runtime-prepare-");
+    writeFile(path.join(productDir, "src", "message.txt"), "hello one\n");
+    writeFile(
+      path.join(productDir, "scripts", "prepare.mjs"),
+      [
+        'import fs from "fs";',
+        'import path from "path";',
+        'const prepareDir = process.argv[2];',
+        'const productDir = process.cwd();',
+        'const message = fs.readFileSync(path.join(productDir, "src", "message.txt"), "utf8").trim();',
+        'const counterDir = path.join(productDir, ".runtime", "prepared");',
+        'const counterFile = path.join(counterDir, "build-count.txt");',
+        'const current = fs.existsSync(counterFile) ? Number.parseInt(fs.readFileSync(counterFile, "utf8"), 10) || 0 : 0;',
+        'fs.mkdirSync(counterDir, { recursive: true });',
+        'fs.mkdirSync(prepareDir, { recursive: true });',
+        'fs.writeFileSync(counterFile, `${current + 1}\\n`);',
+        'fs.writeFileSync(path.join(prepareDir, "message.txt"), `${message}\\n`);',
+      ].join("\n")
+    );
+
+    const config = makeResolvedRuntimeConfig(productDir, {
+      inputs: ["src/message.txt"],
+      steps: [
+        {
+          kind: "command",
+          cmd: "node scripts/prepare.mjs {prepareDir}",
+        },
+      ],
+    });
+
+    await prepareRuntimeService(config);
+    expect(
+      fs.readFileSync(path.join(productDir, ".runtime", "prepared", "build-count.txt"), "utf8").trim()
+    ).toBe("1");
+    expect(fs.readFileSync(path.join(config.testkit.prepareDir, "message.txt"), "utf8").trim()).toBe(
+      "hello one"
+    );
+
+    await prepareRuntimeService(config);
+    expect(
+      fs.readFileSync(path.join(productDir, ".runtime", "prepared", "build-count.txt"), "utf8").trim()
+    ).toBe("1");
+
+    fs.writeFileSync(path.join(productDir, "src", "message.txt"), "hello two\n");
+    await prepareRuntimeService(config);
+    expect(
+      fs.readFileSync(path.join(productDir, ".runtime", "prepared", "build-count.txt"), "utf8").trim()
+    ).toBe("2");
+    expect(fs.readFileSync(path.join(config.testkit.prepareDir, "message.txt"), "utf8").trim()).toBe(
+      "hello two"
+    );
+  });
+
+  it("cleans incomplete prepared output when a prepare step fails", async () => {
+    const productDir = makeTempDir("testkit-runtime-prepare-fail-");
+    writeFile(
+      path.join(productDir, "scripts", "prepare-fail.mjs"),
+      [
+        'import fs from "fs";',
+        'import path from "path";',
+        'const prepareDir = process.argv[2];',
+        'fs.mkdirSync(prepareDir, { recursive: true });',
+        'fs.writeFileSync(path.join(prepareDir, "partial.txt"), "partial\\n");',
+        'throw new Error("prepare failed");',
+      ].join("\n")
+    );
+
+    const config = makeResolvedRuntimeConfig(productDir, {
+      steps: [
+        {
+          kind: "command",
+          cmd: "node scripts/prepare-fail.mjs {prepareDir}",
+        },
+      ],
+    });
+
+    await expect(prepareRuntimeService(config)).rejects.toThrow("Command failed with exit code 1");
+    expect(fs.existsSync(config.testkit.prepareDir)).toBe(false);
+    expect(fs.existsSync(path.join(productDir, ".testkit", "_graphs", "api", "runtimes", "runtime-1", "services", "api", "prepared", "prepare-manifest.json"))).toBe(false);
+  });
+});

package/lib/runner/template-steps.mjs

@@ -0,0 +1,191 @@
+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";
+
+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 runConfiguredSteps({ config, steps = [], env, labelPrefix }) {
+  if (steps.length === 0) return;
+
+  for (const [index, step] of steps.entries()) {
+    const label = `${labelPrefix}:${config.name}:${index + 1}`;
+    console.log(`\n── ${label} ──`);
+    await runConfiguredStep(config, step, env);
+  }
+}
+
+export function collectConfiguredInputs(productDir, { inputs = [], steps = [] } = {}) {
+  const collected = new Set();
+  for (const input of inputs) {
+    collected.add(resolveConfiguredPath(productDir, null, input));
+  }
+  for (const step of steps) {
+    if (step.kind === "sql-file") {
+      collected.add(resolveConfiguredPath(productDir, step.cwd, step.path));
+    }
+    if (step.kind === "module") {
+      collected.add(
+        resolveConfiguredPath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath)
+      );
+    }
+    for (const input of step.inputs || []) {
+      collected.add(resolveConfiguredPath(productDir, step.cwd, input));
+    }
+  }
+  return [...collected].sort();
+}
+
+export function resolveConfiguredCwd(productDir, stepCwd) {
+  return resolveServiceCwd(productDir, stepCwd || ".");
+}
+
+export function resolveConfiguredPath(productDir, stepCwd, targetPath) {
+  return path.resolve(resolveConfiguredCwd(productDir, stepCwd), targetPath);
+}
+
+async function runConfiguredStep(config, step, env) {
+  if (step.kind === "command") {
+    await execaCommand(step.cmd, {
+      cwd: resolveConfiguredCwd(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",
+        resolveConfiguredPath(config.productDir, step.cwd, step.path),
+      ],
+      {
+        cwd: resolveConfiguredCwd(config.productDir, step.cwd),
+        env,
+        stdio: "inherit",
+      }
+    );
+    return;
+  }
+
+  if (step.kind === "module") {
+    const moduleRef = await loadConfiguredModule(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(resolveConfiguredCwd(config.productDir, step.cwd), env, async () => {
+      await fn({
+        databaseUrl: env.DATABASE_URL || null,
+        productDir: config.productDir,
+        cwd: resolveConfiguredCwd(config.productDir, step.cwd),
+        serviceName: config.name,
+        env: { ...env },
+        runtimeId: config.runtimeId || null,
+        stateDir: config.stateDir,
+        prepareDir: config.testkit.prepareDir || null,
+      });
+    });
+    return;
+  }
+
+  throw new Error(`Unsupported template step kind "${step.kind}"`);
+}
+
+async function loadConfiguredModule(productDir, step) {
+  const { modulePath } = parseModuleSpecifier(step.specifier);
+  const absoluteModulePath = resolveConfiguredPath(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;
+  }
+}

package/lib/runner/template.mjs

@@ -113,12 +113,14 @@ export function resolveRuntimeConfig(
   urlMappings
 ) {
   const stateDir = resolveServiceStateDir(runtimeDir, config);
+  const prepareDir = resolveServicePrepareDir(runtimeDir, config);
   const context = {
     runtimeId,
     runtimeLabel,
     runtimeDir,
     serviceName: config.name,
     serviceStateDir: stateDir,
+    prepareDir,
     portMap,
     baseUrlByService,
     readyUrlByService,
@@ -135,6 +137,11 @@ export function resolveRuntimeConfig(
       }
     : undefined;
 
+  const runtime = {
+    ...config.testkit.runtime,
+    prepare: finalizeRuntimePrepare(config.testkit.runtime.prepare, context),
+  };
+
   const local = config.testkit.local
     ? {
         ...config.testkit.local,
@@ -158,7 +165,9 @@ export function resolveRuntimeConfig(
     testkit: {
       ...config.testkit,
       database,
+      prepareDir,
       templateContext: context,
+      runtime,
       local,
     },
   };
@@ -197,6 +206,10 @@ export function resolveServiceStateDir(runtimeDir, config) {
   return path.join(runtimeDir, "services", config.name);
 }
 
+export function resolveServicePrepareDir(runtimeDir, config) {
+  return path.join(resolveServiceStateDir(runtimeDir, config), "prepared");
+}
+
 export function buildExecutionEnv(config, extraEnv = {}, processEnv = process.env) {
   return buildExecutionEnvWithContext(config, null, extraEnv, processEnv);
 }
@@ -244,6 +257,7 @@ function buildTemplateContext(config, lease) {
     runtimeLabel: config.runtimeLabel || baseContext.runtimeLabel || null,
     serviceName: config.name,
     serviceStateDir: config.stateDir || baseContext.serviceStateDir || null,
+    prepareDir: config.testkit?.prepareDir || baseContext.prepareDir || null,
     leaseId: lease?.leaseId || null,
     leaseDir: lease?.leaseDir || null,
   };
@@ -280,6 +294,8 @@ export function resolveTemplateString(value, context) {
         return context.serviceName;
       case "stateDir":
         return context.serviceStateDir;
+      case "prepareDir":
+        return context.prepareDir || "";
       case "lease":
         return context.leaseId ? String(context.leaseId) : "";
       case "leaseDir":
@@ -332,6 +348,31 @@ function resolveEnvTemplates(values, templateContext) {
   );
 }
 
+function finalizeRuntimePrepare(prepare, context) {
+  if (!prepare) {
+    return {
+      inputs: [],
+      steps: [],
+    };
+  }
+
+  const finalizeStep = (step) => ({
+    ...step,
+    ...(typeof step.cmd === "string" ? { cmd: finalizeString(step.cmd, context) } : {}),
+    ...(typeof step.cwd === "string" ? { cwd: finalizeString(step.cwd, context) } : {}),
+    ...(typeof step.path === "string" ? { path: finalizeString(step.path, context) } : {}),
+    ...(typeof step.specifier === "string"
+      ? { specifier: finalizeString(step.specifier, context) }
+      : {}),
+    inputs: (step.inputs || []).map((input) => finalizeString(input, context)),
+  });
+
+  return {
+    inputs: (prepare.inputs || []).map((input) => finalizeString(input, context)),
+    steps: (prepare.steps || []).map(finalizeStep),
+  };
+}
+
 function resolveDatabaseTemplateValue(token, serviceName, context) {
   const stateDir = context.stateDirByService?.get(serviceName);
   if (!stateDir) {

package/lib/runner/template.test.mjs

@@ -22,8 +22,18 @@ function makeRuntimeConfig(name, local, extras = {}) {
     name,
     stateDir: extras.stateDir,
     runtimeId: extras.runtimeId,
+    productDir: extras.productDir || process.cwd(),
     testkit: {
       local,
+      runtime: extras.runtime || {
+        instances: 1,
+        maxConcurrentTasks: Infinity,
+        prepare: {
+          inputs: [],
+          steps: [],
+        },
+      },
+      envFiles: extras.envFiles || [],
       serviceEnv: extras.serviceEnv || {},
       databaseFrom: extras.databaseFrom,
       database: extras.database,
@@ -88,6 +98,9 @@ describe("runner-template", () => {
     expect(resolveTemplateString("{runtime}:{service}:{lease}", context)).toBe(
       "runtime-2:frontend:lease-1"
     );
+    expect(resolveTemplateString("{prepareDir}", { ...context, prepareDir: "/tmp/prepare-1" })).toBe(
+      "/tmp/prepare-1"
+    );
     expect(resolveTemplateString("{baseUrl:api}", context)).toBe("http://127.0.0.1:3100");
     expect(resolveTemplateString("{dbHost:api}:{dbPort:api}/{dbName:api}", context)).toBe(
       "127.0.0.1:55432/runtime_db"
@@ -140,6 +153,7 @@ describe("runner-template", () => {
     expect(resolved[0].testkit.local.port).toBe(3100);
     expect(resolved[0].runtimeLabel).toBe("api__frontend/runtime-2");
     expect(resolveServiceStateDir(runtimeDir, api)).toBe(`${runtimeDir}/services/api`);
+    expect(resolved[0].testkit.prepareDir).toBe(`${runtimeDir}/services/api/prepared`);
 
     fs.mkdirSync(path.join(runtimeDir, "services", "api"), { recursive: true });
     fs.writeFileSync(
@@ -197,6 +211,56 @@ describe("runner-template", () => {
     });
   });
 
+  it("finalizes runtime.prepare templates with prepareDir", () => {
+    const runtimeDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-runtime-prepare-"));
+    const api = makeRuntimeConfig(
+      "api",
+      {
+        cwd: ".",
+        start: "npm run api",
+        port: 3000,
+        baseUrl: "http://127.0.0.1:{port}",
+        readyUrl: "http://127.0.0.1:{port}/health",
+        env: {},
+      },
+      {
+        runtime: {
+          instances: 1,
+          maxConcurrentTasks: 2,
+          prepare: {
+            inputs: ["src/{service}.ts"],
+            steps: [
+              {
+                kind: "command",
+                cmd: "node scripts/prepare.mjs {prepareDir}",
+                cwd: ".",
+                inputs: ["src/{service}.ts"],
+              },
+            ],
+          },
+        },
+      }
+    );
+
+    const [resolved] = resolveRuntimeInstanceConfigs([api], "runtime-1", runtimeDir, {
+      graphDirName: "api",
+      portNamespaceIndex: 0,
+      portNamespaceStride: 1,
+    });
+
+    expect(resolved.testkit.runtime.prepare).toEqual({
+      inputs: ["src/api.ts"],
+      steps: [
+        {
+          kind: "command",
+          cmd: `node scripts/prepare.mjs ${runtimeDir}/services/api/prepared`,
+          cwd: ".",
+          inputs: ["src/api.ts"],
+        },
+      ],
+    });
+  });
+
   it("parses runtime sockets", () => {
     expect(numericPortFromUrl("http://localhost:3000")).toBe(3000);
     expect(socketFromUrl("http://localhost:3000")).toEqual({

package/lib/setup/index.d.ts

@@ -58,6 +58,10 @@ export interface SkipConfig {
 export interface RuntimeConfig {
   instances?: number;
   maxConcurrentTasks?: number;
+  prepare?: {
+    inputs?: string[];
+    steps?: TemplateLifecycleStepConfig[];
+  };
 }
 
 export interface SuiteRequirementRule {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",