@elench/testkit 0.1.66 → 0.1.68

package/lib/setup/index.mjs

@@ -18,11 +18,11 @@ export function defineHttpProfile(profile) {
   return profile || {};
 }
 
-export function service(config) {
-  return config || {};
+export function defineTestkitFile(metadata) {
+  return metadata || {};
 }
 
-export function localDatabase(options = {}) {
+export function postgresDatabase(options = {}) {
   return {
     provider: "local",
     ...options,
@@ -76,7 +76,7 @@ export function verifyModule(specifier, options = {}) {
   return moduleStep(specifier, options);
 }
 
-export function seededDatabaseTemplate(options = {}) {
+function buildDatabaseTemplateConfig(options = {}) {
   const migrate = normalizeTemplateStepList(options.migrate);
   const seed = normalizeTemplateStepList(options.seed);
   const verify = normalizeTemplateStepList(options.verify);
@@ -90,6 +90,52 @@ export function seededDatabaseTemplate(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;
+  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",
+  };
+}
+
 export function nodeToolchain(options = {}) {
   return {
     kind: "node",
@@ -97,61 +143,154 @@ export function nodeToolchain(options = {}) {
   };
 }
 
-export function goService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "goService port");
-  const readyPath = options.readyPath || "/health";
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+export function tscBuild(options = {}) {
+  return {
+    kind: "tsc",
+    cwd: options.cwd,
+    entry: options.entry || "src/index.ts",
+    tsconfig: options.tsconfig || "tsconfig.json",
+    outDir: options.outDir || "dist",
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+  };
+}
 
+export function scriptBuild(script, options = {}) {
   return {
-    ...service(options),
-    local: {
-      cwd,
-      start: options.start || defaultGoStartCommand(options),
-      port,
-      baseUrl,
-      readyUrl: options.readyUrl || `${baseUrl}${readyPath}`,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
-    },
+    kind: "script",
+    script,
+    cwd: options.cwd,
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
   };
 }
 
-export function nextService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "nextService port");
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+export function stepsBuild(options = {}) {
+  return {
+    kind: "steps",
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+    steps: Array.isArray(options.steps) ? [...options.steps] : [],
+  };
+}
 
+export function nextBuild(options = {}) {
   return {
-    ...service(options),
+    kind: "next",
+    cwd: options.cwd,
+    distDir: options.distDir || "dist",
+    tsconfig: options.tsconfig || "tsconfig.json",
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+  };
+}
+
+export function nodeApp(options = {}) {
+  const {
+    baseUrl: explicitBaseUrl,
+    build: explicitBuild,
+    buildInputs,
+    cwd = ".",
+    entry = "src/index.ts",
+    env = {},
+    envFiles,
+    outDir = "dist",
+    port,
+    readyPath = "/health",
+    readyTimeoutMs,
+    readyUrl: explicitReadyUrl,
+    runtime,
+    start: explicitStart,
+    toolchain,
+    tsconfig = "tsconfig.json",
+    ...serviceConfig
+  } = options;
+
+  const normalizedPort = requiredNumber(port, "nodeApp port");
+  const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
+  const build = explicitBuild === undefined ? tscBuild({
+    cwd,
+    entry,
+    tsconfig,
+    outDir,
+    inputs: buildInputs,
+  }) : explicitBuild;
+  const start = explicitStart || resolveNodeAppStart(build, entry);
+
+  return {
+    ...serviceConfig,
+    envFiles,
+    runtime: {
+      ...(runtime || {}),
+      build,
+      toolchain: toolchain ?? runtime?.toolchain,
+    },
     local: {
       cwd,
-      start: options.start || "./node_modules/.bin/next dev -p {port}",
-      port,
+      start,
+      port: normalizedPort,
       baseUrl,
-      readyUrl: options.readyUrl || baseUrl,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
+      readyUrl: explicitReadyUrl || `${baseUrl}${readyPath}`,
+      readyTimeoutMs,
+      env,
     },
   };
 }
 
-export function tsxService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "tsxService port");
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
-  const entry = options.entry || "src/index.ts";
+export function nextApp(options = {}) {
+  const {
+    baseUrl: explicitBaseUrl,
+    browser,
+    build: explicitBuild,
+    buildInputs,
+    cwd = ".",
+    dependsOn,
+    env = {},
+    envFiles,
+    mode = "dev",
+    port,
+    readyTimeoutMs,
+    readyUrl: explicitReadyUrl,
+    runtime,
+    start: explicitStart,
+    toolchain,
+    ...serviceConfig
+  } = options;
+
+  const normalizedPort = requiredNumber(port, "nextApp port");
+  const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
+  const build =
+    explicitBuild === undefined
+      ? mode === "start"
+        ? nextBuild({ cwd, inputs: buildInputs })
+        : null
+      : explicitBuild;
+  const start =
+    explicitStart ||
+    (mode === "start"
+      ? "./node_modules/.bin/next start --port {port}"
+      : "./node_modules/.bin/next dev -p {port}");
 
   return {
-    ...service(options),
+    ...serviceConfig,
+    envFiles,
+    dependsOn: Array.isArray(dependsOn) ? [...dependsOn] : dependsOn,
+    browser,
+    runtime: {
+      ...(runtime || {}),
+      build,
+      toolchain: toolchain ?? runtime?.toolchain,
+    },
     local: {
       cwd,
-      start: options.start || `./node_modules/.bin/tsx watch ${entry}`,
-      port,
+      start,
+      port: normalizedPort,
       baseUrl,
-      readyUrl: options.readyUrl || `${baseUrl}${options.readyPath || "/health"}`,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
+      readyUrl: explicitReadyUrl || baseUrl,
+      readyTimeoutMs,
+      env: mode === "start"
+        ? {
+            NEXT_DIST_DIR: env.NEXT_DIST_DIR || "{prepareDir}/dist",
+            NEXT_TSCONFIG_PATH: env.NEXT_TSCONFIG_PATH || "{prepareDir}/tsconfig.json",
+            ...env,
+          }
+        : env,
     },
   };
 }
@@ -235,16 +374,6 @@ export {
   runtimeJson,
 };
 
-function defaultGoStartCommand(options) {
-  if (options.command) {
-    return `go run ${options.command}`;
-  }
-  if (options.entrypoint) {
-    return `go run ${options.entrypoint}`;
-  }
-  return "go run ./cmd/server";
-}
-
 function requiredNumber(value, label) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${label} must be a positive integer`);
@@ -252,6 +381,14 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function resolveNodeAppStart(build, entry) {
+  if (build?.kind === "tsc") {
+    const compiled = compiledEntryFromSource(entry || build.entry || "src/index.ts", build.outDir || "dist");
+    return `node {prepareDir}/${compiled}`;
+  }
+  return `./node_modules/.bin/tsx ${entry || "src/index.ts"}`;
+}
+
 function normalizeTemplateStepList(value) {
   if (value == null) return [];
   return Array.isArray(value) ? [...value] : [value];
@@ -265,6 +402,13 @@ function normalizeSchemaStep(value) {
   return value;
 }
 
+function compiledEntryFromSource(entry, outDir) {
+  const normalized = String(entry || "src/index.ts").replaceAll("\\", "/");
+  const compiled = normalized.replace(/\.[cm]?[jt]sx?$/i, ".js");
+  const relative = compiled.startsWith("src/") ? compiled.slice(4) : compiled;
+  return `${outDir}/${relative}`.replace(/\/+/g, "/");
+}
+
 function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];

package/lib/setup/index.test.mjs

@@ -1,38 +1,76 @@
 import { describe, expect, it } from "vitest";
 import {
-  goService,
-  nextService,
+  databaseServiceEnv,
+  defineTestkitFile,
+  nextApp,
+  nextBuild,
   nodeToolchain,
+  nodeApp,
+  postgresDatabase,
+  postgresFixture,
   schemaSql,
   seedCommand,
   seedModule,
-  seededDatabaseTemplate,
-  tsxService,
+  stepsBuild,
+  templateDatabase,
+  tscBuild,
   verifyCommand,
   verifyModule,
 } from "./index.mjs";
 
 describe("setup helpers", () => {
-  it("emits plain next start commands without an exec prefix", () => {
-    const config = nextService({ port: 3000 });
+  it("defines file-local metadata plainly", () => {
+    expect(defineTestkitFile({ skip: "Auth is stubbed", locks: ["background-workers"] })).toEqual({
+      skip: "Auth is stubbed",
+      locks: ["background-workers"],
+    });
+  });
+
+  it("builds a Next app preset for dev mode", () => {
+    const config = nextApp({ port: 3000 });
 
     expect(config.local.start).toBe("./node_modules/.bin/next dev -p {port}");
   });
 
-  it("emits plain tsx start commands without an exec prefix", () => {
-    const config = tsxService({ port: 3000, entry: "src/server.ts" });
+  it("builds a Next app preset for start mode with managed runtime env defaults", () => {
+    const config = nextApp({ cwd: "frontend", port: 3000, mode: "start" });
+
+    expect(config.local.start).toBe("./node_modules/.bin/next start --port {port}");
+    expect(config.local.env).toMatchObject({
+      NEXT_DIST_DIR: "{prepareDir}/dist",
+      NEXT_TSCONFIG_PATH: "{prepareDir}/tsconfig.json",
+    });
+    expect(config.runtime.build).toEqual({
+      kind: "next",
+      cwd: "frontend",
+      distDir: "dist",
+      tsconfig: "tsconfig.json",
+      inputs: undefined,
+    });
+  });
+
+  it("allows Next start apps to disable managed builds explicitly", () => {
+    const config = nextApp({ cwd: "frontend", port: 3000, mode: "start", build: null });
 
-    expect(config.local.start).toBe("./node_modules/.bin/tsx watch src/server.ts");
+    expect(config.runtime.build).toBeNull();
+    expect(config.local.env).toMatchObject({
+      NEXT_DIST_DIR: "{prepareDir}/dist",
+      NEXT_TSCONFIG_PATH: "{prepareDir}/tsconfig.json",
+    });
   });
 
-  it("emits plain go start commands without an exec prefix", () => {
-    expect(goService({ port: 3000 }).local.start).toBe("go run ./cmd/server");
-    expect(goService({ port: 3000, entrypoint: "./cmd/api" }).local.start).toBe(
-      "go run ./cmd/api"
-    );
-    expect(goService({ port: 3000, command: "./cmd/worker" }).local.start).toBe(
-      "go run ./cmd/worker"
-    );
+  it("builds a Node app preset with tsc build defaults", () => {
+    const config = nodeApp({ port: 3000, entry: "src/server.ts" });
+
+    expect(config.local.start).toBe("node {prepareDir}/dist/server.js");
+    expect(config.runtime.build).toEqual({
+      kind: "tsc",
+      cwd: ".",
+      entry: "src/server.ts",
+      tsconfig: "tsconfig.json",
+      outDir: "dist",
+      inputs: undefined,
+    });
   });
 
   it("builds node toolchain profiles with a node kind", () => {
@@ -43,6 +81,41 @@ describe("setup helpers", () => {
     });
   });
 
+  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,
+    });
+    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,
+        },
+      ],
+    });
+  });
+
   it("emits semantic database template steps using the underlying step shapes", () => {
     expect(schemaSql("db/schema.sql")).toEqual({
       kind: "sql-file",
@@ -76,67 +149,152 @@ describe("setup helpers", () => {
     });
   });
 
-  it("builds a seeded database template from schema, seed, and verify intents", () => {
+  it("builds declarative template databases from schema, seed, and verify intents", () => {
     expect(
-      seededDatabaseTemplate({
+      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({
-      inputs: ["db/schema.sql", "scripts/seed.ts"],
-      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: [
-        {
-          kind: "module",
-          specifier: "scripts/verify.ts#verifySeed",
-          cwd: undefined,
-          inputs: undefined,
-        },
-      ],
+      provider: "local",
+      template: {
+        inputs: ["db/schema.sql", "scripts/seed.ts"],
+        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: [
+          {
+            kind: "module",
+            specifier: "scripts/verify.ts#verifySeed",
+            cwd: undefined,
+            inputs: undefined,
+          },
+        ],
+      },
     });
   });
 
   it("prepends schema before explicit migrate steps and normalizes singletons to arrays", () => {
     expect(
-      seededDatabaseTemplate({
+      templateDatabase({
         schema: schemaSql("db/schema.sql", { cwd: "db" }),
         migrate: seedCommand("echo migrate"),
       })
     ).toEqual({
-      inputs: undefined,
-      migrate: [
-        {
-          kind: "sql-file",
-          path: "db/schema.sql",
-          cwd: "db",
-          inputs: undefined,
-        },
-        {
-          kind: "command",
-          cmd: "echo migrate",
-          cwd: undefined,
-          inputs: undefined,
-        },
-      ],
-      seed: [],
-      verify: [],
+      provider: "local",
+      template: {
+        inputs: undefined,
+        migrate: [
+          {
+            kind: "sql-file",
+            path: "db/schema.sql",
+            cwd: "db",
+            inputs: undefined,
+          },
+          {
+            kind: "command",
+            cmd: "echo migrate",
+            cwd: undefined,
+            inputs: undefined,
+          },
+        ],
+        seed: [],
+        verify: [],
+      },
+    });
+  });
+
+  it("builds declarative postgres database helpers", () => {
+    expect(postgresDatabase({ reset: false })).toEqual({
+      provider: "local",
+      reset: false,
+    });
+    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({
+        reset: true,
+      })
+    ).toEqual({
+      discovery: {
+        roots: [".testkit-fixture"],
+      },
+      envFiles: undefined,
+      local: false,
+      database: {
+        provider: "local",
+        reset: true,
+      },
+    });
+    expect(databaseServiceEnv("ONIX", "catalog")).toEqual({
+      ONIX_DATABASE_HOST: "{dbHost:catalog}",
+      ONIX_DATABASE_PORT: "{dbPort:catalog}",
+      ONIX_DATABASE_NAME: "{dbName:catalog}",
+      ONIX_DATABASE_USER: "{dbUser:catalog}",
+      ONIX_DATABASE_PASSWORD: "{dbPassword:catalog}",
+      ONIX_DATABASE_SSL: "0",
+    });
+  });
+
+  it("does not leak preset-only helper fields into node app configs", () => {
+    const config = nodeApp({
+      port: 3000,
+      entry: "src/server.ts",
+      buildInputs: ["src", "package.json"],
+      env: { API_KEY: "test" },
+      readyPath: "/live",
+    });
+
+    expect(config).not.toHaveProperty("entry");
+    expect(config).not.toHaveProperty("buildInputs");
+    expect(config).not.toHaveProperty("readyPath");
+    expect(config.local.env).toEqual({ API_KEY: "test" });
+    expect(config.local.readyUrl).toBe("http://127.0.0.1:{port}/live");
+  });
 });

package/lib/setup/next-runtime-tsconfig.mjs

@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+
+export async function writeNextRuntimeTsconfig(context = {}) {
+  const serviceDir = context.cwd || context.productDir;
+  const prepareDir = context.prepareDir;
+  if (!serviceDir || !prepareDir) {
+    throw new Error("writeNextRuntimeTsconfig requires cwd and prepareDir");
+  }
+
+  const outputPath = path.join(prepareDir, "tsconfig.json");
+  const outputDir = path.dirname(outputPath);
+  const relative = (target) => path.relative(outputDir, target).replaceAll(path.sep, "/");
+  const srcDir = path.join(serviceDir, "src");
+  const testsDir = path.join(serviceDir, "tests");
+
+  const config = {
+    extends: relative(path.join(serviceDir, "tsconfig.json")),
+    compilerOptions: {
+      paths: {
+        "@/*": [relative(path.join(srcDir, "*"))],
+      },
+    },
+    include: [
+      relative(path.join(serviceDir, "next-env.d.ts")),
+      `${relative(srcDir)}/**/*.ts`,
+      `${relative(srcDir)}/**/*.tsx`,
+      `${relative(srcDir)}/**/*.mts`,
+      `${relative(path.join(prepareDir, "dist", "types"))}/**/*.ts`,
+      `${relative(path.join(prepareDir, "dist", "dev", "types"))}/**/*.ts`,
+    ],
+    exclude: [
+      "node_modules",
+      `${relative(srcDir)}/**/__testkit__/**`,
+      `${relative(testsDir)}/**`,
+      ".next/cache",
+      ".next/dev",
+    ],
+  };
+
+  fs.mkdirSync(outputDir, { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(config, null, 2)}\n`);
+}