@elench/testkit 0.1.50 → 0.1.51

package/README.md

@@ -67,6 +67,7 @@ import {
   localDatabase,
   moduleStep,
   nextService,
+  nodeToolchain,
   service,
   sqlFileStep,
   tsxService,
@@ -85,6 +86,13 @@ export default defineTestkitSetup({
       cacheTtlSeconds: 900,
     },
   },
+  toolchains: {
+    frontendNode: nodeToolchain({
+      cwd: "frontend",
+      detect: "auto",
+      install: "download",
+    }),
+  },
   services: {
     api: service({
       ...tsxService({
@@ -130,6 +138,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 +173,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 +191,41 @@ 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.
 
+`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

@@ -62,8 +62,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 +136,7 @@ export interface TestkitSetup {
     issueValidation?: KnownFailureIssueValidationConfig;
   };
   services?: Record<string, ServiceConfig>;
+  toolchains?: Record<string, ToolchainConfig>;
   telemetry?: {
     enabled?: boolean;
     endpoint?: string;
@@ -148,6 +161,7 @@ export declare function moduleStep(
   specifier: string,
   options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
 ): TemplateModuleStepConfig;
+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,13 @@ export function moduleStep(specifier, options = {}) {
   };
 }
 
+export function nodeToolchain(options = {}) {
+  return {
+    kind: "node",
+    ...options,
+  };
+}
+
 export function goService(options = {}) {
   const cwd = options.cwd || ".";
   const port = requiredNumber(options.port, "goService port");

package/lib/setup/index.test.mjs

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { goService, nextService, tsxService } from "./index.mjs";
+import { goService, nextService, nodeToolchain, tsxService } from "./index.mjs";
 
 describe("setup helpers", () => {
   it("emits plain next start commands without an exec prefix", () => {
@@ -23,4 +23,12 @@ describe("setup helpers", () => {
       "go run ./cmd/worker"
     );
   });
+
+  it("builds node toolchain profiles with a node kind", () => {
+    expect(nodeToolchain({ node: "20.19.5", install: "download" })).toEqual({
+      kind: "node",
+      node: "20.19.5",
+      install: "download",
+    });
+  });
 });