@elench/testkit 0.1.48 → 0.1.50

package/README.md

@@ -119,7 +119,9 @@ export default defineTestkitSetup({
       ...nextService({
         cwd: "frontend",
         port: 3000,
+        start: "./node_modules/.bin/next start --port {port}",
         env: {
+          NEXT_DIST_DIR: "{prepareDir}/dist",
           NEXT_PUBLIC_API_URL: "{baseUrl:api}",
         },
       }),
@@ -127,6 +129,11 @@ export default defineTestkitSetup({
       envFiles: ["frontend/.env.testkit"],
       runtime: {
         instances: 1,
+        maxConcurrentTasks: 2,
+        prepare: {
+          inputs: ["frontend/src", "frontend/public", "frontend/package.json"],
+          steps: [commandStep("npm run build", { cwd: "frontend" })],
+        },
       },
     }),
     billing: service({
@@ -157,6 +164,7 @@ for:
 - multi-service graphs
 - local runtime instance counts
 - per-runtime concurrent task caps
+- one-time runtime preparation steps for stable shared servers
 - local DB binding configuration
 - template database migrate / seed / verify stages
 - template schema snapshot capture
@@ -167,6 +175,12 @@ for:
 - repo-declared suite/file skip policies with explicit reasons
 - telemetry upload configuration
 
+`runtime.prepare` is the generic build-once hook for shared runtimes. It runs
+once per runtime generation before local services start, fingerprints declared
+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.
+
 If `reporting.knownFailuresFile` is configured, `testkit` enriches
 `.testkit/results/latest.json` and `testkit.status.json` with:
 

package/lib/config/index.mjs

@@ -212,7 +212,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (detectNextApp(absoluteCwd)) {
     return {
       cwd,
-      start: "exec ./node_modules/.bin/next dev -p {port}",
+      start: "./node_modules/.bin/next dev -p {port}",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}",
@@ -223,7 +223,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (fs.existsSync(path.join(absoluteCwd, "cmd", "server"))) {
     return {
       cwd,
-      start: "exec go run ./cmd/server",
+      start: "go run ./cmd/server",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}/health",
@@ -234,7 +234,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (fs.existsSync(path.join(absoluteCwd, "package.json")) && fs.existsSync(path.join(absoluteCwd, "src"))) {
     return {
       cwd,
-      start: "exec ./node_modules/.bin/tsx watch src/index.ts",
+      start: "./node_modules/.bin/tsx watch src/index.ts",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}/health",
@@ -279,6 +279,10 @@ function normalizeRuntimeConfig(value, serviceName) {
     return {
       instances: 1,
       maxConcurrentTasks: Number.POSITIVE_INFINITY,
+      prepare: {
+        inputs: [],
+        steps: [],
+      },
     };
   }
 
@@ -291,6 +295,27 @@ function normalizeRuntimeConfig(value, serviceName) {
       value.maxConcurrentTasks,
       `Service "${serviceName}" runtime.maxConcurrentTasks`
     ),
+    prepare: normalizeRuntimePrepareConfig(value.prepare, serviceName),
+  };
+}
+
+function normalizeRuntimePrepareConfig(value, serviceName) {
+  if (value == null) {
+    return {
+      inputs: [],
+      steps: [],
+    };
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`Service "${serviceName}" runtime.prepare must be an object`);
+  }
+
+  return {
+    inputs: normalizeTemplateInputs(value.inputs, `Service "${serviceName}" runtime.prepare`),
+    steps: normalizeTemplateLifecycleSteps(
+      value.steps,
+      `Service "${serviceName}" runtime.prepare.steps`
+    ),
   };
 }
 
@@ -751,6 +776,36 @@ function validateServiceConfig({
   for (const input of database?.template?.inputs || []) {
     ensureExistingPath(productDir, input, `Service "${name}" database.template input`);
   }
+  for (const step of runtime.prepare?.steps || []) {
+    if (step.cwd) {
+      ensureExistingPath(productDir, step.cwd, `Service "${name}" runtime.prepare step cwd`);
+    }
+    if (step.kind === "sql-file") {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        step.path,
+        `Service "${name}" runtime.prepare sql file`
+      );
+    }
+    if (step.kind === "module") {
+      const { modulePath } = parseModuleSpecifier(step.specifier);
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        modulePath,
+        `Service "${name}" runtime.prepare module`
+      );
+    }
+    for (const input of step.inputs || []) {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        input,
+        `Service "${name}" runtime.prepare step input`
+      );
+    }
+  }
+  for (const input of runtime.prepare?.inputs || []) {
+    ensureExistingPath(productDir, input, `Service "${name}" runtime.prepare input`);
+  }
 }
 
 function ensureExistingPath(productDir, relativePath, label) {

package/lib/database/index.mjs

@@ -33,6 +33,8 @@ const LOCAL_PASSWORD = "testkit";
 const LOCAL_ADMIN_DB = "postgres";
 const LOCAL_READY_TIMEOUT_MS = 60_000;
 const LOCAL_POLL_INTERVAL_MS = 1_000;
+const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
+const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
 export async function prepareDatabaseRuntime(config) {
   const db = config.testkit.database;
@@ -398,18 +400,78 @@ async function cloneDatabaseFromTemplate(infra, dbName, templateDbName) {
 }
 
 async function dropDatabaseIfExists(infra, dbName) {
-  await runAdminQuery(infra, [
-    "-c",
-    [
-      `SELECT pg_terminate_backend(pid)`,
-      `FROM pg_stat_activity`,
-      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
-    ].join(" "),
-  ]);
-  await runAdminQuery(infra, [
-    "-c",
-    `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}"`,
-  ]);
+  await dropDatabaseWithForceOrDrain(infra, dbName);
+}
+
+export async function dropDatabaseWithForceOrDrain(infra, dbName, hooks = {}) {
+  const runAdminQueryFn = hooks.runAdminQuery || runAdminQuery;
+  const databaseExistsFn = hooks.databaseExists || databaseExists;
+  const sleepFn = hooks.sleep || sleep;
+
+  try {
+    await runAdminQueryFn(infra, [
+      "-c",
+      `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}" WITH (FORCE)`,
+    ]);
+    return;
+  } catch (error) {
+    if (!isUnsupportedForceDropError(error)) {
+      throw error;
+    }
+  }
+
+  if (!(await databaseExistsFn(infra, dbName))) {
+    return;
+  }
+
+  let restoreConnections = false;
+  try {
+    await runAdminQueryFn(infra, [
+      "-c",
+      `ALTER DATABASE "${escapeIdentifier(dbName)}" WITH ALLOW_CONNECTIONS false`,
+    ]);
+    restoreConnections = true;
+    await waitForDatabaseConnectionsToDrain(infra, dbName, {
+      runAdminQuery: runAdminQueryFn,
+      sleep: sleepFn,
+    });
+    await runAdminQueryFn(infra, [
+      "-c",
+      `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}"`,
+    ]);
+    restoreConnections = false;
+  } finally {
+    if (restoreConnections && (await databaseExistsFn(infra, dbName))) {
+      await runAdminQueryFn(infra, [
+        "-c",
+        `ALTER DATABASE "${escapeIdentifier(dbName)}" WITH ALLOW_CONNECTIONS true`,
+      ]).catch(() => {
+        // Best-effort restoration for failed fallback drops.
+      });
+    }
+  }
+}
+
+export async function waitForDatabaseConnectionsToDrain(infra, dbName, hooks = {}) {
+  const runAdminQueryFn = hooks.runAdminQuery || runAdminQuery;
+  const sleepFn = hooks.sleep || sleep;
+  const now = hooks.now || Date.now;
+  const timeoutMs = hooks.timeoutMs ?? LOCAL_DROP_DATABASE_TIMEOUT_MS;
+  const deadline = now() + timeoutMs;
+
+  while (true) {
+    await terminateDatabaseConnections(infra, dbName, runAdminQueryFn);
+    const remainingConnections = await countDatabaseConnections(infra, dbName, runAdminQueryFn);
+    if (remainingConnections === 0) {
+      return;
+    }
+    if (now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for database "${dbName}" connections to close (${remainingConnections} remaining)`
+      );
+    }
+    await sleepFn(LOCAL_DROP_DATABASE_POLL_INTERVAL_MS);
+  }
 }
 
 async function runAdminQuery(infra, args) {
@@ -431,6 +493,37 @@ async function runAdminQuery(infra, args) {
   return stdout;
 }
 
+async function terminateDatabaseConnections(infra, dbName, runAdminQueryFn) {
+  await runAdminQueryFn(infra, [
+    "-c",
+    [
+      "SELECT pg_terminate_backend(pid)",
+      "FROM pg_stat_activity",
+      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
+    ].join(" "),
+  ]);
+}
+
+async function countDatabaseConnections(infra, dbName, runAdminQueryFn) {
+  const result = await runAdminQueryFn(infra, [
+    "-tAc",
+    [
+      "SELECT COUNT(*)",
+      "FROM pg_stat_activity",
+      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
+    ].join(" "),
+  ]);
+  return Number.parseInt(result.trim(), 10) || 0;
+}
+
+function isUnsupportedForceDropError(error) {
+  const text = `${error?.shortMessage || ""}\n${error?.stderr || ""}\n${error?.stdout || ""}\n${error?.message || ""}`;
+  return (
+    text.includes('syntax error at or near "WITH"') ||
+    text.includes('option "force"')
+  );
+}
+
 async function computeTemplateFingerprint(config) {
   return computeTemplateFingerprintModel(config);
 }

package/lib/database/index.test.mjs

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import {
+  dropDatabaseWithForceOrDrain,
+  waitForDatabaseConnectionsToDrain,
+} from "./index.mjs";
+
+describe("database lifecycle helpers", () => {
+  it("uses DROP DATABASE ... WITH (FORCE) when supported", async () => {
+    const calls = [];
+
+    await dropDatabaseWithForceOrDrain(
+      { containerName: "pg", password: "pw", user: "user" },
+      "demo",
+      {
+        async runAdminQuery(_infra, args) {
+          calls.push(args);
+          return "";
+        },
+      }
+    );
+
+    expect(calls).toEqual([["-c", 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)']]);
+  });
+
+  it("falls back to draining connections when forced drop is unsupported", async () => {
+    const calls = [];
+    const counts = ["2", "0"];
+
+    await dropDatabaseWithForceOrDrain(
+      { containerName: "pg", password: "pw", user: "user" },
+      "demo",
+      {
+        async runAdminQuery(_infra, args) {
+          calls.push(args);
+          if (args[1] === 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)') {
+            const error = new Error('syntax error at or near "WITH"');
+            error.stderr = 'ERROR: syntax error at or near "WITH"';
+            throw error;
+          }
+          if (args[0] === "-tAc") {
+            return counts.shift() || "0";
+          }
+          return "";
+        },
+        async databaseExists() {
+          return true;
+        },
+        async sleep() {},
+      }
+    );
+
+    expect(calls).toEqual([
+      ["-c", 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)'],
+      ["-c", 'ALTER DATABASE "demo" WITH ALLOW_CONNECTIONS false'],
+      [
+        "-c",
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-tAc",
+        "SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-c",
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-tAc",
+        "SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      ["-c", 'DROP DATABASE IF EXISTS "demo"'],
+    ]);
+  });
+
+  it("times out clearly while waiting for lingering connections to drain", async () => {
+    let now = 0;
+    await expect(() =>
+      waitForDatabaseConnectionsToDrain(
+        { containerName: "pg", password: "pw", user: "user" },
+        "demo",
+        {
+          async runAdminQuery(_infra, args) {
+            if (args[0] === "-tAc") return "1";
+            return "";
+          },
+          async sleep() {
+            now += 10;
+          },
+          now: () => now,
+          timeoutMs: 20,
+        }
+      )
+    ).rejects.toThrow(/Timed out waiting for database "demo" connections to close/);
+  });
+});

package/lib/database/template-steps.mjs

@@ -1,17 +1,11 @@
-import crypto from "crypto";
 import fs from "fs";
 import path from "path";
-import { build } from "esbuild";
-import { execa, execaCommand } from "execa";
-import { fileURLToPath, pathToFileURL } from "url";
-import { resolveServiceCwd } from "../config/index.mjs";
+import { execa } from "execa";
 import { buildExecutionEnv } from "../runner/template.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");
+import {
+  collectConfiguredInputs,
+  runConfiguredSteps,
+} from "../runner/template-steps.mjs";
 
 export async function runTemplateStage(config, stageName, databaseUrl) {
   const steps = config.testkit.database?.template?.[stageName] || [];
@@ -22,32 +16,20 @@ export async function runTemplateStage(config, stageName, databaseUrl) {
     DATABASE_URL: databaseUrl,
   };
 
-  for (const [index, step] of steps.entries()) {
-    const label = `template:${stageName}:${config.name}:${index + 1}`;
-    console.log(`\n── ${label} ──`);
-    await runTemplateStep(config, stageName, step, env);
-  }
+  await runConfiguredSteps({
+    config,
+    steps,
+    env,
+    labelPrefix: `template:${stageName}`,
+  });
 }
 
 export function collectTemplateInputs(productDir, template = {}) {
-  const inputs = new Set();
-  for (const input of template.inputs || []) {
-    inputs.add(resolveTemplatePath(productDir, null, input));
-  }
-  for (const stageName of ["migrate", "seed", "verify"]) {
-    for (const step of template[stageName] || []) {
-      if (step.kind === "sql-file") {
-        inputs.add(resolveTemplatePath(productDir, step.cwd, step.path));
-      }
-      if (step.kind === "module") {
-        inputs.add(resolveTemplatePath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath));
-      }
-      for (const input of step.inputs || []) {
-        inputs.add(resolveTemplatePath(productDir, step.cwd, input));
-      }
-    }
-  }
-  return [...inputs].sort();
+  const steps = ["migrate", "seed", "verify"].flatMap((stageName) => template[stageName] || []);
+  return collectConfiguredInputs(productDir, {
+    inputs: template.inputs || [],
+    steps,
+  });
 }
 
 export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
@@ -55,21 +37,25 @@ export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
   const absoluteOutputPath = path.resolve(config.productDir, outputPath);
   fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
 
-  await execa("pg_dump", [
-    "--schema-only",
-    "--no-owner",
-    "--no-privileges",
-    "--file",
-    absoluteOutputPath,
-    templateDbUrl,
-  ], {
-    cwd: config.productDir,
-    env: {
-      ...buildExecutionEnv(config, {}, process.env),
-      DATABASE_URL: templateDbUrl,
-    },
-    stdio: "inherit",
-  });
+  await execa(
+    "pg_dump",
+    [
+      "--schema-only",
+      "--no-owner",
+      "--no-privileges",
+      "--file",
+      absoluteOutputPath,
+      templateDbUrl,
+    ],
+    {
+      cwd: config.productDir,
+      env: {
+        ...buildExecutionEnv(config, {}, process.env),
+        DATABASE_URL: templateDbUrl,
+      },
+      stdio: "inherit",
+    }
+  );
 
   sanitizeSnapshotFile(absoluteOutputPath);
   return absoluteOutputPath;
@@ -86,147 +72,3 @@ function sanitizeSnapshotFile(filePath) {
     fs.writeFileSync(filePath, sanitized);
   }
 }
-
-async function runTemplateStep(config, stageName, step, env) {
-  if (step.kind === "command") {
-    await execaCommand(step.cmd, {
-      cwd: resolveTemplateCwd(config.productDir, step.cwd),
-      env,
-      stdio: "inherit",
-      shell: true,
-    });
-    return;
-  }
-
-  if (step.kind === "sql-file") {
-    await execa("psql", [
-      env.DATABASE_URL,
-      "-v",
-      "ON_ERROR_STOP=1",
-      "-X",
-      "-f",
-      resolveTemplatePath(config.productDir, step.cwd, step.path),
-    ], {
-      cwd: resolveTemplateCwd(config.productDir, step.cwd),
-      env,
-      stdio: "inherit",
-    });
-    return;
-  }
-
-  if (step.kind === "module") {
-    const moduleRef = await loadTemplateModule(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}"`
-      );
-    }
-
-    await withProcessContext(
-      resolveTemplateCwd(config.productDir, step.cwd),
-      env,
-      async () => {
-        await fn({
-          productDir: config.productDir,
-          cwd: resolveTemplateCwd(config.productDir, step.cwd),
-          serviceName: config.name,
-          stage: stageName,
-          databaseUrl: env.DATABASE_URL,
-          env: { ...env },
-          runtimeId: config.runtimeId || null,
-          stateDir: config.stateDir,
-        });
-      }
-    );
-    return;
-  }
-
-  throw new Error(`Unsupported template step kind "${step.kind}"`);
-}
-
-function resolveTemplateCwd(productDir, stepCwd) {
-  return resolveServiceCwd(productDir, stepCwd || ".");
-}
-
-function resolveTemplatePath(productDir, stepCwd, targetPath) {
-  return path.resolve(resolveTemplateCwd(productDir, stepCwd), targetPath);
-}
-
-async function loadTemplateModule(productDir, step) {
-  const { modulePath } = parseModuleSpecifier(step.specifier);
-  const absoluteModulePath = resolveTemplatePath(productDir, step.cwd, modulePath);
-  const bundleDir = path.join(productDir, ".testkit", "_template-steps");
-  fs.mkdirSync(bundleDir, { recursive: true });
-
-  const cacheKey = buildModuleCacheKey(absoluteModulePath);
-  const outputFile = path.join(bundleDir, `${path.basename(modulePath).replace(/\W+/g, "-")}-${cacheKey.slice(0, 12)}.mjs`);
-
-  await build({
-    absWorkingDir: productDir,
-    bundle: true,
-    entryPoints: [absoluteModulePath],
-    format: "esm",
-    legalComments: "none",
-    outfile: outputFile,
-    platform: "node",
-    sourcemap: "inline",
-    target: "es2020",
-    plugins: [testkitAliasPlugin()],
-  });
-
-  return import(`${pathToFileURL(outputFile).href}?v=${cacheKey}`);
-}
-
-function buildModuleCacheKey(modulePath) {
-  const content = fs.readFileSync(modulePath, "utf8");
-  return crypto.createHash("sha256").update(modulePath).update("\0").update(content).digest("hex");
-}
-
-function testkitAliasPlugin() {
-  return {
-    name: "testkit-template-step-alias",
-    setup(buildApi) {
-      buildApi.onResolve({ filter: /^@elench\/testkit(?:\/.*)?$/ }, (args) => ({
-        namespace: "file",
-        path: resolvePackageSubpath(args.path),
-      }));
-    },
-  };
-}
-
-function resolvePackageSubpath(specifier) {
-  const subpath = specifier.slice("@elench/testkit".length);
-  if (!subpath) return ROOT_ENTRY;
-  if (subpath === "/setup") return SETUP_ENTRY;
-  if (subpath === "/runtime") return RUNTIME_ENTRY;
-  if (subpath === "/known-failures") return KNOWN_FAILURES_ENTRY;
-
-  throw new Error(`Unsupported @elench/testkit import "${specifier}" while loading template step`);
-}
-
-function parseModuleSpecifier(specifier) {
-  const [modulePath, exportName] = String(specifier).split("#", 2);
-  return {
-    modulePath,
-    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/runner/processes.mjs

@@ -1,8 +1,22 @@
 import { spawn } from "child_process";
 
+export function normalizeServiceStartCommand(command) {
+  if (typeof command !== "string") {
+    throw new Error("Service start command must be a string");
+  }
+
+  const trimmed = command.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Service start command must not be empty");
+  }
+
+  return trimmed.replace(/^exec\s+/u, "");
+}
+
 export function startDetachedCommand(command, cwd, env) {
+  const normalizedCommand = normalizeServiceStartCommand(command);
   if (process.platform === "win32") {
-    return spawn(command, {
+    return spawn(normalizedCommand, {
       cwd,
       env,
       detached: true,
@@ -12,7 +26,7 @@ export function startDetachedCommand(command, cwd, env) {
   }
 
   const shell = process.env.SHELL || "/bin/sh";
-  return spawn(shell, ["-lc", `exec ${command}`], {
+  return spawn(shell, ["-lc", `exec ${normalizedCommand}`], {
     cwd,
     env,
     detached: true,

package/lib/runner/processes.test.mjs

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { normalizeServiceStartCommand } from "./processes.mjs";
+
+describe("runner processes", () => {
+  it("strips a single leading exec prefix for backward compatibility", () => {
+    expect(normalizeServiceStartCommand("exec node server.mjs")).toBe("node server.mjs");
+    expect(normalizeServiceStartCommand("  exec ./node_modules/.bin/next dev -p {port}  ")).toBe(
+      "./node_modules/.bin/next dev -p {port}"
+    );
+  });
+
+  it("leaves plain commands unchanged", () => {
+    expect(normalizeServiceStartCommand("node server.mjs")).toBe("node server.mjs");
+  });
+
+  it("rejects empty commands", () => {
+    expect(() => normalizeServiceStartCommand("   ")).toThrow(
+      /Service start command must not be empty/
+    );
+  });
+});