@elench/testkit 0.1.50 → 0.1.52

package/README.md

@@ -65,11 +65,14 @@ import {
   commandStep,
   defineTestkitSetup,
   localDatabase,
-  moduleStep,
   nextService,
+  nodeToolchain,
+  schemaSql,
+  seedCommand,
+  seededDatabaseTemplate,
   service,
-  sqlFileStep,
   tsxService,
+  verifyModule,
 } from "@elench/testkit/setup";
 
 export default defineTestkitSetup({
@@ -85,6 +88,13 @@ export default defineTestkitSetup({
       cacheTtlSeconds: 900,
     },
   },
+  toolchains: {
+    frontendNode: nodeToolchain({
+      cwd: "frontend",
+      detect: "auto",
+      install: "download",
+    }),
+  },
   services: {
     api: service({
       ...tsxService({
@@ -95,12 +105,12 @@ export default defineTestkitSetup({
       }),
       envFiles: [".env.testkit"],
       database: localDatabase({
-        template: {
+        template: seededDatabaseTemplate({
           inputs: ["db/schema.sql", "scripts/seed.ts"],
-          migrate: [sqlFileStep("db/schema.sql")],
-          seed: [commandStep("npm run db:seed")],
-          verify: [moduleStep("src/testkit/verify-seed.ts#verifySeed")],
-        },
+          schema: schemaSql("db/schema.sql"),
+          seed: seedCommand("npm run db:seed"),
+          verify: verifyModule("src/testkit/verify-seed.ts#verifySeed"),
+        }),
       }),
       runtime: {
         instances: 1,
@@ -130,6 +140,7 @@ export default defineTestkitSetup({
       runtime: {
         instances: 1,
         maxConcurrentTasks: 2,
+        toolchain: "frontendNode",
         prepare: {
           inputs: ["frontend/src", "frontend/public", "frontend/package.json"],
           steps: [commandStep("npm run build", { cwd: "frontend" })],
@@ -164,6 +175,7 @@ for:
 - multi-service graphs
 - local runtime instance counts
 - per-runtime concurrent task caps
+- repo-managed Node toolchains for prepare/start commands
 - one-time runtime preparation steps for stable shared servers
 - local DB binding configuration
 - template database migrate / seed / verify stages
@@ -181,6 +193,60 @@ 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.
 
+`database.template` is the database-side equivalent for reusable template DB
+state. It always executes in three explicit phases:
+
+- `migrate`
+- `seed`
+- `verify`
+
+For most repos, prefer the intent-focused helpers:
+
+- `schemaSql(...)`
+- `seedCommand(...)`
+- `seedModule(...)`
+- `verifyCommand(...)`
+- `verifyModule(...)`
+- `seededDatabaseTemplate(...)`
+
+Use raw `commandStep(...)`, `sqlFileStep(...)`, and `moduleStep(...)` arrays when
+you need lower-level control over the exact stage layout.
+
+`runtime.toolchain` is the first-class way to make those prepare/start commands
+run under the correct Node toolchain instead of whatever `node`/`npm` happened
+to launch `testkit`. Node toolchains support:
+
+- host verification mode: `install: "require-host"`
+- cached repo-local provisioning mode: `install: "download"`
+- auto-detection from:
+  - `package.json#volta.node`
+  - `.nvmrc`
+  - `.node-version`
+  - `.tool-versions` (`nodejs`)
+  - `package.json#engines.node`
+  - `package.json#volta.npm`
+  - `package.json#packageManager`
+  - `package.json#engines.npm`
+
+Example:
+
+```ts
+toolchains: {
+  frontendNode: nodeToolchain({
+    cwd: "frontend",
+    detect: "auto",
+    install: "download",
+  }),
+},
+services: {
+  frontend: service({
+    runtime: {
+      toolchain: "frontendNode",
+    },
+  }),
+}
+```
+
 If `reporting.knownFailuresFile` is configured, `testkit` enriches
 `.testkit/results/latest.json` and `testkit.status.json` with:
 

package/lib/config/index.mjs

@@ -16,6 +16,10 @@ import {
   normalizeRuntimeInstances,
 } from "../runner/execution-config.mjs";
 import { normalizeKnownFailureIssueValidationConfig } from "../known-failures/github.mjs";
+import {
+  normalizeRuntimeToolchain,
+  normalizeToolchainRegistry,
+} from "../toolchains/index.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -32,6 +36,7 @@ export async function loadConfigs(opts = {}) {
   const { setup, setupFile } = await loadTestkitSetup(productDir);
   const execution = normalizeRepoExecution(setup.execution);
   const reporting = normalizeReportingConfig(setup.reporting);
+  const toolchains = normalizeToolchainRegistry(setup.toolchains);
   const explicitServices = setup.services || {};
   const discovery = discoverProject(productDir, explicitServices);
   const serviceNames = new Set([
@@ -49,6 +54,7 @@ export async function loadConfigs(opts = {}) {
         setupFile,
         execution,
         reporting,
+        toolchains,
         explicitService: explicitServices[name] || {},
         discoveredService: discovery.services[name] || null,
         suites: discovery.suitesByService[name] || {},
@@ -109,6 +115,7 @@ function normalizeServiceConfig({
   setupFile,
   execution,
   reporting,
+  toolchains,
   explicitService,
   discoveredService,
   suites,
@@ -125,7 +132,7 @@ function normalizeServiceConfig({
     );
   }
   const database = normalizeDatabaseConfig(explicitService, name);
-  const runtime = normalizeRuntimeConfig(explicitService.runtime, name);
+  const runtime = normalizeRuntimeConfig(explicitService.runtime, name, toolchains);
   const skip = normalizeSkipConfig(explicitService.skip, {
     name,
     productDir,
@@ -274,7 +281,7 @@ function normalizeDatabaseConfig(explicitService, serviceName) {
   };
 }
 
-function normalizeRuntimeConfig(value, serviceName) {
+function normalizeRuntimeConfig(value, serviceName, toolchains) {
   if (!value) {
     return {
       instances: 1,
@@ -283,6 +290,7 @@ function normalizeRuntimeConfig(value, serviceName) {
         inputs: [],
         steps: [],
       },
+      toolchain: null,
     };
   }
 
@@ -296,6 +304,11 @@ function normalizeRuntimeConfig(value, serviceName) {
       `Service "${serviceName}" runtime.maxConcurrentTasks`
     ),
     prepare: normalizeRuntimePrepareConfig(value.prepare, serviceName),
+    toolchain: normalizeRuntimeToolchain(
+      value.toolchain,
+      `Service "${serviceName}" runtime.toolchain`,
+      toolchains || {}
+    ),
   };
 }
 
@@ -739,6 +752,9 @@ function validateServiceConfig({
   if (local?.cwd) {
     ensureExistingPath(productDir, local.cwd, `Service "${name}" local.cwd`);
   }
+  if (runtime.toolchain?.cwd) {
+    ensureExistingPath(productDir, runtime.toolchain.cwd, `Service "${name}" runtime.toolchain.cwd`);
+  }
   for (const [stageName, steps] of Object.entries(database?.template || {})) {
     if (stageName === "inputs") continue;
     for (const step of steps || []) {

package/lib/runner/runtime-preparation.mjs

@@ -3,6 +3,7 @@ import fs from "fs";
 import path from "path";
 import { resolveServiceCwd } from "../config/index.mjs";
 import { appendFileToHash, appendInputToHash } from "../database/fingerprint.mjs";
+import { announceResolvedToolchain, resolveConfiguredToolchain } from "../toolchains/index.mjs";
 import { readDatabaseUrl } from "./state-io.mjs";
 import { buildExecutionEnv } from "./template.mjs";
 import {
@@ -42,6 +43,7 @@ export async function prepareRuntimeService(config) {
   }
 
   try {
+    await announceResolvedToolchain(config, await resolveConfiguredToolchain(config));
     await runConfiguredSteps({
       config,
       steps: prepare.steps,
@@ -61,10 +63,22 @@ export async function prepareRuntimeService(config) {
 }
 
 export async function computeRuntimePrepareFingerprint(config) {
+  const resolvedToolchain = await resolveConfiguredToolchain(config);
   const hash = crypto.createHash("sha256");
   hash.update(
     JSON.stringify({
       prepare: config.testkit.runtime.prepare || null,
+      toolchain: resolvedToolchain
+        ? {
+            kind: resolvedToolchain.kind,
+            install: resolvedToolchain.install,
+            nodeVersion: resolvedToolchain.nodeVersion,
+            npmVersion: resolvedToolchain.npmVersion,
+            nodeSource: resolvedToolchain.nodeSource,
+            npmSource: resolvedToolchain.npmSource,
+            fingerprint: resolvedToolchain.fingerprint,
+          }
+        : null,
       serviceEnv: config.testkit.serviceEnv || {},
       local: config.testkit.local
         ? {

package/lib/runner/services.mjs

@@ -1,4 +1,9 @@
 import { resolveServiceCwd } from "../config/index.mjs";
+import {
+  announceResolvedToolchain,
+  applyToolchainEnv,
+  resolveConfiguredToolchain,
+} from "../toolchains/index.mjs";
 import { buildExecutionEnv, numericPortFromUrl } from "./template.mjs";
 import { DEFAULT_READY_TIMEOUT_MS, assertLocalServicePortsAvailable, isPortInUse, waitForReady } from "./readiness.mjs";
 import { killChildProcess, pipeOutput, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
@@ -23,7 +28,12 @@ export async function startLocalServices(runtimeConfigs, lifecycle) {
 
 export async function startLocalService(config, lifecycle) {
   const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
-  const env = buildExecutionEnv(config, config.testkit.local.env, process.env);
+  const resolvedToolchain = await resolveConfiguredToolchain(config);
+  await announceResolvedToolchain(config, resolvedToolchain);
+  const env = applyToolchainEnv(
+    buildExecutionEnv(config, config.testkit.local.env, process.env),
+    resolvedToolchain
+  );
   const port = config.testkit.local.port || numericPortFromUrl(config.testkit.local.baseUrl);
   if (port) {
     env.PORT = String(port);

package/lib/runner/template-step-module-runner.mjs

@@ -0,0 +1,25 @@
+import fs from "fs";
+import { pathToFileURL } from "url";
+
+const [, , moduleFile, exportName, contextFile] = process.argv;
+
+if (!moduleFile || !exportName || !contextFile) {
+  console.error("Usage: node template-step-module-runner.mjs <module-file> <export-name> <context-file>");
+  process.exit(1);
+}
+
+try {
+  const context = JSON.parse(fs.readFileSync(contextFile, "utf8"));
+  const moduleRef = await import(pathToFileURL(moduleFile).href);
+  const fn = moduleRef[exportName];
+  if (typeof fn !== "function") {
+    throw new Error(
+      `Template module step "${moduleFile}#${exportName}" did not export a function named "${exportName}"`
+    );
+  }
+
+  await fn(context);
+} catch (error) {
+  console.error(error?.stack || error?.message || String(error));
+  process.exit(1);
+}

package/lib/runner/template-steps.mjs

@@ -3,22 +3,35 @@ import fs from "fs";
 import path from "path";
 import { build } from "esbuild";
 import { execa, execaCommand } from "execa";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath } from "url";
 import { resolveServiceCwd } from "../config/index.mjs";
+import {
+  announceResolvedToolchain,
+  applyToolchainEnv,
+  resolveConfiguredToolchain,
+} from "../toolchains/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");
+const MODULE_RUNNER_ENTRY = path.join(
+  PACKAGE_ROOT,
+  "lib",
+  "runner",
+  "template-step-module-runner.mjs"
+);
 
 export async function runConfiguredSteps({ config, steps = [], env, labelPrefix }) {
   if (steps.length === 0) return;
+  const resolvedToolchain = await resolveConfiguredToolchain(config);
+  await announceResolvedToolchain(config, resolvedToolchain);
 
   for (const [index, step] of steps.entries()) {
     const label = `${labelPrefix}:${config.name}:${index + 1}`;
     console.log(`\n── ${label} ──`);
-    await runConfiguredStep(config, step, env);
+    await runConfiguredStep(config, step, env, resolvedToolchain);
   }
 }
 
@@ -51,11 +64,14 @@ export function resolveConfiguredPath(productDir, stepCwd, targetPath) {
   return path.resolve(resolveConfiguredCwd(productDir, stepCwd), targetPath);
 }
 
-async function runConfiguredStep(config, step, env) {
+async function runConfiguredStep(config, step, env, resolvedToolchain) {
+  const runtimeEnv = applyToolchainEnv(env, resolvedToolchain);
+  const cwd = resolveConfiguredCwd(config.productDir, step.cwd);
+
   if (step.kind === "command") {
     await execaCommand(step.cmd, {
-      cwd: resolveConfiguredCwd(config.productDir, step.cwd),
-      env,
+      cwd,
+      env: runtimeEnv,
       stdio: "inherit",
       shell: true,
     });
@@ -66,7 +82,7 @@ async function runConfiguredStep(config, step, env) {
     await execa(
       "psql",
       [
-        env.DATABASE_URL,
+        runtimeEnv.DATABASE_URL,
         "-v",
         "ON_ERROR_STOP=1",
         "-X",
@@ -74,8 +90,8 @@ async function runConfiguredStep(config, step, env) {
         resolveConfiguredPath(config.productDir, step.cwd, step.path),
       ],
       {
-        cwd: resolveConfiguredCwd(config.productDir, step.cwd),
-        env,
+        cwd,
+        env: runtimeEnv,
         stdio: "inherit",
       }
     );
@@ -83,34 +99,41 @@ async function runConfiguredStep(config, step, env) {
   }
 
   if (step.kind === "module") {
-    const moduleRef = await loadConfiguredModule(config.productDir, step);
+    const bundledModule = await bundleConfiguredModule(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}"`
+    const context = {
+      databaseUrl: runtimeEnv.DATABASE_URL || null,
+      productDir: config.productDir,
+      cwd,
+      serviceName: config.name,
+      env: { ...runtimeEnv },
+      runtimeId: config.runtimeId || null,
+      stateDir: config.stateDir,
+      prepareDir: config.testkit.prepareDir || null,
+    };
+    const contextPath = `${bundledModule.outputFile}.context.json`;
+    fs.writeFileSync(contextPath, JSON.stringify(context));
+
+    try {
+      await execa(
+        resolvedToolchain?.nodeExecutable || process.execPath,
+        [MODULE_RUNNER_ENTRY, bundledModule.outputFile, exportName, contextPath],
+        {
+          cwd,
+          env: runtimeEnv,
+          stdio: "inherit",
+        }
       );
+    } finally {
+      fs.rmSync(contextPath, { force: true });
     }
-
-    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) {
+async function bundleConfiguredModule(productDir, step) {
   const { modulePath } = parseModuleSpecifier(step.specifier);
   const absoluteModulePath = resolveConfiguredPath(productDir, step.cwd, modulePath);
   const bundleDir = path.join(productDir, ".testkit", "_template-steps");
@@ -135,7 +158,10 @@ async function loadConfiguredModule(productDir, step) {
     plugins: [testkitAliasPlugin()],
   });
 
-  return import(`${pathToFileURL(outputFile).href}?v=${cacheKey}`);
+  return {
+    outputFile,
+    cacheKey,
+  };
 }
 
 function buildModuleCacheKey(modulePath) {
@@ -172,20 +198,3 @@ function parseModuleSpecifier(specifier) {
     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/setup/index.d.ts

@@ -1,18 +1,18 @@
 import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
 
-export interface LocalDatabaseConfig {
-  provider: "local";
-  binding?: "shared" | "per-runtime";
-  image?: string;
-  password?: string;
-  reset?: boolean;
-  template?: {
-    inputs?: string[];
-    migrate?: TemplateLifecycleStepConfig[];
-    seed?: TemplateLifecycleStepConfig[];
-    verify?: TemplateLifecycleStepConfig[];
-  };
-  user?: string;
+export interface DatabaseTemplateConfig {
+  inputs?: string[];
+  migrate?: TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig[];
+}
+
+export interface SeededDatabaseTemplateOptions {
+  inputs?: string[];
+  schema?: string | TemplateSqlFileStepConfig;
+  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
 }
 
 export interface TemplateStepBaseConfig {
@@ -40,6 +40,16 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface LocalDatabaseConfig {
+  provider: "local";
+  binding?: "shared" | "per-runtime";
+  image?: string;
+  password?: string;
+  reset?: boolean;
+  template?: DatabaseTemplateConfig;
+  user?: string;
+}
+
 export interface SkipFileRule {
   path: string;
   reason: string;
@@ -62,8 +72,20 @@ export interface RuntimeConfig {
     inputs?: string[];
     steps?: TemplateLifecycleStepConfig[];
   };
+  toolchain?: string | NodeToolchainConfig;
 }
 
+export interface NodeToolchainConfig {
+  kind?: "node";
+  cwd?: string;
+  detect?: "auto" | "off";
+  install?: "require-host" | "download";
+  node?: string;
+  npm?: string;
+}
+
+export type ToolchainConfig = NodeToolchainConfig;
+
 export interface SuiteRequirementRule {
   selector: string;
   locks?: string[];
@@ -124,6 +146,7 @@ export interface TestkitSetup {
     issueValidation?: KnownFailureIssueValidationConfig;
   };
   services?: Record<string, ServiceConfig>;
+  toolchains?: Record<string, ToolchainConfig>;
   telemetry?: {
     enabled?: boolean;
     endpoint?: string;
@@ -148,6 +171,30 @@ export declare function moduleStep(
   specifier: string,
   options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
 ): TemplateModuleStepConfig;
+export declare function schemaSql(
+  filePath: string,
+  options?: Omit<TemplateSqlFileStepConfig, "kind" | "path">
+): TemplateSqlFileStepConfig;
+export declare function seedCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function seedModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function verifyCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function verifyModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function seededDatabaseTemplate(
+  options?: SeededDatabaseTemplateOptions
+): DatabaseTemplateConfig;
+export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
 export declare function goService(options: ServiceConfig["local"] & {
   command?: string;
   entrypoint?: string;

package/lib/setup/index.mjs

@@ -56,6 +56,47 @@ export function moduleStep(specifier, options = {}) {
   };
 }
 
+export function schemaSql(filePath, options = {}) {
+  return sqlFileStep(filePath, options);
+}
+
+export function seedCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function seedModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function verifyCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function verifyModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function seededDatabaseTemplate(options = {}) {
+  const migrate = normalizeTemplateStepList(options.migrate);
+  const seed = normalizeTemplateStepList(options.seed);
+  const verify = normalizeTemplateStepList(options.verify);
+  const schema = normalizeSchemaStep(options.schema);
+
+  return {
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+    migrate: schema ? [schema, ...migrate] : migrate,
+    seed,
+    verify,
+  };
+}
+
+export function nodeToolchain(options = {}) {
+  return {
+    kind: "node",
+    ...options,
+  };
+}
+
 export function goService(options = {}) {
   const cwd = options.cwd || ".";
   const port = requiredNumber(options.port, "goService port");
@@ -211,6 +252,19 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function normalizeTemplateStepList(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? [...value] : [value];
+}
+
+function normalizeSchemaStep(value) {
+  if (value == null) return null;
+  if (typeof value === "string") {
+    return sqlFileStep(value);
+  }
+  return value;
+}
+
 function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];