@elench/testkit 0.1.136 → 0.1.137

package/lib/local/kiln-driver.mjs

@@ -0,0 +1,544 @@
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execa } from "execa";
+import { KilnClient } from "../kiln/client.mjs";
+import {
+  createLocalEnvironmentLifecycle,
+  getEnvironmentDir,
+  isLocalEnvironmentActive,
+  readLocalEnvironmentManifest,
+} from "./lifecycle.mjs";
+
+const DEFAULT_REMOTE_PRODUCT_DIR = "/workspace/testkit-local";
+const BOOTSTRAP_MANIFEST_PATH = ".testkit/kiln/bootstrap-manifest.json";
+const DEFAULT_RSYNC_EXCLUDES = [
+  ".git/",
+  "node_modules/",
+  "frontend/node_modules/",
+  ".next/",
+  "frontend/.next/",
+  "dist/",
+  "coverage/",
+  "playwright-report/",
+  ".testkit/kiln/packages/",
+  ".testkit/results/",
+];
+
+export async function kilnLocalUp(context, environment, options = {}) {
+  const vmConfig = normalizeVMConfig(environment);
+  const remoteProductDir = environment.kiln?.workspace?.remotePath || DEFAULT_REMOTE_PRODUCT_DIR;
+  const client = new KilnClient(environment.kiln?.api || {});
+  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}.`);
+  }
+  const lifecycle = createLocalEnvironmentLifecycle(context.productDir, environment.name, {
+    target: environment.target,
+    data: environment.data,
+    portOffset: environment.portOffset,
+    driver: "kiln",
+  });
+  let ssh = null;
+
+  try {
+    const network = await ensureNetwork(client, environment);
+    let vm = await ensureVM(client, vmConfig, network?.id || "");
+    vm = await ensureStarted(client, vm.name);
+    vm = await waitForVMReady(client, vm.name);
+
+    if (network && vm.network_id !== network.id) {
+      if (vm.state !== "stopped") {
+        await client.stopVM(vm.name);
+        await waitForVMState(client, vm.name, "stopped");
+      }
+      vm = await client.attachVMNetwork(vm.name, network.id);
+      vm = await ensureStarted(client, vm.name);
+      vm = await waitForVMReady(client, vm.name);
+    }
+
+    const targetHost = vm.private_ip || vm.ip;
+    if (!targetHost) throw new Error(`Kiln VM ${vm.name} has no reachable IP`);
+    ssh = await prepareSSH(client, vm);
+    await waitForSSHReady(ssh, vm.name);
+    await syncWorkspace({ ssh, productDir: context.productDir, remoteProductDir, environment });
+    await bootstrapRemoteWorkspace({ ssh, context, remoteProductDir });
+
+    const remote = await remoteTestkit(ssh, remoteProductDir, [
+      "local",
+      "up",
+      environment.name,
+      ...(options.service ? ["--service", options.service] : []),
+      ...(environment.data === "reset" ? ["--reset"] : []),
+      ...(environment.data === "rebuild" ? ["--rebuild"] : []),
+      ...(environment.portOffset ? ["--port-offset", String(environment.portOffset)] : []),
+    ], { TESTKIT_PUBLIC_HOST: targetHost });
+    if (remote.exitCode !== 0) {
+      throw new Error(`remote testkit local up failed\n${remote.stdout}${remote.stderr}`);
+    }
+
+    const status = await remoteLocalStatus(ssh, remoteProductDir, environment.name);
+    lifecycle.markRunning({
+      driver: "kiln",
+      target: environment.target,
+      remoteProductDir,
+      kiln: {
+        api: pickAPIConfig(environment.kiln?.api || {}),
+        vm: pickVM(vm),
+        network: network ? { id: network.id, name: network.name, cidr: network.cidr } : null,
+      },
+      endpoints: rewriteEndpoints(status?.manifest?.endpoints || {}, targetHost),
+      remoteStatus: status?.manifest || null,
+    });
+    return buildKilnLocalStatus(context.productDir, environment.name);
+  } catch (error) {
+    lifecycle.requestStop("startup-failed");
+    throw error;
+  } finally {
+    ssh?.cleanup?.();
+  }
+}
+
+export async function kilnLocalDown(context, name, options = {}) {
+  const manifest = readLocalEnvironmentManifest(context.productDir, name);
+  if (!manifest) return null;
+  if (!manifest.kiln?.vm?.name) {
+    writeKilnManifest(context.productDir, name, {
+      ...manifest,
+      status: "stopped",
+      stoppedAt: new Date().toISOString(),
+      services: [],
+    });
+    return manifest;
+  }
+  const ssh = await sshFromManifest(manifest);
+  const args = ["local", "down", name, ...(options.destroyState ? ["--destroy-state"] : [])];
+  try {
+    const result = await remoteTestkit(ssh, manifest.remoteProductDir, args);
+    if (result.exitCode !== 0) {
+      throw new Error(`remote testkit local down failed\n${result.stdout}${result.stderr}`);
+    }
+    writeKilnManifest(context.productDir, name, {
+      ...manifest,
+      status: "stopped",
+      stoppedAt: new Date().toISOString(),
+      services: [],
+    });
+    return manifest;
+  } finally {
+    ssh.cleanup?.();
+  }
+}
+
+export async function kilnLocalLogs(context, name, options = {}) {
+  const manifest = requireKilnManifest(context.productDir, name);
+  const ssh = await sshFromManifest(manifest);
+  const args = ["local", "logs", name, ...(options.service ? ["--service", options.service] : []), "--lines", String(options.lines || 200)];
+  try {
+    const result = await remoteTestkit(ssh, manifest.remoteProductDir, args);
+    if (result.exitCode !== 0) throw new Error(`remote testkit local logs failed\n${result.stdout}${result.stderr}`);
+    return { name, lines: splitOutput(result) };
+  } finally {
+    ssh.cleanup?.();
+  }
+}
+
+export async function kilnLocalEnv(context, name, options = {}) {
+  const manifest = requireKilnManifest(context.productDir, name);
+  const ssh = await sshFromManifest(manifest);
+  const args = ["local", "env", name, ...(options.service ? ["--service", options.service] : [])];
+  try {
+    const result = await remoteTestkit(ssh, manifest.remoteProductDir, args);
+    if (result.exitCode !== 0) throw new Error(`remote testkit local env failed\n${result.stdout}${result.stderr}`);
+    return { name, service: options.service || manifest.target, lines: splitOutput(result) };
+  } finally {
+    ssh.cleanup?.();
+  }
+}
+
+export async function kilnLocalShell(context, name, options = {}) {
+  const manifest = requireKilnManifest(context.productDir, name);
+  const ssh = await sshFromManifest(manifest);
+  const command = options.command || [];
+  if (command.length === 0) throw new Error("testkit local shell requires a command after --");
+  try {
+    return await remoteTestkit(ssh, manifest.remoteProductDir, [
+      "local",
+      "shell",
+      name,
+      ...(options.service ? ["--service", options.service] : []),
+      "--",
+      ...command,
+    ]);
+  } finally {
+    ssh.cleanup?.();
+  }
+}
+
+export function buildKilnLocalStatus(productDir, name) {
+  const manifest = readLocalEnvironmentManifest(productDir, name);
+  if (!manifest) return { name, exists: false, active: false, lines: [`Local Environment: ${name}`, "  not found"] };
+  const endpoints = manifest.endpoints || {};
+  const lines = [
+    `Local Environment: ${name}`,
+    `  status: ${manifest.status || "unknown"}`,
+    `  driver: kiln`,
+    `  target: ${manifest.target || "unknown"}`,
+    `  vm: ${manifest.kiln?.vm?.name || "unknown"} ${manifest.kiln?.vm?.private_ip || manifest.kiln?.vm?.ip || ""}`.trimEnd(),
+    `  remote: ${manifest.remoteProductDir || "unknown"}`,
+  ];
+  if (Object.keys(endpoints).length > 0) {
+    lines.push("  endpoints:");
+    for (const [service, url] of Object.entries(endpoints)) lines.push(`    ${service}: ${url}`);
+  }
+  return { name, exists: true, active: manifest.status === "running", manifest, services: [], lines };
+}
+
+async function ensureNetwork(client, environment) {
+  const networkConfig = environment.kiln?.network;
+  if (!networkConfig) return null;
+  if (networkConfig.id) {
+    const network = { id: networkConfig.id, name: networkConfig.name || networkConfig.id };
+    await attachExistingVMs(client, network, networkConfig.attachExistingVMs || []);
+    return network;
+  }
+  const name = networkConfig.name || `testkit-${environment.name}`;
+  const networks = await client.listNetworks();
+  const existing = networks.find((network) => network.name === name);
+  const network = existing || (await client.createNetwork({ name, ...(networkConfig.cidr ? { cidr: networkConfig.cidr } : {}) }));
+  await attachExistingVMs(client, network, networkConfig.attachExistingVMs || []);
+  return network;
+}
+
+async function attachExistingVMs(client, network, vmRefs) {
+  for (const ref of vmRefs || []) {
+    let vm = await client.getVM(ref);
+    if (vm.network_id === network.id) continue;
+    if (vm.state !== "stopped") {
+      await client.stopVM(ref);
+      await waitForVMState(client, ref, "stopped");
+    }
+    await client.attachVMNetwork(ref, network.id);
+    await client.startVM(ref);
+    await waitForVMReady(client, ref);
+  }
+}
+
+async function ensureVM(client, vmConfig, networkId) {
+  try {
+    const existing = await client.getVM(vmConfig.name);
+    if (existing.profile && existing.profile !== vmConfig.profile) {
+      throw new Error(`Kiln VM ${vmConfig.name} uses profile ${existing.profile}; expected ${vmConfig.profile}`);
+    }
+    return existing;
+  } catch (error) {
+    if (!String(error.message || "").includes("404")) throw error;
+  }
+  return client.createVM({
+    name: vmConfig.name,
+    profile: vmConfig.profile,
+    network_id: networkId || vmConfig.networkId || "",
+    disk_size_mb: vmConfig.diskSizeMB,
+    memory_mb: vmConfig.memoryMB,
+    vcpus: vmConfig.vcpus,
+    autostart: Boolean(vmConfig.autostart),
+  });
+}
+
+async function ensureStarted(client, ref) {
+  const vm = await client.getVM(ref);
+  if (vm.state === "running" || vm.state === "creating") return vm;
+  return client.startVM(ref);
+}
+
+async function waitForVMReady(client, ref) {
+  const startedAt = Date.now();
+  let last = null;
+  let lastError = null;
+  while (Date.now() - startedAt < 180_000) {
+    last = await client.getVM(ref);
+    if (last.state === "running") {
+      try {
+        const result = await client.execVM(ref, "echo testkit-kiln-ready");
+        if (result.exit_code === 0 && result.stdout.includes("testkit-kiln-ready")) return await client.getVM(ref);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    await sleep(1000);
+  }
+  const suffix = lastError ? `; last readiness error: ${lastError.message}` : "";
+  throw new Error(`Timed out waiting for Kiln VM ${ref}; last state ${last?.state || "unknown"}${suffix}`);
+}
+
+async function waitForVMState(client, ref, state) {
+  const startedAt = Date.now();
+  let last = null;
+  while (Date.now() - startedAt < 120_000) {
+    last = await client.getVM(ref);
+    if (last.state === state) return last;
+    await sleep(1000);
+  }
+  throw new Error(`Timed out waiting for Kiln VM ${ref} to become ${state}; last state ${last?.state || "unknown"}`);
+}
+
+async function prepareSSH(client, vm) {
+  const key = await client.sshKey(vm.machine_id);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-kiln-ssh-"));
+  const keyPath = path.join(dir, "id_ed25519");
+  fs.writeFileSync(keyPath, key, { mode: 0o600 });
+  return { host: vm.ip, keyPath, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
+async function sshFromManifest(manifest) {
+  const client = new KilnClient(manifest.kiln?.api || {});
+  const vm = await client.getVM(manifest.kiln.vm.name);
+  const started = vm.state === "running" ? vm : await ensureStarted(client, vm.name);
+  const running = started.state === "running" ? started : await waitForVMReady(client, vm.name);
+  const ssh = await prepareSSH(client, running);
+  await waitForSSHReady(ssh, vm.name);
+  return ssh;
+}
+
+async function waitForSSHReady(ssh, vmName) {
+  const startedAt = Date.now();
+  let lastError = null;
+  while (Date.now() - startedAt < 120_000) {
+    try {
+      await sshCommand(ssh, "true");
+      return;
+    } catch (error) {
+      lastError = error;
+      await sleep(1000);
+    }
+  }
+  throw new Error(`Timed out waiting for SSH in Kiln VM ${vmName}: ${lastError?.message || "unknown error"}`);
+}
+
+async function syncWorkspace({ ssh, productDir, remoteProductDir, environment }) {
+  await sshCommand(ssh, `mkdir -p ${shellQuote(remoteProductDir)}`);
+  const excludes = [...DEFAULT_RSYNC_EXCLUDES, ...(environment.kiln?.workspace?.exclude || [])];
+  const args = [
+    "-az",
+    "--delete",
+    ...excludes.flatMap((entry) => ["--exclude", entry]),
+    "-e",
+    sshTransport(ssh),
+    `${path.resolve(productDir)}/`,
+    `root@${ssh.host}:${remoteProductDir}/`,
+  ];
+  await execa("rsync", args, { stdio: "inherit" });
+}
+
+async function bootstrapRemoteWorkspace({ ssh, context, remoteProductDir }) {
+  const nodeVersion = readDesiredNodeVersion(context.productDir);
+  const packPath = await packCurrentTestkit(context.productDir);
+  const manifest = buildBootstrapManifest(context.productDir, { nodeVersion, testkitPackPath: packPath });
+  const remotePack = `/tmp/${path.basename(packPath)}`;
+  const localManifest = path.join(context.productDir, ".testkit", "kiln", "bootstrap-manifest.json");
+  fs.mkdirSync(path.dirname(localManifest), { recursive: true });
+  fs.writeFileSync(localManifest, `${JSON.stringify(manifest, null, 2)}\n`);
+  await execa("rsync", ["-az", "-e", sshTransport(ssh), packPath, `root@${ssh.host}:${remotePack}`], { stdio: "inherit" });
+  await execa("rsync", ["-az", "-e", sshTransport(ssh), localManifest, `root@${ssh.host}:/tmp/testkit-bootstrap-manifest.json`], { stdio: "inherit" });
+  await sshCommand(ssh, [
+    "set -eu",
+    `NODE_VERSION=${shellQuote(nodeVersion)}`,
+    `REMOTE_DIR=${shellQuote(remoteProductDir)}`,
+    `BOOTSTRAP_MANIFEST=${shellQuote(BOOTSTRAP_MANIFEST_PATH)}`,
+    "NODE_HOME=/opt/testkit-node-$NODE_VERSION",
+    "if [ ! -x \"$NODE_HOME/bin/node\" ]; then",
+    "  mkdir -p /opt",
+    "  curl -fsSL \"https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION-linux-x64.tar.xz\" -o /tmp/testkit-node.tar.xz",
+    "  rm -rf \"$NODE_HOME\"",
+    "  mkdir -p \"$NODE_HOME\"",
+    "  tar -xJf /tmp/testkit-node.tar.xz -C \"$NODE_HOME\" --strip-components=1",
+    "fi",
+    "export PATH=\"$NODE_HOME/bin:$PATH\"",
+    "deadline=$(($(date +%s) + 120))",
+    "until docker info >/dev/null 2>&1; do",
+    "  if [ \"$(date +%s)\" -ge \"$deadline\" ]; then tail -80 /var/log/dockerd.log >&2 || true; exit 1; fi",
+    "  sleep 1",
+    "done",
+    "cd \"$REMOTE_DIR\"",
+    "BOOTSTRAP_READY=1",
+    "[ -x ./node_modules/.bin/testkit ] || BOOTSTRAP_READY=0",
+    "if [ -f frontend/package-lock.json ] && [ ! -d frontend/node_modules ]; then BOOTSTRAP_READY=0; fi",
+    "if [ -f \"$BOOTSTRAP_MANIFEST\" ] && cmp -s /tmp/testkit-bootstrap-manifest.json \"$BOOTSTRAP_MANIFEST\" && [ \"$BOOTSTRAP_READY\" = 1 ]; then",
+    "  echo 'testkit kiln bootstrap cache hit'",
+    "else",
+    "  npm ci",
+    "  if [ -f frontend/package-lock.json ]; then npm --prefix frontend ci; fi",
+    `  npm install --no-save ${shellQuote(remotePack)}`,
+    "  mkdir -p \"$(dirname \"$BOOTSTRAP_MANIFEST\")\"",
+    "  cp /tmp/testkit-bootstrap-manifest.json \"$BOOTSTRAP_MANIFEST\"",
+    "fi",
+  ].join("\n"));
+}
+
+async function remoteTestkit(ssh, remoteProductDir, args, extraEnv = {}) {
+  const envPrefix = Object.entries({ TESTKIT_KILN_INNER: "1", TESTKIT_LOCAL_DRIVER: "host", ...extraEnv })
+    .map(([key, value]) => `${key}=${shellQuote(value)}`)
+    .join(" ");
+  const command = [
+    `cd ${shellQuote(remoteProductDir)}`,
+    `BOOTSTRAP_MANIFEST=${shellQuote(BOOTSTRAP_MANIFEST_PATH)}`,
+    "NODE_VERSION=$(sed -n 's/.*\"nodeVersion\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p' \"$BOOTSTRAP_MANIFEST\" | head -1)",
+    "[ -n \"$NODE_VERSION\" ]",
+    "NODE_HOME=/opt/testkit-node-$NODE_VERSION",
+    "export PATH=\"$NODE_HOME/bin:$PATH\"",
+    `export ${envPrefix}`,
+    `./node_modules/.bin/testkit ${args.map(shellQuote).join(" ")}`,
+  ].join(" && ");
+  return sshCommand(ssh, command, { reject: false });
+}
+
+async function remoteLocalStatus(ssh, remoteProductDir, name) {
+  const result = await remoteTestkit(ssh, remoteProductDir, ["local", "status", name, "--json"]);
+  if (result.exitCode !== 0) return null;
+  try {
+    return JSON.parse(result.stdout)?.result || null;
+  } catch {
+    return null;
+  }
+}
+
+async function sshCommand(ssh, command, options = {}) {
+  const args = sshArgs(ssh, command);
+  return execa("ssh", args, { reject: options.reject !== false });
+}
+
+function sshArgs(ssh, command) {
+  return [
+    "-i",
+    ssh.keyPath,
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-o",
+    "UserKnownHostsFile=/dev/null",
+    "-o",
+    "LogLevel=ERROR",
+    `root@${ssh.host}`,
+    command,
+  ];
+}
+
+function sshTransport(ssh) {
+  return `ssh -i ${ssh.keyPath} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR`;
+}
+
+function normalizeVMConfig(environment) {
+  const vm = environment.kiln?.vm || {};
+  const name = vm.name || `testkit-${environment.name}`;
+  return {
+    name,
+    profile: vm.profile || "ubuntu-docker",
+    diskSizeMB: parseDiskMB(vm.disk || vm.diskSize || vm.diskSizeMB || "64G"),
+    memoryMB: Number(vm.memoryMB || vm.memoryMb || vm.memory_mib || 8192),
+    vcpus: Number(vm.vcpus || 4),
+    autostart: Boolean(vm.autostart),
+    networkId: vm.networkId || vm.network_id || "",
+  };
+}
+
+function parseDiskMB(value) {
+  if (typeof value === "number") return value;
+  const raw = String(value || "").trim();
+  const match = raw.match(/^(\d+)([gGmM])?$/);
+  if (!match) throw new Error(`Invalid Kiln VM disk size: ${value}`);
+  const amount = Number(match[1]);
+  return match[2]?.toLowerCase() === "g" ? amount * 1024 : amount;
+}
+
+function readDesiredNodeVersion(productDir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(productDir, "package.json"), "utf8"));
+    return pkg.volta?.node || String(pkg.engines?.node || "20.19.5").match(/\d+\.\d+\.\d+/)?.[0] || "20.19.5";
+  } catch {
+    return "20.19.5";
+  }
+}
+
+async function packCurrentTestkit(productDir) {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  const outDir = path.join(productDir, ".testkit", "kiln", "packages");
+  fs.mkdirSync(outDir, { recursive: true });
+  const { stdout } = await execa("npm", ["pack", "--pack-destination", outDir, "--silent"], { cwd: packageRoot });
+  return path.join(outDir, stdout.trim().split(/\r?\n/).at(-1));
+}
+
+export function buildBootstrapManifest(productDir, { nodeVersion, testkitPackPath }) {
+  return {
+    version: 1,
+    nodeVersion,
+    testkitPackSha256: sha256File(testkitPackPath),
+    locks: Object.fromEntries(
+      ["package-lock.json", "frontend/package-lock.json"]
+        .filter((entry) => fs.existsSync(path.join(productDir, entry)))
+        .map((entry) => [entry, sha256File(path.join(productDir, entry))])
+    ),
+  };
+}
+
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+export function rewriteEndpoints(endpoints, host) {
+  return Object.fromEntries(
+    Object.entries(endpoints || {}).map(([service, raw]) => {
+      try {
+        const url = new URL(raw);
+        url.hostname = host;
+        return [service, url.toString().replace(/\/$/, "")];
+      } catch {
+        return [service, raw];
+      }
+    })
+  );
+}
+
+function requireKilnManifest(productDir, name) {
+  const manifest = readLocalEnvironmentManifest(productDir, name);
+  if (!manifest) throw new Error(`Local environment "${name}" has not been started.`);
+  if (manifest.driver !== "kiln") throw new Error(`Local environment "${name}" is not managed by the Kiln driver.`);
+  if (!manifest.kiln?.vm?.name) throw new Error(`Local environment "${name}" has no Kiln VM recorded.`);
+  return manifest;
+}
+
+function writeKilnManifest(productDir, name, manifest) {
+  fs.writeFileSync(
+    path.join(getEnvironmentDir(productDir, name), "manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`
+  );
+}
+
+function pickVM(vm) {
+  return {
+    id: vm.id,
+    name: vm.name,
+    machine_id: vm.machine_id,
+    ip: vm.ip,
+    private_ip: vm.private_ip,
+    state: vm.state,
+  };
+}
+
+function pickAPIConfig(api) {
+  return {
+    ...(api.apiUrl ? { apiUrl: api.apiUrl } : {}),
+  };
+}
+
+function splitOutput(result) {
+  return [result.stdout, result.stderr].filter(Boolean).join("").split(/\r?\n/).filter(Boolean);
+}
+
+function shellQuote(value) {
+  return "'" + String(value ?? "").replaceAll("'", "'\"'\"'") + "'";
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/local/lifecycle.mjs

@@ -19,6 +19,7 @@ export function createLocalEnvironmentLifecycle(productDir, name, options = {})
   const state = {
     schemaVersion: SCHEMA_VERSION,
     kind: "local",
+    driver: options.driver || "host",
     name,
     productDir,
     pid: process.pid,
@@ -200,6 +201,7 @@ export function findLocalPortOwner(productDir, { host, port }) {
 }
 
 export function isLocalEnvironmentActive(manifest) {
+  if (manifest.driver === "kiln") return manifest.status === "running";
   return (manifest.services || []).some(isLocalServiceActive);
 }
 

package/lib/local/orchestrator.mjs

@@ -8,6 +8,14 @@ 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,
@@ -21,6 +29,9 @@ import {
 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}.`);
@@ -77,21 +88,30 @@ export async function localUp(options = {}) {
 export async function localDown(options = {}) {
   const context = await loadConfigContext({ dir: options.dir });
   const name = normalizeEnvironmentName(options.name || "local");
-  const manifest = await stopLocalEnvironment(context.productDir, name, {
+  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 manifest
+  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) return buildLocalStatus(context.productDir, normalizeEnvironmentName(options.name));
+  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) =>
-      buildLocalStatus(context.productDir, manifest.name)
+      manifest.driver === "kiln" ? buildKilnLocalStatus(context.productDir, manifest.name) : buildLocalStatus(context.productDir, manifest.name)
     ),
   };
 }
@@ -101,6 +121,7 @@ export async function localEnv(options = {}) {
   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);
@@ -119,6 +140,7 @@ export async function localLogs(options = {}) {
   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]
@@ -140,6 +162,7 @@ export async function localShell(options = {}) {
   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);
@@ -162,6 +185,7 @@ export function buildLocalRuntimeConfigs(allConfigs, environment, runtimeDir) {
   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));
 }
 
@@ -202,17 +226,22 @@ export function buildLocalStatus(productDir, name) {
   };
 }
 
-function resolveEnvironment(context, options = {}) {
+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,
   };
 }