@elench/testkit 0.1.75 → 0.1.77

package/README.md

@@ -147,14 +147,11 @@ Create `testkit.config.ts` at repo root:
 
 ```ts
 import {
+  app,
+  database,
   defineConfig,
   defineFile,
-  nextApp,
-  nodeToolchain,
-  nodeApp,
-  seedCommand,
-  templateDatabase,
-  verifyModule,
+  toolchain,
 } from "@elench/testkit/config";
 
 export default defineConfig({
@@ -171,38 +168,41 @@ export default defineConfig({
     },
   },
   toolchains: {
-    frontendNode: nodeToolchain({
+    frontendNode: toolchain.node({
       cwd: "frontend",
       detect: "auto",
       install: "download",
     }),
   },
   services: {
-    api: nodeApp({
+    api: app.node({
       cwd: ".",
       entry: "src/index.ts",
       port: 3004,
       envFiles: [".env.testkit"],
-      database: templateDatabase({
-        inputs: ["db/schema.sql", "scripts/seed.ts"],
-        schema: "db/schema.sql",
-        seed: seedCommand("npm run db:seed"),
-        verify: verifyModule("src/testkit/verify-seed.ts#verifySeed"),
+      database: database.postgres({
+        template: {
+          inputs: ["db/schema.sql", "scripts/seed.ts"],
+          schema: "db/schema.sql",
+          seed: [{ kind: "command", run: "npm run db:seed" }],
+          verify: [{ kind: "module", target: "src/testkit/verify-seed.ts#verifySeed" }],
+        },
       }),
       runtime: {
         instances: 1,
         maxConcurrentTasks: 4,
       },
     }),
-    frontend: nextApp({
+    frontend: app.next({
       cwd: "frontend",
       mode: "start",
       port: 3000,
       dependsOn: ["api"],
       envFiles: ["frontend/.env.testkit"],
       env: {
-        NEXT_DIST_DIR: "{prepareDir}/dist",
-        NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        values: {
+          NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        },
       },
       runtime: {
         instances: 1,
@@ -258,17 +258,13 @@ state. It always executes in three explicit phases:
 - `seed`
 - `verify`
 
-For most repos, prefer the intent-focused helpers:
+For most repos, prefer declarative step objects directly inside
+`database.postgres({ template: ... })` and `runtime.prepare.steps`.
+The supported shapes are:
 
-- `schemaSql(...)`
-- `seedCommand(...)`
-- `seedModule(...)`
-- `verifyCommand(...)`
-- `verifyModule(...)`
-- `templateDatabase(...)`
-
-Use raw `commandStep(...)`, `sqlFileStep(...)`, and `moduleStep(...)` arrays when
-you need lower-level control over the exact stage layout.
+- `{ kind: "command", run: "..." }`
+- `{ kind: "sql-file", path: "..." }`
+- `{ kind: "module", target: "file.ts#exportName" }`
 
 `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
@@ -290,14 +286,14 @@ Example:
 
 ```ts
 toolchains: {
-  frontendNode: nodeToolchain({
+  frontendNode: toolchain.node({
     cwd: "frontend",
     detect: "auto",
     install: "download",
   }),
 },
 services: {
-  frontend: nextApp({
+  frontend: app.next({
     cwd: "frontend",
     port: 3000,
     runtime: {
@@ -508,7 +504,7 @@ Git metadata.
 ## Local Databases
 
 `@elench/testkit` provisions Docker-managed local Postgres automatically for
-services that define `database: postgresDatabase(...)` or `database: templateDatabase(...)`.
+services that define `database: database.postgres(...)`.
 
 - template databases are cached
 - runtime databases are cloned from templates when binding is `per-runtime`

package/lib/config/runtime.test.mjs

@@ -19,7 +19,7 @@ describe("config runtime helpers", () => {
       normalizeRuntimePrepareConfig(
         {
           inputs: ["fixtures/users.json"],
-          steps: [{ kind: "module", specifier: "./scripts/setup.mjs#run", inputs: ["fixtures/users.json"] }],
+          steps: [{ kind: "module", target: "./scripts/setup.mjs#run", inputs: ["fixtures/users.json"] }],
         },
         "web"
       )
@@ -73,7 +73,7 @@ describe("config runtime helpers", () => {
 
   it("rejects malformed lifecycle steps and empty step inputs", () => {
     expect(() => normalizeTemplateLifecycleStep({ kind: "module" }, "runtime.prepare.steps[0]")).toThrow(
-      /specifier must be a non-empty string/
+      /target must be a non-empty string/
     );
     expect(() => normalizeTemplateStepInputs([""], "runtime.prepare.steps[0]")).toThrow(
       /must be a non-empty string/

package/lib/config-api/index.d.ts

@@ -22,7 +22,7 @@ export interface TemplateStepBaseConfig {
 
 export interface TemplateCommandStepConfig extends TemplateStepBaseConfig {
   kind: "command";
-  cmd: string;
+  run: string;
 }
 
 export interface TemplateSqlFileStepConfig extends TemplateStepBaseConfig {
@@ -32,7 +32,7 @@ export interface TemplateSqlFileStepConfig extends TemplateStepBaseConfig {
 
 export interface TemplateModuleStepConfig extends TemplateStepBaseConfig {
   kind: "module";
-  specifier: string;
+  target: string;
 }
 
 export type TemplateLifecycleStepConfig =
@@ -177,18 +177,28 @@ export interface ServiceConfig {
   skip?: SkipConfig;
 }
 
+export interface DatabaseBindingEnvConfig {
+  prefix: string;
+  service: string;
+}
+
+export interface PresetEnvConfig {
+  values?: Record<string, string>;
+  databases?: Record<string, DatabaseBindingEnvConfig>;
+}
+
 export interface TestkitFileMetadata {
   locks?: string[];
   skip?: string | { reason: string };
 }
 
-export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
   cwd?: string;
   entry?: string;
-  env?: Record<string, string>;
+  env?: PresetEnvConfig;
   outDir?: string;
   port: number;
   readyPath?: string;
@@ -200,12 +210,12 @@ export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime">
   tsconfig?: string;
 }
 
-export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
   cwd?: string;
-  env?: Record<string, string>;
+  env?: PresetEnvConfig;
   mode?: "dev" | "start";
   port: number;
   readyTimeoutMs?: number;
@@ -238,62 +248,27 @@ export interface TestkitConfig {
 export declare function defineConfig<T extends TestkitConfig>(config: T): T;
 export declare function defineHttpProfile<T extends HttpSuiteConfig>(profile: T): T;
 export declare function defineFile<T extends TestkitFileMetadata>(metadata: T): T;
-export declare function postgresDatabase(options?: Omit<LocalDatabaseConfig, "provider">): LocalDatabaseConfig;
-export declare function commandStep(
-  cmd: string,
-  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
-): TemplateCommandStepConfig;
-export declare function sqlFileStep(
-  filePath: string,
-  options?: Omit<TemplateSqlFileStepConfig, "kind" | "path">
-): TemplateSqlFileStepConfig;
-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 templateDatabase(
-  options?: DatabaseTemplateOptions & Omit<LocalDatabaseConfig, "provider" | "template">
-): LocalDatabaseConfig;
-export declare function postgresFixture(
-  options?: Omit<LocalDatabaseConfig, "provider"> & {
-    discovery?: DiscoveryConfig;
-    envFiles?: string[];
-  }
-): ServiceConfig;
-export declare function databaseServiceEnv(
-  prefix: string,
-  serviceName: string
-): Record<string, string>;
-export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
-export declare function tscBuild(options?: Omit<TscBuildConfig, "kind">): TscBuildConfig;
-export declare function scriptBuild(
-  script: string,
-  options?: Omit<ScriptBuildConfig, "kind" | "script">
-): ScriptBuildConfig;
-export declare function stepsBuild(options?: Omit<StepsBuildConfig, "kind">): StepsBuildConfig;
-export declare function nextBuild(options?: Omit<NextBuildConfig, "kind">): NextBuildConfig;
-export declare function nodeApp(options: NodeAppOptions): ServiceConfig;
-export declare function nextApp(options: NextAppOptions): ServiceConfig;
+export declare const app: {
+  node(options: NodeAppOptions): ServiceConfig;
+  next(options: NextAppOptions): ServiceConfig;
+};
+export declare const database: {
+  postgres(
+    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      template?: DatabaseTemplateOptions;
+    }
+  ): LocalDatabaseConfig;
+  fixture(
+    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      template?: DatabaseTemplateOptions;
+      discovery?: DiscoveryConfig;
+      envFiles?: string[];
+    }
+  ): ServiceConfig;
+};
+export declare const toolchain: {
+  node(options?: NodeToolchainConfig): NodeToolchainConfig;
+};
 export declare function clerkSessionProfile(options?: {
   apiBase?: string;
   needsAuth?: boolean;

package/lib/config-api/index.mjs

@@ -22,60 +22,13 @@ export function defineFile(metadata) {
   return metadata || {};
 }
 
-export function postgresDatabase(options = {}) {
+function postgresDatabase(options = {}) {
   return {
     provider: "local",
     ...options,
   };
 }
 
-export function commandStep(cmd, options = {}) {
-  return {
-    kind: "command",
-    cmd,
-    cwd: options.cwd,
-    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
-  };
-}
-
-export function sqlFileStep(filePath, options = {}) {
-  return {
-    kind: "sql-file",
-    path: filePath,
-    cwd: options.cwd,
-    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
-  };
-}
-
-export function moduleStep(specifier, options = {}) {
-  return {
-    kind: "module",
-    specifier,
-    cwd: options.cwd,
-    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
-  };
-}
-
-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);
-}
-
 function buildDatabaseTemplateConfig(options = {}) {
   const migrate = normalizeTemplateStepList(options.migrate);
   const seed = normalizeTemplateStepList(options.seed);
@@ -90,60 +43,40 @@ function buildDatabaseTemplateConfig(options = {}) {
   };
 }
 
-export function templateDatabase(options = {}) {
-  const {
-    inputs,
-    schema,
-    migrate,
-    seed,
-    verify,
-    ...databaseOptions
-  } = options;
-  return postgresDatabase({
-    ...databaseOptions,
-    template: buildDatabaseTemplateConfig(options.template || { inputs, schema, migrate, seed, verify }),
-  });
-}
-
-export function postgresFixture(options = {}) {
-  const { discovery, envFiles, ...databaseOptions } = options;
+function postgresFixture(options = {}) {
+  const { discovery, envFiles, template, ...databaseOptions } = options;
+  for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
+    if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
+      throw new Error(
+        `database.fixture(...) no longer accepts top-level "${legacyKey}". Move lifecycle config under database.fixture({ template: { ... } }).`
+      );
+    }
+  }
   return {
     discovery: discovery || {
       roots: [".testkit-fixture"],
     },
     envFiles,
     local: false,
-    database: postgresDatabase(databaseOptions),
-  };
-}
-
-export function databaseServiceEnv(prefix, serviceName) {
-  const normalizedPrefix = String(prefix || "").trim().replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  if (!normalizedPrefix) {
-    throw new Error("databaseServiceEnv prefix must be a non-empty string");
-  }
-  if (!serviceName || !String(serviceName).trim()) {
-    throw new Error("databaseServiceEnv serviceName must be a non-empty string");
-  }
-
-  return {
-    [`${normalizedPrefix}_DATABASE_HOST`]: `{dbHost:${serviceName}}`,
-    [`${normalizedPrefix}_DATABASE_PORT`]: `{dbPort:${serviceName}}`,
-    [`${normalizedPrefix}_DATABASE_NAME`]: `{dbName:${serviceName}}`,
-    [`${normalizedPrefix}_DATABASE_USER`]: `{dbUser:${serviceName}}`,
-    [`${normalizedPrefix}_DATABASE_PASSWORD`]: `{dbPassword:${serviceName}}`,
-    [`${normalizedPrefix}_DATABASE_SSL`]: "0",
+    database: postgresDatabase(
+      template
+        ? {
+            ...databaseOptions,
+            template: buildDatabaseTemplateConfig(template),
+          }
+        : databaseOptions
+    ),
   };
 }
 
-export function nodeToolchain(options = {}) {
+function nodeToolchain(options = {}) {
   return {
     kind: "node",
     ...options,
   };
 }
 
-export function tscBuild(options = {}) {
+function tscBuild(options = {}) {
   return {
     kind: "tsc",
     cwd: options.cwd,
@@ -154,7 +87,7 @@ export function tscBuild(options = {}) {
   };
 }
 
-export function scriptBuild(script, options = {}) {
+function scriptBuild(script, options = {}) {
   return {
     kind: "script",
     script,
@@ -163,7 +96,7 @@ export function scriptBuild(script, options = {}) {
   };
 }
 
-export function stepsBuild(options = {}) {
+function stepsBuild(options = {}) {
   return {
     kind: "steps",
     inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
@@ -171,7 +104,7 @@ export function stepsBuild(options = {}) {
   };
 }
 
-export function nextBuild(options = {}) {
+function nextBuild(options = {}) {
   return {
     kind: "next",
     cwd: options.cwd,
@@ -181,14 +114,14 @@ export function nextBuild(options = {}) {
   };
 }
 
-export function nodeApp(options = {}) {
+function nodeApp(options = {}) {
   const {
     baseUrl: explicitBaseUrl,
     build: explicitBuild,
     buildInputs,
     cwd = ".",
     entry = "src/index.ts",
-    env = {},
+    env,
     envFiles,
     outDir = "dist",
     port,
@@ -202,7 +135,8 @@ export function nodeApp(options = {}) {
     ...serviceConfig
   } = options;
 
-  const normalizedPort = requiredNumber(port, "nodeApp port");
+  const normalizedPort = requiredNumber(port, "app.node port");
+  const normalizedEnv = normalizePresetEnv(env);
   const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
   const build = explicitBuild === undefined ? tscBuild({
     cwd,
@@ -228,12 +162,12 @@ export function nodeApp(options = {}) {
       baseUrl,
       readyUrl: explicitReadyUrl || `${baseUrl}${readyPath}`,
       readyTimeoutMs,
-      env,
+      env: normalizedEnv,
     },
   };
 }
 
-export function nextApp(options = {}) {
+function nextApp(options = {}) {
   const {
     baseUrl: explicitBaseUrl,
     browser,
@@ -241,7 +175,7 @@ export function nextApp(options = {}) {
     buildInputs,
     cwd = ".",
     dependsOn,
-    env = {},
+    env,
     envFiles,
     mode = "dev",
     port,
@@ -253,7 +187,8 @@ export function nextApp(options = {}) {
     ...serviceConfig
   } = options;
 
-  const normalizedPort = requiredNumber(port, "nextApp port");
+  const normalizedPort = requiredNumber(port, "app.next port");
+  const normalizedEnv = normalizePresetEnv(env);
   const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
   const build =
     explicitBuild === undefined
@@ -286,15 +221,47 @@ export function nextApp(options = {}) {
       readyTimeoutMs,
       env: mode === "start"
         ? {
-            NEXT_DIST_DIR: env.NEXT_DIST_DIR || ".next-testkit/{runtimeId}/dist",
-            NEXT_TSCONFIG_PATH: env.NEXT_TSCONFIG_PATH || ".next-testkit/{runtimeId}/tsconfig.json",
-            ...env,
+            NEXT_DIST_DIR: normalizedEnv.NEXT_DIST_DIR || ".next-testkit/{runtimeId}/dist",
+            NEXT_TSCONFIG_PATH:
+              normalizedEnv.NEXT_TSCONFIG_PATH || ".next-testkit/{runtimeId}/tsconfig.json",
+            ...normalizedEnv,
           }
-        : env,
+        : normalizedEnv,
     },
   };
 }
 
+export const app = {
+  node: nodeApp,
+  next: nextApp,
+};
+
+export const database = {
+  postgres(options = {}) {
+    const { template, ...databaseOptions } = options;
+    for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
+      if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
+        throw new Error(
+          `database.postgres(...) no longer accepts top-level "${legacyKey}". Move lifecycle config under database.postgres({ template: { ... } }).`
+        );
+      }
+    }
+    return postgresDatabase(
+      template
+        ? {
+            ...databaseOptions,
+            template: buildDatabaseTemplateConfig(template),
+          }
+        : databaseOptions
+    );
+  },
+  fixture: postgresFixture,
+};
+
+export const toolchain = {
+  node: nodeToolchain,
+};
+
 export function clerkSessionProfile(options = {}) {
   const apiBase = options.apiBase || "https://api.clerk.com/v1";
   const secretKeyEnv = options.secretKeyEnv || "CLERK_SECRET_KEY";
@@ -381,6 +348,58 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function normalizePresetEnv(env) {
+  if (!env) return {};
+  if (typeof env !== "object" || Array.isArray(env)) {
+    throw new Error("Preset env must be an object");
+  }
+  const allowedKeys = new Set(["values", "databases"]);
+  const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(
+      `Preset env only supports "values" and "databases". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
+    );
+  }
+
+  const values = env.values && typeof env.values === "object" && !Array.isArray(env.values) ? env.values : {};
+  const databases =
+    env.databases && typeof env.databases === "object" && !Array.isArray(env.databases) ? env.databases : {};
+
+  return {
+    ...expandDatabaseBindings(databases),
+    ...values,
+  };
+}
+
+function expandDatabaseBindings(bindings) {
+  const env = {};
+  for (const [name, binding] of Object.entries(bindings || {})) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      throw new Error(`env.databases.${name} must be an object`);
+    }
+    const prefix = normalizeDatabaseEnvToken(binding.prefix, `env.databases.${name}.prefix`);
+    const serviceName = normalizeDatabaseEnvToken(binding.service, `env.databases.${name}.service`, false);
+    env[`${prefix}_DATABASE_HOST`] = `{dbHost:${serviceName}}`;
+    env[`${prefix}_DATABASE_PORT`] = `{dbPort:${serviceName}}`;
+    env[`${prefix}_DATABASE_NAME`] = `{dbName:${serviceName}}`;
+    env[`${prefix}_DATABASE_USER`] = `{dbUser:${serviceName}}`;
+    env[`${prefix}_DATABASE_PASSWORD`] = `{dbPassword:${serviceName}}`;
+    env[`${prefix}_DATABASE_SSL`] = "0";
+  }
+  return env;
+}
+
+function normalizeDatabaseEnvToken(value, label, sanitize = true) {
+  const raw = String(value || "").trim();
+  const normalized = sanitize
+    ? raw.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "")
+    : raw;
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
 function resolveNodeAppStart(build, entry) {
   if (build?.kind === "tsc") {
     const compiled = compiledEntryFromSource(entry || build.entry || "src/index.ts", build.outDir || "dist");
@@ -397,7 +416,10 @@ function normalizeTemplateStepList(value) {
 function normalizeSchemaStep(value) {
   if (value == null) return null;
   if (typeof value === "string") {
-    return sqlFileStep(value);
+    return {
+      kind: "sql-file",
+      path: value,
+    };
   }
   return value;
 }

package/lib/config-api/index.test.mjs

@@ -1,26 +1,14 @@
 import { describe, expect, it } from "vitest";
 import {
-  databaseServiceEnv,
+  app,
+  database,
   defineConfig,
   defineFile,
   defineHttpProfile,
-  nextApp,
-  nextBuild,
-  nodeToolchain,
-  nodeApp,
-  postgresDatabase,
-  postgresFixture,
-  schemaSql,
-  seedCommand,
-  seedModule,
-  stepsBuild,
-  templateDatabase,
-  tscBuild,
-  verifyCommand,
-  verifyModule,
+  toolchain,
 } from "./index.mjs";
 
-describe("config helpers", () => {
+describe("config api", () => {
   it("defines repo config plainly", () => {
     expect(defineConfig({ execution: { workers: 4 } })).toEqual({
       execution: { workers: 4 },
@@ -40,13 +28,13 @@ describe("config helpers", () => {
   });
 
   it("builds a Next app preset for dev mode", () => {
-    const config = nextApp({ port: 3000 });
+    const config = app.next({ port: 3000 });
 
     expect(config.local.start).toBe("./node_modules/.bin/next dev -p {port}");
   });
 
   it("builds a Next app preset for start mode with managed runtime env defaults", () => {
-    const config = nextApp({ cwd: "frontend", port: 3000, mode: "start" });
+    const config = app.next({ cwd: "frontend", port: 3000, mode: "start" });
 
     expect(config.local.start).toBe("./node_modules/.bin/next start --port {port}");
     expect(config.local.env).toMatchObject({
@@ -63,7 +51,7 @@ describe("config helpers", () => {
   });
 
   it("allows Next start apps to disable managed builds explicitly", () => {
-    const config = nextApp({ cwd: "frontend", port: 3000, mode: "start", build: null });
+    const config = app.next({ cwd: "frontend", port: 3000, mode: "start", build: null });
 
     expect(config.runtime.build).toBeNull();
     expect(config.local.env).toMatchObject({
@@ -73,7 +61,7 @@ describe("config helpers", () => {
   });
 
   it("builds a Node app preset with tsc build defaults", () => {
-    const config = nodeApp({ port: 3000, entry: "src/server.ts" });
+    const config = app.node({ port: 3000, entry: "src/server.ts" });
 
     expect(config.local.start).toBe("node {prepareDir}/dist/server.js");
     expect(config.runtime.build).toEqual({
@@ -87,88 +75,22 @@ describe("config helpers", () => {
   });
 
   it("builds node toolchain profiles with a node kind", () => {
-    expect(nodeToolchain({ node: "20.19.5", install: "download" })).toEqual({
+    expect(toolchain.node({ node: "20.19.5", install: "download" })).toEqual({
       kind: "node",
       node: "20.19.5",
       install: "download",
     });
   });
 
-  it("builds explicit build presets", () => {
-    expect(tscBuild({ entry: "src/server.ts", outDir: "build" })).toEqual({
-      kind: "tsc",
-      cwd: undefined,
-      entry: "src/server.ts",
-      tsconfig: "tsconfig.json",
-      outDir: "build",
-      inputs: undefined,
-    });
-    expect(nextBuild({ cwd: "frontend" })).toEqual({
-      kind: "next",
-      cwd: "frontend",
-      distDir: "dist",
-      tsconfig: "tsconfig.json",
-      inputs: undefined,
-    });
+  it("builds declarative postgres database templates from plain objects", () => {
     expect(
-      stepsBuild({
-        inputs: ["scripts/prepare.mjs"],
-        steps: [seedCommand("node scripts/prepare.mjs")],
-      })
-    ).toEqual({
-      kind: "steps",
-      inputs: ["scripts/prepare.mjs"],
-      steps: [
-        {
-          kind: "command",
-          cmd: "node scripts/prepare.mjs",
-          cwd: undefined,
-          inputs: undefined,
+      database.postgres({
+        template: {
+          inputs: ["db/schema.sql", "scripts/seed.ts"],
+          schema: "db/schema.sql",
+          seed: { kind: "command", run: "npm run db:seed" },
+          verify: { kind: "module", target: "scripts/verify.ts#verifySeed" },
         },
-      ],
-    });
-  });
-
-  it("emits semantic database template steps using the underlying step shapes", () => {
-    expect(schemaSql("db/schema.sql")).toEqual({
-      kind: "sql-file",
-      path: "db/schema.sql",
-      cwd: undefined,
-      inputs: undefined,
-    });
-    expect(seedCommand("npm run db:seed")).toEqual({
-      kind: "command",
-      cmd: "npm run db:seed",
-      cwd: undefined,
-      inputs: undefined,
-    });
-    expect(seedModule("scripts/seed.ts#seed")).toEqual({
-      kind: "module",
-      specifier: "scripts/seed.ts#seed",
-      cwd: undefined,
-      inputs: undefined,
-    });
-    expect(verifyCommand("npm run db:verify")).toEqual({
-      kind: "command",
-      cmd: "npm run db:verify",
-      cwd: undefined,
-      inputs: undefined,
-    });
-    expect(verifyModule("scripts/verify.ts#verify")).toEqual({
-      kind: "module",
-      specifier: "scripts/verify.ts#verify",
-      cwd: undefined,
-      inputs: undefined,
-    });
-  });
-
-  it("builds declarative template databases from schema, seed, and verify intents", () => {
-    expect(
-      templateDatabase({
-        inputs: ["db/schema.sql", "scripts/seed.ts"],
-        schema: "db/schema.sql",
-        seed: seedCommand("npm run db:seed"),
-        verify: verifyModule("scripts/verify.ts#verifySeed"),
       })
     ).toEqual({
       provider: "local",
@@ -178,24 +100,18 @@ describe("config helpers", () => {
           {
             kind: "sql-file",
             path: "db/schema.sql",
-            cwd: undefined,
-            inputs: undefined,
           },
         ],
         seed: [
           {
             kind: "command",
-            cmd: "npm run db:seed",
-            cwd: undefined,
-            inputs: undefined,
+            run: "npm run db:seed",
           },
         ],
         verify: [
           {
             kind: "module",
-            specifier: "scripts/verify.ts#verifySeed",
-            cwd: undefined,
-            inputs: undefined,
+            target: "scripts/verify.ts#verifySeed",
           },
         ],
       },
@@ -204,9 +120,11 @@ describe("config helpers", () => {
 
   it("prepends schema before explicit migrate steps and normalizes singletons to arrays", () => {
     expect(
-      templateDatabase({
-        schema: schemaSql("db/schema.sql", { cwd: "db" }),
-        migrate: seedCommand("echo migrate"),
+      database.postgres({
+        template: {
+          schema: { kind: "sql-file", path: "db/schema.sql", cwd: "db" },
+          migrate: { kind: "command", run: "echo migrate" },
+        },
       })
     ).toEqual({
       provider: "local",
@@ -217,13 +135,10 @@ describe("config helpers", () => {
             kind: "sql-file",
             path: "db/schema.sql",
             cwd: "db",
-            inputs: undefined,
           },
           {
             kind: "command",
-            cmd: "echo migrate",
-            cwd: undefined,
-            inputs: undefined,
+            run: "echo migrate",
           },
         ],
         seed: [],
@@ -232,46 +147,9 @@ describe("config helpers", () => {
     });
   });
 
-  it("builds declarative postgres database helpers", () => {
-    expect(postgresDatabase({ reset: false })).toEqual({
-      provider: "local",
-      reset: false,
-    });
+  it("builds support database presets and expands database env bindings declaratively", () => {
     expect(
-      templateDatabase({
-        reset: true,
-        schema: "db/schema.sql",
-        seed: seedCommand("npm run db:seed"),
-      })
-    ).toEqual({
-      provider: "local",
-      reset: true,
-      template: {
-        inputs: undefined,
-        migrate: [
-          {
-            kind: "sql-file",
-            path: "db/schema.sql",
-            cwd: undefined,
-            inputs: undefined,
-          },
-        ],
-        seed: [
-          {
-            kind: "command",
-            cmd: "npm run db:seed",
-            cwd: undefined,
-            inputs: undefined,
-          },
-        ],
-        verify: [],
-      },
-    });
-  });
-
-  it("builds support database presets and env bindings", () => {
-    expect(
-      postgresFixture({
+      database.fixture({
         reset: true,
       })
     ).toEqual({
@@ -285,7 +163,19 @@ describe("config helpers", () => {
         reset: true,
       },
     });
-    expect(databaseServiceEnv("ONIX", "catalog")).toEqual({
+
+    const config = app.node({
+      port: 3000,
+      env: {
+        values: { API_KEY: "test" },
+        databases: {
+          onix: { service: "catalog", prefix: "ONIX" },
+        },
+      },
+    });
+
+    expect(config.local.env).toEqual({
+      API_KEY: "test",
       ONIX_DATABASE_HOST: "{dbHost:catalog}",
       ONIX_DATABASE_PORT: "{dbPort:catalog}",
       ONIX_DATABASE_NAME: "{dbName:catalog}",
@@ -295,12 +185,25 @@ describe("config helpers", () => {
     });
   });
 
+  it("rejects top-level database template lifecycle fields", () => {
+    expect(() =>
+      database.postgres({
+        schema: "db/schema.sql",
+      })
+    ).toThrow(/no longer accepts top-level "schema"/);
+    expect(() =>
+      database.fixture({
+        seed: { kind: "command", run: "npm run db:seed" },
+      })
+    ).toThrow(/no longer accepts top-level "seed"/);
+  });
+
   it("does not leak preset-only helper fields into node app configs", () => {
-    const config = nodeApp({
+    const config = app.node({
       port: 3000,
       entry: "src/server.ts",
       buildInputs: ["src", "package.json"],
-      env: { API_KEY: "test" },
+      env: { values: { API_KEY: "test" } },
       readyPath: "/live",
     });
 
@@ -310,4 +213,15 @@ describe("config helpers", () => {
     expect(config.local.env).toEqual({ API_KEY: "test" });
     expect(config.local.readyUrl).toBe("http://127.0.0.1:{port}/live");
   });
+
+  it("rejects flat preset env maps in favor of env.values and env.databases", () => {
+    expect(() =>
+      app.node({
+        port: 3000,
+        env: {
+          API_KEY: "test",
+        },
+      })
+    ).toThrow(/Preset env only supports "values" and "databases"/);
+  });
 });

package/lib/coverage/index.test.mjs

@@ -19,11 +19,11 @@ describe("coverage graph builder", () => {
       productDir,
       "testkit.config.ts",
       `
-        import { defineConfig, nextApp } from "@elench/testkit/config";
+        import { app, defineConfig } from "@elench/testkit/config";
 
         export default defineConfig({
           services: {
-            web: nextApp({
+            web: app.next({
               cwd: ".",
               start: "node server.js",
               mode: "start",

package/lib/runner/template.mjs

@@ -280,6 +280,7 @@ export function resolveTemplateString(value, context) {
   return value.replace(/\{([a-zA-Z]+)(?::([a-zA-Z0-9_-]+))?\}/g, (_match, token, arg) => {
     switch (token) {
       case "runtime":
+      case "runtimeId":
         return String(context.runtimeId);
       case "service":
         return context.serviceName;

package/lib/runner/template.test.mjs

@@ -192,6 +192,9 @@ describe("runner-template", () => {
       TESTKIT_LEASE_ID: "lease-1",
       TESTKIT_LEASE_DIR: "/tmp/lease-1",
     });
+    expect(finalizeString(".next-testkit/{runtimeId}/dist", resolved[1].testkit.templateContext)).toBe(
+      ".next-testkit/runtime-2/dist"
+    );
 
     expect(
       buildPlaywrightEnv(

package/lib/shared/build-config.test.mjs

@@ -77,7 +77,7 @@ describe("shared build config helpers", () => {
         {
           kind: "steps",
           inputs: ["scripts/prepare.mjs"],
-          steps: [{ kind: "command", cmd: "node scripts/prepare.mjs" }],
+          steps: [{ kind: "command", run: "node scripts/prepare.mjs" }],
         },
         "runtime.build"
       )

package/lib/shared/configured-steps.mjs

@@ -53,8 +53,8 @@ export function normalizeConfiguredStep(step, label) {
 
   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`);
+    const cmd = normalizeOptionalString(step.run);
+    if (!cmd) throw new Error(`${label}.run must be a non-empty string`);
     return {
       kind,
       cmd,
@@ -73,8 +73,8 @@ export function normalizeConfiguredStep(step, label) {
     };
   }
   if (kind === "module") {
-    const specifier = normalizeOptionalString(step.specifier);
-    if (!specifier) throw new Error(`${label}.specifier must be a non-empty string`);
+    const specifier = normalizeOptionalString(step.target);
+    if (!specifier) throw new Error(`${label}.target must be a non-empty string`);
     return {
       kind,
       specifier,
@@ -118,7 +118,8 @@ export function collectConfiguredInputs(productDir, { inputs = [], steps = [] }
       collected.add(resolveConfiguredPath(productDir, step.cwd, step.path));
     }
     if (step.kind === "module") {
-      const { modulePath } = parseModuleSpecifier(step.specifier);
+      const moduleRef = step.specifier || step.target;
+      const { modulePath } = parseModuleSpecifier(moduleRef);
       const candidatePath = resolveConfiguredPath(productDir, step.cwd, modulePath);
       if (modulePath.startsWith("@elench/testkit") || fs.existsSync(candidatePath)) {
         if (!modulePath.startsWith("@elench/testkit")) {
@@ -138,7 +139,7 @@ export function collectConfiguredInputs(productDir, { inputs = [], steps = [] }
 export function summarizeConfiguredStep(step) {
   if (step.kind === "command") return `command: ${String(step.cmd).trim()}`;
   if (step.kind === "sql-file") return `sql: ${step.path}`;
-  if (step.kind === "module") return `module: ${step.specifier}`;
+  if (step.kind === "module") return `module: ${step.specifier || step.target}`;
   return step.kind;
 }
 
@@ -174,7 +175,8 @@ export function validateConfiguredCollection({ productDir, label, inputs = [], s
       ensureExistingPath(resolveConfiguredPath(productDir, step.cwd, step.path), `${label} sql file`);
     }
     if (step.kind === "module") {
-      const { modulePath } = parseModuleSpecifier(step.specifier);
+      const moduleRef = step.specifier || step.target;
+      const { modulePath } = parseModuleSpecifier(moduleRef);
       const candidatePath = resolveConfiguredPath(productDir, step.cwd, modulePath);
       if (modulePath.startsWith("@elench/testkit")) {
         // Internal testkit module steps are resolved by the runtime alias map.

package/lib/shared/configured-steps.test.mjs

@@ -22,7 +22,7 @@ afterEach(() => {
 describe("shared configured steps", () => {
   it("normalizes and finalizes configured steps", () => {
     const normalized = normalizeConfiguredStep(
-      { kind: "module", specifier: "./seed.mjs#run", cwd: "db", inputs: ["schema.sql"] },
+      { kind: "module", target: "./seed.mjs#run", cwd: "db", inputs: ["schema.sql"] },
       'Service "api" database.template.seed[0]'
     );
 
@@ -55,7 +55,7 @@ describe("shared configured steps", () => {
       inputs: ["db/schema.sql"],
       steps: [
         { kind: "sql-file", path: "schema.sql", cwd: "db", inputs: [] },
-        { kind: "module", specifier: "./seed.mjs#run", cwd: "db", inputs: [] },
+        { kind: "module", target: "./seed.mjs#run", cwd: "db", inputs: [] },
       ],
     };
 
@@ -82,7 +82,7 @@ describe("shared configured steps", () => {
       steps: [
         {
           kind: "module",
-          specifier: "@elench/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          target: "@elench/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",
           cwd: "frontend",
           inputs: [],
         },

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.75"
+    "@elench/testkit-protocol": "0.1.77"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "workspaces": [
@@ -81,10 +81,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.75",
-    "@elench/testkit-bridge": "0.1.75",
-    "@elench/testkit-protocol": "0.1.75",
-    "@elench/ts-analysis": "0.1.75",
+    "@elench/next-analysis": "0.1.77",
+    "@elench/testkit-bridge": "0.1.77",
+    "@elench/testkit-protocol": "0.1.77",
+    "@elench/ts-analysis": "0.1.77",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",
     "execa": "^9.5.0",