@elench/testkit 0.1.67 → 0.1.68

package/lib/runner/template-steps.mjs

@@ -21,6 +21,12 @@ import {
 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 SETUP_NEXT_TSCONFIG_ENTRY = path.join(
+  PACKAGE_ROOT,
+  "lib",
+  "setup",
+  "next-runtime-tsconfig.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(
@@ -225,6 +231,7 @@ function resolvePackageSubpath(specifier) {
   const subpath = specifier.slice("@elench/testkit".length);
   if (!subpath) return ROOT_ENTRY;
   if (subpath === "/setup") return SETUP_ENTRY;
+  if (subpath === "/setup/next-runtime-tsconfig") return SETUP_NEXT_TSCONFIG_ENTRY;
   if (subpath === "/runtime") return RUNTIME_ENTRY;
   if (subpath === "/known-failures") return KNOWN_FAILURES_ENTRY;
 

package/lib/setup/index.d.ts

@@ -56,13 +56,21 @@ export interface ScriptBuildConfig {
   script: string;
 }
 
+export interface NextBuildConfig {
+  kind: "next";
+  cwd?: string;
+  distDir?: string;
+  inputs?: string[];
+  tsconfig?: string;
+}
+
 export interface StepsBuildConfig {
   kind: "steps";
   inputs?: string[];
   steps?: TemplateLifecycleStepConfig[];
 }
 
-export type BuildConfig = TscBuildConfig | ScriptBuildConfig | StepsBuildConfig;
+export type BuildConfig = TscBuildConfig | ScriptBuildConfig | NextBuildConfig | StepsBuildConfig;
 
 export interface LocalDatabaseConfig {
   provider: "local";
@@ -151,6 +159,7 @@ export interface ServiceConfig {
   databaseFrom?: string;
   dependsOn?: string[];
   discovery?: DiscoveryConfig;
+  env?: Record<string, string>;
   envFile?: string;
   envFiles?: string[];
   browser?: BrowserServiceConfig;
@@ -282,7 +291,7 @@ export declare function scriptBuild(
   options?: Omit<ScriptBuildConfig, "kind" | "script">
 ): ScriptBuildConfig;
 export declare function stepsBuild(options?: Omit<StepsBuildConfig, "kind">): StepsBuildConfig;
-export declare function nextBuild(options?: Omit<ScriptBuildConfig, "kind" | "script">): ScriptBuildConfig;
+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 function clerkSessionProfile(options?: {

package/lib/setup/index.mjs

@@ -172,7 +172,13 @@ export function stepsBuild(options = {}) {
 }
 
 export function nextBuild(options = {}) {
-  return scriptBuild("./node_modules/.bin/next build", options);
+  return {
+    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 = {}) {
@@ -249,7 +255,12 @@ export function nextApp(options = {}) {
 
   const normalizedPort = requiredNumber(port, "nextApp port");
   const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
-  const build = mode === "start" ? explicitBuild || nextBuild({ cwd, inputs: buildInputs }) : explicitBuild || null;
+  const build =
+    explicitBuild === undefined
+      ? mode === "start"
+        ? nextBuild({ cwd, inputs: buildInputs })
+        : null
+      : explicitBuild;
   const start =
     explicitStart ||
     (mode === "start"
@@ -273,7 +284,13 @@ export function nextApp(options = {}) {
       baseUrl,
       readyUrl: explicitReadyUrl || baseUrl,
       readyTimeoutMs,
-      env,
+      env: mode === "start"
+        ? {
+            NEXT_DIST_DIR: env.NEXT_DIST_DIR || "{prepareDir}/dist",
+            NEXT_TSCONFIG_PATH: env.NEXT_TSCONFIG_PATH || "{prepareDir}/tsconfig.json",
+            ...env,
+          }
+        : env,
     },
   };
 }

package/lib/setup/index.test.mjs

@@ -32,6 +32,33 @@ describe("setup helpers", () => {
     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" });
+
+    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.runtime.build).toBeNull();
+    expect(config.local.env).toMatchObject({
+      NEXT_DIST_DIR: "{prepareDir}/dist",
+      NEXT_TSCONFIG_PATH: "{prepareDir}/tsconfig.json",
+    });
+  });
+
   it("builds a Node app preset with tsc build defaults", () => {
     const config = nodeApp({ port: 3000, entry: "src/server.ts" });
 
@@ -64,9 +91,10 @@ describe("setup helpers", () => {
       inputs: undefined,
     });
     expect(nextBuild({ cwd: "frontend" })).toEqual({
-      kind: "script",
-      script: "./node_modules/.bin/next build",
+      kind: "next",
       cwd: "frontend",
+      distDir: "dist",
+      tsconfig: "tsconfig.json",
       inputs: undefined,
     });
     expect(

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`);
+}

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

@@ -0,0 +1,57 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { writeNextRuntimeTsconfig } from "./next-runtime-tsconfig.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("next runtime tsconfig helper", () => {
+  it("writes a runtime-specific tsconfig for next builds", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-next-tsconfig-"));
+    cleanups.push(() => fs.rmSync(tempRoot, { recursive: true, force: true }));
+
+    const serviceDir = path.join(tempRoot, "frontend");
+    const prepareDir = path.join(tempRoot, ".testkit", "prepared");
+    fs.mkdirSync(path.join(serviceDir, "src"), { recursive: true });
+    fs.writeFileSync(path.join(serviceDir, "tsconfig.json"), "{}\n");
+    fs.writeFileSync(path.join(serviceDir, "next-env.d.ts"), "// next\n");
+
+    await writeNextRuntimeTsconfig({
+      cwd: serviceDir,
+      prepareDir,
+      productDir: tempRoot,
+    });
+
+    const generated = JSON.parse(fs.readFileSync(path.join(prepareDir, "tsconfig.json"), "utf8"));
+    expect(generated).toEqual({
+      extends: "../../frontend/tsconfig.json",
+      compilerOptions: {
+        paths: {
+          "@/*": ["../../frontend/src/*"],
+        },
+      },
+      include: [
+        "../../frontend/next-env.d.ts",
+        "../../frontend/src/**/*.ts",
+        "../../frontend/src/**/*.tsx",
+        "../../frontend/src/**/*.mts",
+        "dist/types/**/*.ts",
+        "dist/dev/types/**/*.ts",
+      ],
+      exclude: [
+        "node_modules",
+        "../../frontend/src/**/__testkit__/**",
+        "../../frontend/tests/**",
+        ".next/cache",
+        ".next/dev",
+      ],
+    });
+  });
+});

package/lib/shared/build-config.mjs

@@ -30,6 +30,16 @@ export function normalizeBuildConfig(value, label) {
     };
   }
 
+  if (kind === "next") {
+    return {
+      kind,
+      cwd: normalizeOptionalString(value.cwd),
+      distDir: normalizeOptionalString(value.distDir) || "dist",
+      tsconfig: normalizeOptionalString(value.tsconfig) || "tsconfig.json",
+      inputs: normalizeConfiguredInputs(value.inputs, `${label}.inputs`),
+    };
+  }
+
   if (kind === "steps") {
     return {
       kind,
@@ -38,7 +48,7 @@ export function normalizeBuildConfig(value, label) {
     };
   }
 
-  throw new Error(`${label}.kind must be one of: tsc, script, steps`);
+  throw new Error(`${label}.kind must be one of: tsc, script, next, steps`);
 }
 
 export function finalizeBuildConfig(build, transform) {
@@ -61,6 +71,15 @@ export function finalizeBuildConfig(build, transform) {
       inputs: build.inputs.map((input) => transform(input)),
     };
   }
+  if (build.kind === "next") {
+    return {
+      ...build,
+      cwd: build.cwd ? transform(build.cwd) : build.cwd,
+      distDir: transform(build.distDir),
+      tsconfig: transform(build.tsconfig),
+      inputs: build.inputs.map((input) => transform(input)),
+    };
+  }
   return {
     ...build,
     inputs: build.inputs.map((input) => transform(input)),
@@ -104,6 +123,27 @@ export function buildConfigToPrepare(build) {
     };
   }
 
+  if (build.kind === "next") {
+    const inputs = build.inputs.length > 0 ? [...build.inputs] : defaultNextInputs(build);
+    return {
+      inputs,
+      steps: [
+        {
+          kind: "module",
+          specifier: "@elench/testkit/setup/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          cwd: build.cwd || undefined,
+          inputs,
+        },
+        {
+          kind: "command",
+          cmd: "./node_modules/.bin/next build",
+          cwd: build.cwd || undefined,
+          inputs,
+        },
+      ],
+    };
+  }
+
   const inputs = build.inputs.length > 0 ? [...build.inputs] : defaultTscInputs(build);
   const cmd = `./node_modules/.bin/tsc -p ${build.tsconfig} --outDir "{prepareDir}/${build.outDir}"`;
   return {
@@ -134,11 +174,35 @@ function sourceEntryToOutputPath(entry) {
 }
 
 function defaultTscInputs(build) {
-  const inputs = new Set([build.tsconfig, "package.json"]);
-  const normalizedEntry = String(build.entry).split(path.sep).join("/");
+  const inputs = new Set([
+    prefixConfiguredPath(build.cwd, build.tsconfig),
+    prefixConfiguredPath(build.cwd, "package.json"),
+  ]);
+  const normalizedEntry = prefixConfiguredPath(build.cwd, String(build.entry).split(path.sep).join("/"));
   const topLevelDir = normalizedEntry.includes("/") ? normalizedEntry.slice(0, normalizedEntry.indexOf("/")) : normalizedEntry;
   if (topLevelDir) {
     inputs.add(topLevelDir);
   }
   return [...inputs];
 }
+
+function defaultNextInputs(build) {
+  const inputs = new Set([
+    prefixConfiguredPath(build.cwd, build.tsconfig),
+    prefixConfiguredPath(build.cwd, "package.json"),
+    prefixConfiguredPath(build.cwd, "src"),
+    prefixConfiguredPath(build.cwd, "app"),
+    prefixConfiguredPath(build.cwd, "public"),
+    prefixConfiguredPath(build.cwd, "next.config.js"),
+    prefixConfiguredPath(build.cwd, "next.config.mjs"),
+    prefixConfiguredPath(build.cwd, "next.config.ts"),
+  ]);
+  return [...inputs];
+}
+
+function prefixConfiguredPath(cwd, value) {
+  const normalizedCwd = String(cwd || "").split(path.sep).join("/").replace(/^\.\/+/, "").replace(/\/+$/g, "");
+  const normalizedValue = String(value).split(path.sep).join("/").replace(/^\.\/+/, "");
+  if (!normalizedCwd || normalizedCwd === ".") return normalizedValue;
+  return `${normalizedCwd}/${normalizedValue}`.replace(/\/+/g, "/");
+}

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

@@ -56,6 +56,22 @@ describe("shared build config helpers", () => {
       inputs: ["frontend/package.json"],
     });
 
+    expect(
+      normalizeBuildConfig(
+        {
+          kind: "next",
+          cwd: "frontend",
+        },
+        "runtime.build"
+      )
+    ).toEqual({
+      kind: "next",
+      cwd: "frontend",
+      distDir: "dist",
+      tsconfig: "tsconfig.json",
+      inputs: [],
+    });
+
     expect(
       normalizeBuildConfig(
         {
@@ -77,5 +93,58 @@ describe("shared build config helpers", () => {
         },
       ],
     });
+
+    expect(
+      buildConfigToPrepare({
+        kind: "next",
+        cwd: "frontend",
+        distDir: "dist",
+        tsconfig: "tsconfig.json",
+        inputs: [],
+      })
+    ).toEqual({
+      inputs: [
+        "frontend/tsconfig.json",
+        "frontend/package.json",
+        "frontend/src",
+        "frontend/app",
+        "frontend/public",
+        "frontend/next.config.js",
+        "frontend/next.config.mjs",
+        "frontend/next.config.ts",
+      ],
+      steps: [
+        {
+          kind: "module",
+          specifier: "@elench/testkit/setup/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          cwd: "frontend",
+          inputs: [
+            "frontend/tsconfig.json",
+            "frontend/package.json",
+            "frontend/src",
+            "frontend/app",
+            "frontend/public",
+            "frontend/next.config.js",
+            "frontend/next.config.mjs",
+            "frontend/next.config.ts",
+          ],
+        },
+        {
+          kind: "command",
+          cmd: "./node_modules/.bin/next build",
+          cwd: "frontend",
+          inputs: [
+            "frontend/tsconfig.json",
+            "frontend/package.json",
+            "frontend/src",
+            "frontend/app",
+            "frontend/public",
+            "frontend/next.config.js",
+            "frontend/next.config.mjs",
+            "frontend/next.config.ts",
+          ],
+        },
+      ],
+    });
   });
 });

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "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.67",
+  "version": "0.1.68",
   "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.67"
+    "@elench/testkit-protocol": "0.1.68"
   },
   "private": false
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "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.67",
+  "version": "0.1.68",
   "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.67",
+  "version": "0.1.68",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "workspaces": [
@@ -64,10 +64,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@elench/next-analysis": "0.1.67",
-    "@elench/ts-analysis": "0.1.67",
-    "@elench/testkit-bridge": "0.1.67",
-    "@elench/testkit-protocol": "0.1.67",
+    "@elench/next-analysis": "0.1.68",
+    "@elench/ts-analysis": "0.1.68",
+    "@elench/testkit-bridge": "0.1.68",
+    "@elench/testkit-protocol": "0.1.68",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",