@elench/testkit 0.1.135 → 0.1.137

package/lib/local/lifecycle.mjs

@@ -0,0 +1,289 @@
+import fs from "fs";
+import path from "path";
+import { destroyRuntimeDatabase, cleanupOrphanedLocalInfrastructure } from "../database/index.mjs";
+import { killProcessTree } from "../runner/processes.mjs";
+import { isPidRunning } from "../runner/lifecycle.mjs";
+
+const SCHEMA_VERSION = 1;
+const ENVIRONMENTS_DIRNAME = path.join(".testkit", "environments");
+const TERMINATION_TIMEOUT_MS = 5_000;
+
+export function getEnvironmentDir(productDir, name) {
+  return path.join(productDir, ENVIRONMENTS_DIRNAME, name);
+}
+
+export function createLocalEnvironmentLifecycle(productDir, name, options = {}) {
+  const environmentDir = getEnvironmentDir(productDir, name);
+  const manifestPath = path.join(environmentDir, "manifest.json");
+  const abortController = new AbortController();
+  const state = {
+    schemaVersion: SCHEMA_VERSION,
+    kind: "local",
+    driver: options.driver || "host",
+    name,
+    productDir,
+    pid: process.pid,
+    status: "starting",
+    startedAt: new Date().toISOString(),
+    target: options.target || null,
+    runtimeDir: options.runtimeDir || null,
+    runtimeStateDirs: [],
+    portOffset: options.portOffset || 0,
+    data: options.data || "reuse",
+    services: [],
+  };
+  const managedProcesses = new Set();
+
+  function persist() {
+    fs.mkdirSync(environmentDir, { recursive: true });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(state, null, 2)}\n`);
+  }
+
+  function mutate(mutator) {
+    mutator(state);
+    persist();
+  }
+
+  const api = {
+    name,
+    environmentDir,
+    manifestPath,
+    signal: abortController.signal,
+    isStopRequested() {
+      return abortController.signal.aborted;
+    },
+    markRunning(extra = {}) {
+      mutate((draft) => {
+        draft.status = "running";
+        Object.assign(draft, extra);
+      });
+    },
+    requestStop(reason = "stopped") {
+      if (!abortController.signal.aborted) {
+        abortController.abort(new Error(`testkit local environment stopped (${reason})`));
+      }
+      for (const entry of managedProcesses) {
+        try {
+          entry.terminate?.();
+        } catch {
+          // Best-effort stop only.
+        }
+      }
+      mutate((draft) => {
+        draft.status = "stopping";
+        draft.stopReason = reason;
+      });
+    },
+    registerProcess(child, terminate) {
+      if (!child) return;
+      managedProcesses.add({ child, terminate });
+    },
+    unregisterProcess(childPid) {
+      for (const entry of managedProcesses) {
+        if (entry.child?.pid === childPid) managedProcesses.delete(entry);
+      }
+    },
+    registerService(config, child, cwd, terminate) {
+      api.registerProcess(child, terminate);
+      mutate((draft) => {
+        draft.services = draft.services.filter((service) => service.pid !== child.pid);
+        draft.services.push({
+          serviceName: config.name,
+          runtimeLabel: config.runtimeLabel,
+          command: config.testkit.local?.start || null,
+          cwd,
+          pid: child.pid,
+          processGroupId: child.pid,
+          baseUrl: config.testkit.local?.baseUrl || null,
+          readyUrl: config.testkit.local?.readyUrl || null,
+          ports: collectConfigPorts(config),
+          startedAt: new Date().toISOString(),
+        });
+        for (const runtimeConfig of config.testkit?.templateContext?.stateDirByService?.values?.() || []) {
+          pushUnique(draft.runtimeStateDirs, runtimeConfig);
+        }
+      });
+    },
+    unregisterService(childPid) {
+      api.unregisterProcess(childPid);
+      mutate((draft) => {
+        draft.services = draft.services.filter((service) => service.pid !== childPid);
+      });
+    },
+    setRuntimeState(runtimeConfigs) {
+      mutate((draft) => {
+        draft.runtimeStateDirs = [...new Set(runtimeConfigs.map((config) => config.stateDir).filter(Boolean))];
+      });
+    },
+    removeManifest() {
+      fs.rmSync(manifestPath, { force: true });
+      pruneEmptyDir(environmentDir);
+      pruneEmptyDir(path.dirname(environmentDir));
+    },
+    persist,
+  };
+
+  api.persist();
+  return api;
+}
+
+export function readLocalEnvironmentManifest(productDir, name) {
+  return readManifest(path.join(getEnvironmentDir(productDir, name), "manifest.json"));
+}
+
+export function listLocalEnvironmentManifests(productDir) {
+  const root = path.join(productDir, ENVIRONMENTS_DIRNAME);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => readManifest(path.join(root, entry.name, "manifest.json")))
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export async function stopLocalEnvironment(productDir, name, options = {}) {
+  const manifest = readLocalEnvironmentManifest(productDir, name);
+  if (!manifest) return null;
+  for (const service of [...(manifest.services || [])].reverse()) {
+    await terminateOwnedProcess(service);
+  }
+  if (options.removeRuntimeState) {
+    for (const stateDir of [...new Set(manifest.runtimeStateDirs || [])].sort((a, b) => b.length - a.length)) {
+      await destroyRuntimeDatabase({ productDir, stateDir });
+    }
+    if (manifest.runtimeDir) fs.rmSync(manifest.runtimeDir, { recursive: true, force: true });
+    const environmentDir = getEnvironmentDir(productDir, name);
+    fs.rmSync(environmentDir, { recursive: true, force: true });
+    pruneEmptyDir(path.dirname(environmentDir));
+    await cleanupOrphanedLocalInfrastructure(productDir);
+    return manifest;
+  }
+  const environmentDir = getEnvironmentDir(productDir, name);
+  fs.mkdirSync(environmentDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(environmentDir, "manifest.json"),
+    `${JSON.stringify({
+      ...manifest,
+      status: "stopped",
+      stoppedAt: new Date().toISOString(),
+      services: [],
+    }, null, 2)}\n`
+  );
+  await cleanupOrphanedLocalInfrastructure(productDir);
+  return manifest;
+}
+
+export async function cleanupStaleLocalEnvironments(productDir) {
+  const cleaned = [];
+  for (const manifest of listLocalEnvironmentManifests(productDir)) {
+    if (isLocalEnvironmentActive(manifest)) continue;
+    await stopLocalEnvironment(productDir, manifest.name, { removeRuntimeState: false });
+    cleaned.push(manifest);
+  }
+  return cleaned;
+}
+
+export function findLocalPortOwner(productDir, { host, port }) {
+  for (const manifest of listLocalEnvironmentManifests(productDir)) {
+    for (const service of manifest.services || []) {
+      for (const socket of service.ports || []) {
+        if (normalizeHost(socket.host) === normalizeHost(host) && Number(socket.port) === Number(port)) {
+          return {
+            manifest,
+            service,
+            active: isLocalServiceActive(service),
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+export function isLocalEnvironmentActive(manifest) {
+  if (manifest.driver === "kiln") return manifest.status === "running";
+  return (manifest.services || []).some(isLocalServiceActive);
+}
+
+export function formatLocalEnvironmentSummary(manifest) {
+  const ports = [
+    ...new Set(
+      (manifest.services || []).flatMap((service) =>
+        (service.ports || []).map((socket) => `${socket.host}:${socket.port}`)
+      )
+    ),
+  ];
+  return `${manifest.name}${ports.length > 0 ? ` ports=${ports.join(",")}` : ""}`;
+}
+
+function isLocalServiceActive(service) {
+  return isPidRunning(Number(service.processGroupId || service.pid));
+}
+
+async function terminateOwnedProcess(service) {
+  const pid = Number(service.processGroupId || service.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (!isPidRunning(pid)) return;
+  killProcessTree(pid, "SIGTERM");
+  const exited = await waitForPidExit(pid, TERMINATION_TIMEOUT_MS);
+  if (!exited) {
+    killProcessTree(pid, "SIGKILL");
+    await waitForPidExit(pid, TERMINATION_TIMEOUT_MS);
+  }
+}
+
+async function waitForPidExit(pid, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isPidRunning(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isPidRunning(pid);
+}
+
+function readManifest(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return parsed?.kind === "local" && parsed?.name ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function collectConfigPorts(config) {
+  const seen = new Set();
+  const ports = [];
+  for (const rawUrl of [config.testkit.local?.baseUrl, config.testkit.local?.readyUrl]) {
+    if (!rawUrl) continue;
+    try {
+      const parsed = new URL(rawUrl);
+      const host = normalizeHost(parsed.hostname);
+      const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+      const key = `${host}:${port}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      ports.push({ host, port });
+    } catch {
+      // Startup validation handles malformed URLs.
+    }
+  }
+  return ports;
+}
+
+function normalizeHost(host) {
+  if (!host || host === "localhost" || host === "::1") return "127.0.0.1";
+  return host;
+}
+
+function pushUnique(list, value) {
+  if (value && !list.includes(value)) list.push(value);
+}
+
+function pruneEmptyDir(dir) {
+  if (!dir || !fs.existsSync(dir)) return;
+  try {
+    if (fs.readdirSync(dir).length === 0) fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup only.
+  }
+}

package/lib/local/orchestrator.mjs

@@ -0,0 +1,343 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { loadConfigContext } from "../config/index.mjs";
+import { prepareDatabaseRuntime } from "../database/index.mjs";
+import { prepareRuntimeServices } from "../runner/runtime-preparation.mjs";
+import { resolveRuntimeConfigs } from "../runner/planning.mjs";
+import { startLocalServices } from "../runner/services.mjs";
+import { buildExecutionEnv, resolveRuntimeInstanceConfigs } from "../runner/template.mjs";
+import { readDatabaseUrl } from "../runner/state-io.mjs";
+import {
+  buildKilnLocalStatus,
+  kilnLocalDown,
+  kilnLocalEnv,
+  kilnLocalLogs,
+  kilnLocalShell,
+  kilnLocalUp,
+} from "./kiln-driver.mjs";
+import {
+  cleanupStaleLocalEnvironments,
+  createLocalEnvironmentLifecycle,
+  getEnvironmentDir,
+  isLocalEnvironmentActive,
+  listLocalEnvironmentManifests,
+  readLocalEnvironmentManifest,
+  stopLocalEnvironment,
+} from "./lifecycle.mjs";
+
+export async function localUp(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  const environment = resolveEnvironment(context, options);
+  if (environment.driver === "kiln") {
+    return kilnLocalUp(context, environment, options);
+  }
+  const existing = readLocalEnvironmentManifest(context.productDir, environment.name);
+  if (existing && isLocalEnvironmentActive(existing)) {
+    throw new Error(`Local environment "${environment.name}" is already running. Stop it with testkit local down ${environment.name}.`);
+  }
+  if (existing && environment.data === "rebuild") {
+    await stopLocalEnvironment(context.productDir, environment.name, { removeRuntimeState: true });
+  } else {
+    await cleanupStaleLocalEnvironments(context.productDir);
+  }
+
+  const runtimeDir = path.join(getEnvironmentDir(context.productDir, environment.name), "runtime");
+  fs.mkdirSync(runtimeDir, { recursive: true });
+
+  const runtimeConfigs = buildLocalRuntimeConfigs(context.configs, environment, runtimeDir);
+  const lifecycle = createLocalEnvironmentLifecycle(context.productDir, environment.name, {
+    target: environment.target,
+    runtimeDir,
+    data: environment.data,
+    portOffset: environment.portOffset,
+  });
+  lifecycle.setRuntimeState(runtimeConfigs);
+
+  const extraEnv = environment.env || {};
+  try {
+    for (const config of runtimeConfigs) {
+      await prepareDatabaseRuntime(config, { ...(options.setupOptions || {}) });
+    }
+    await prepareRuntimeServices(runtimeConfigs, { ...(options.setupOptions || {}), extraEnv });
+    await startLocalServices(runtimeConfigs, lifecycle, {
+      extraEnv,
+      reporter: options.reporter,
+      serviceLogFiles(config) {
+        const logsDir = path.join(getEnvironmentDir(context.productDir, environment.name), "logs");
+        return {
+          stdoutPath: path.join(logsDir, `${config.name}.stdout.log`),
+          stderrPath: path.join(logsDir, `${config.name}.stderr.log`),
+        };
+      },
+    });
+    lifecycle.markRunning({
+      target: environment.target,
+      runtimeDir,
+      runtimeServices: runtimeConfigs.map((config) => config.name),
+      endpoints: collectEndpoints(runtimeConfigs),
+    });
+    return buildLocalStatus(context.productDir, environment.name);
+  } catch (error) {
+    lifecycle.requestStop("startup-failed");
+    await stopLocalEnvironment(context.productDir, environment.name, { removeRuntimeState: environment.data === "rebuild" });
+    throw error;
+  }
+}
+
+export async function localDown(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  const name = normalizeEnvironmentName(options.name || "local");
+  const manifest = readLocalEnvironmentManifest(context.productDir, name);
+  if (manifest?.driver === "kiln") {
+    await kilnLocalDown(context, name, { destroyState: Boolean(options.destroyState) });
+    return buildKilnLocalStatus(context.productDir, name);
+  }
+  const stopped = await stopLocalEnvironment(context.productDir, name, {
+    removeRuntimeState: Boolean(options.destroyState),
+  });
+  return stopped
+    ? buildLocalStatus(context.productDir, name)
+    : { name, exists: false, lines: [`Local Environment: ${name}`, "  not found"] };
+}
+
+export async function localStatus(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  if (options.name) {
+    const name = normalizeEnvironmentName(options.name);
+    const manifest = readLocalEnvironmentManifest(context.productDir, name);
+    return manifest?.driver === "kiln" ? buildKilnLocalStatus(context.productDir, name) : buildLocalStatus(context.productDir, name);
+  }
+  return {
+    productDir: context.productDir,
+    environments: listLocalEnvironmentManifests(context.productDir).map((manifest) =>
+      manifest.driver === "kiln" ? buildKilnLocalStatus(context.productDir, manifest.name) : buildLocalStatus(context.productDir, manifest.name)
+    ),
+  };
+}
+
+export async function localEnv(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  const environment = resolveEnvironment(context, options);
+  const manifest = readLocalEnvironmentManifest(context.productDir, environment.name);
+  if (!manifest) throw new Error(`Local environment "${environment.name}" has not been started.`);
+  if (manifest.driver === "kiln") return kilnLocalEnv(context, environment.name, options);
+  const runtimeConfigs = buildLocalRuntimeConfigs(context.configs, environment, manifest.runtimeDir);
+  const serviceConfig = resolveService(runtimeConfigs, options.service || environment.target);
+  const env = buildServiceEnv(serviceConfig, environment.env);
+  return {
+    name: environment.name,
+    service: serviceConfig.name,
+    env,
+    lines: Object.entries(env)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, value]) => `${key}=${shellQuote(String(value))}`),
+  };
+}
+
+export async function localLogs(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  const name = normalizeEnvironmentName(options.name || "local");
+  const manifest = readLocalEnvironmentManifest(context.productDir, name);
+  if (!manifest) throw new Error(`Local environment "${name}" has not been started.`);
+  if (manifest.driver === "kiln") return kilnLocalLogs(context, name, options);
+  const logsDir = path.join(getEnvironmentDir(context.productDir, name), "logs");
+  const serviceNames = options.service
+    ? [options.service]
+    : [...new Set((manifest.services || []).map((service) => service.serviceName))].sort();
+  const lines = [];
+  for (const serviceName of serviceNames) {
+    for (const stream of ["stdout", "stderr"]) {
+      const filePath = path.join(logsDir, `${serviceName}.${stream}.log`);
+      if (!fs.existsSync(filePath)) continue;
+      lines.push(`==> ${serviceName}.${stream} <==`);
+      lines.push(...tailLines(fs.readFileSync(filePath, "utf8"), options.lines || 200));
+    }
+  }
+  return { name, lines };
+}
+
+export async function localShell(options = {}) {
+  const context = await loadConfigContext({ dir: options.dir });
+  const environment = resolveEnvironment(context, options);
+  const manifest = readLocalEnvironmentManifest(context.productDir, environment.name);
+  if (!manifest) throw new Error(`Local environment "${environment.name}" has not been started.`);
+  if (manifest.driver === "kiln") return kilnLocalShell(context, environment.name, options);
+  const runtimeConfigs = buildLocalRuntimeConfigs(context.configs, environment, manifest.runtimeDir);
+  const serviceConfig = resolveService(runtimeConfigs, options.service || environment.target);
+  const env = buildServiceEnv(serviceConfig, environment.env);
+  const command = options.command || [];
+  if (command.length === 0) throw new Error("testkit local shell requires a command after --");
+  return runShellCommand(command, {
+    cwd: serviceConfig.productDir,
+    env: { ...process.env, ...env },
+  });
+}
+
+export function buildLocalRuntimeConfigs(allConfigs, environment, runtimeDir) {
+  const configMap = new Map(allConfigs.map((config) => [config.name, config]));
+  const target = configMap.get(environment.target);
+  if (!target) {
+    const available = allConfigs.map((config) => config.name).join(", ");
+    throw new Error(`Service "${environment.target}" not found. Available: ${available}`);
+  }
+  const runtimeConfigs = resolveRuntimeConfigs(target, configMap);
+  return resolveRuntimeInstanceConfigs(runtimeConfigs, "local", runtimeDir, {
+    graphDirName: runtimeConfigs.map((config) => config.name).sort().join("__"),
+    portOffset: environment.portOffset || 0,
+    publicHost: environment.publicHost || null,
+  }).map((config) => applyLocalEnvironmentConfig(config, environment));
+}
+
+export function buildLocalStatus(productDir, name) {
+  const manifest = readLocalEnvironmentManifest(productDir, name);
+  if (!manifest) return { name, exists: false, active: false, services: [], lines: [`Local Environment: ${name}`, "  not found"] };
+  const active = isLocalEnvironmentActive(manifest);
+  const services = (manifest.services || []).map((service) => ({
+    serviceName: service.serviceName,
+    pid: service.pid,
+    active: serviceIsActive(service),
+    baseUrl: service.baseUrl,
+    readyUrl: service.readyUrl,
+    ports: service.ports || [],
+  }));
+  const lines = [
+    `Local Environment: ${name}`,
+    `  status: ${active ? "running" : manifest.status || "stopped"}`,
+    `  target: ${manifest.target || "unknown"}`,
+    `  state: ${path.relative(productDir, getEnvironmentDir(productDir, name))}`,
+  ];
+  if (services.length === 0) {
+    lines.push("  services: none");
+  } else {
+    lines.push("  services:");
+    for (const service of services) {
+      const url = service.baseUrl ? ` url=${service.baseUrl}` : "";
+      lines.push(`    ${service.serviceName}: ${service.active ? "running" : "stale"} pid=${service.pid}${url}`);
+    }
+  }
+  return {
+    name,
+    exists: true,
+    active,
+    manifest,
+    services,
+    lines,
+  };
+}
+
+export function resolveEnvironment(context, options = {}) {
+  const name = normalizeEnvironmentName(options.name || "local");
+  const configured = context.environments[name] || null;
+  const target = options.service || configured?.target || inferDefaultTarget(context.configs);
+  const requestedDriver = process.env.TESTKIT_LOCAL_DRIVER || options.driver || configured?.driver || "host";
+  const driver = process.env.TESTKIT_KILN_INNER === "1" ? "host" : requestedDriver;
+  return {
+    name,
+    kind: "local",
+    driver,
+    target,
+    data: options.rebuild ? "rebuild" : options.reset ? "reset" : configured?.data || "reuse",
+    portOffset: Number(options.portOffset ?? configured?.portOffset ?? 0),
+    env: { ...(configured?.env || {}) },
+    kiln: configured?.kiln || null,
+    publicHost: process.env.TESTKIT_PUBLIC_HOST || configured?.publicHost || null,
+  };
+}
+
+function inferDefaultTarget(configs) {
+  if (configs.length === 1) return configs[0].name;
+  const runnable = configs.filter((config) => config.testkit.local);
+  if (runnable.length === 1) return runnable[0].name;
+  const available = configs.map((config) => config.name).join(", ");
+  throw new Error(`Multiple services available. Configure environments.local.target or pass --service. Available: ${available}`);
+}
+
+function applyLocalEnvironmentConfig(config, environment) {
+  const database = config.testkit.database
+    ? {
+        ...config.testkit.database,
+        reset: environment.data === "reuse" ? false : true,
+      }
+    : config.testkit.database;
+  return {
+    ...config,
+    testkit: {
+      ...config.testkit,
+      mode: "local",
+      localEnvironmentName: environment.name,
+      database,
+    },
+  };
+}
+
+function resolveService(runtimeConfigs, serviceName) {
+  const serviceConfig = runtimeConfigs.find((config) => config.name === serviceName);
+  if (!serviceConfig) {
+    const available = runtimeConfigs.map((config) => config.name).join(", ");
+    throw new Error(`Service "${serviceName}" is not in this local environment. Available: ${available}`);
+  }
+  return serviceConfig;
+}
+
+function buildServiceEnv(config, extraEnv = {}) {
+  const env = buildExecutionEnv(config, { ...(config.testkit.local?.env || {}), ...(extraEnv || {}) }, process.env);
+  const databaseUrl = readDatabaseUrl(config.stateDir);
+  if (databaseUrl) env.DATABASE_URL = databaseUrl;
+  return env;
+}
+
+function collectEndpoints(runtimeConfigs) {
+  return Object.fromEntries(
+    runtimeConfigs
+      .filter((config) => config.testkit.local?.baseUrl)
+      .map((config) => [config.name, config.testkit.local.baseUrl])
+  );
+}
+
+function normalizeEnvironmentName(name) {
+  const normalized = String(name || "").trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(normalized)) {
+    throw new Error(`Environment name "${name}" must contain only letters, numbers, underscores, or dashes`);
+  }
+  return normalized;
+}
+
+function serviceIsActive(service) {
+  try {
+    process.kill(Number(service.processGroupId || service.pid), 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function tailLines(text, count) {
+  return text.split(/\r?\n/).filter(Boolean).slice(-count);
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_/:.,@%+=-]*$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function runShellCommand(command, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command[0], command.slice(1), {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}