@elench/testkit 0.1.134 → 0.1.136

package/lib/local/orchestrator.mjs

@@ -0,0 +1,314 @@
+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 {
+  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);
+  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 = await stopLocalEnvironment(context.productDir, name, {
+    removeRuntimeState: Boolean(options.destroyState),
+  });
+  return manifest
+    ? 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));
+  return {
+    productDir: context.productDir,
+    environments: listLocalEnvironmentManifests(context.productDir).map((manifest) =>
+      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.`);
+  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.`);
+  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.`);
+  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,
+  }).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,
+  };
+}
+
+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);
+  return {
+    name,
+    kind: "local",
+    target,
+    data: options.rebuild ? "rebuild" : options.reset ? "reset" : configured?.data || "reuse",
+    portOffset: Number(options.portOffset ?? configured?.portOffset ?? 0),
+    env: { ...(configured?.env || {}) },
+  };
+}
+
+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 });
+    });
+  });
+}

package/lib/repo/fingerprint-policy.mjs

@@ -0,0 +1,145 @@
+import fs from "fs";
+import path from "path";
+
+const TESTKIT_OWNED_PATHS = [
+  ".testkit",
+  ".next-testkit",
+  "testkit.status.json",
+];
+
+export function normalizeFingerprintPolicy(value = {}) {
+  if (value == null) {
+    return {
+      exclude: [],
+      include: [],
+    };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("testkit.config.ts fingerprints must be an object");
+  }
+  return {
+    exclude: normalizePatternList(value.exclude, "fingerprints.exclude"),
+    include: normalizePatternList(value.include, "fingerprints.include"),
+  };
+}
+
+export function shouldIgnoreFingerprintPath(productDir, absOrRelPath, policy = {}) {
+  const relativePath = normalizeRelativePath(productDir, absOrRelPath);
+  if (!relativePath) return false;
+  if (matchesTestkitOwnedPath(relativePath)) return true;
+  if (matchesAnyPattern(relativePath, policy.include || [])) return false;
+  return matchesAnyPattern(relativePath, policy.exclude || []);
+}
+
+export function appendFingerprintPathToHash(hash, productDir, absPath, policy = {}) {
+  const relativePath = normalizeRelativePath(productDir, absPath);
+  const ignored = shouldIgnoreFingerprintPath(productDir, relativePath, policy);
+
+  let stat;
+  try {
+    stat = fs.lstatSync(absPath);
+  } catch {
+    if (ignored) return;
+    hash.update(`missing:${relativePath}`);
+    return;
+  }
+  if (ignored && (!stat.isDirectory() || !hasIncludedDescendant(relativePath, policy))) return;
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink:${relativePath}:${fs.readlinkSync(absPath)}`);
+    return;
+  }
+  if (stat.isDirectory()) {
+    if (!ignored) hash.update(`dir:${relativePath}`);
+    for (const entry of fs.readdirSync(absPath).sort()) {
+      appendFingerprintPathToHash(hash, productDir, path.join(absPath, entry), policy);
+    }
+    return;
+  }
+
+  if (!stat.isFile()) return;
+  hash.update(`file:${relativePath}:${stat.size}:${stat.mtimeMs}`);
+  hash.update(fs.readFileSync(absPath));
+}
+
+export function normalizeRelativePath(productDir, absOrRelPath) {
+  const raw = String(absOrRelPath || "");
+  const relative = path.isAbsolute(raw) ? path.relative(productDir, raw) : raw;
+  return normalizePath(relative);
+}
+
+export function normalizePath(value) {
+  return String(value || "")
+    .split(path.sep)
+    .join("/")
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "");
+}
+
+function normalizePatternList(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`testkit.config.ts ${label} must be an array of paths`);
+  }
+  return value.map((entry, index) => {
+    const normalized = normalizePath(String(entry || "").trim());
+    if (!normalized) {
+      throw new Error(`testkit.config.ts ${label}[${index}] must be a non-empty path`);
+    }
+    if (
+      path.isAbsolute(normalized) ||
+      path.win32.isAbsolute(normalized) ||
+      normalized.startsWith("../") ||
+      normalized === ".."
+    ) {
+      throw new Error(`testkit.config.ts ${label}[${index}] must be relative to the product directory`);
+    }
+    return normalized;
+  });
+}
+
+function matchesAnyPattern(relativePath, patterns) {
+  return (patterns || []).some((pattern) => matchesPattern(relativePath, pattern));
+}
+
+function matchesTestkitOwnedPath(relativePath) {
+  return matchesAnyPattern(relativePath, TESTKIT_OWNED_PATHS);
+}
+
+function hasIncludedDescendant(relativePath, policy = {}) {
+  if (!relativePath || matchesTestkitOwnedPath(relativePath)) return false;
+  const prefix = `${relativePath}/`;
+  return (policy.include || []).some((pattern) => normalizePath(pattern).startsWith(prefix));
+}
+
+function matchesPattern(relativePath, pattern) {
+  const normalizedPath = normalizePath(relativePath);
+  const normalizedPattern = normalizePath(pattern);
+  if (!normalizedPattern) return false;
+  if (normalizedPath === normalizedPattern) return true;
+  if (normalizedPath.startsWith(`${normalizedPattern}/`)) return true;
+  if (!normalizedPattern.includes("*")) return false;
+  return globToRegExp(normalizedPattern).test(normalizedPath);
+}
+
+function globToRegExp(pattern) {
+  let source = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+    if (char === "*" && next === "*") {
+      source += ".*";
+      index += 1;
+    } else if (char === "*") {
+      source += "[^/]*";
+    } else {
+      source += escapeRegExp(char);
+    }
+  }
+  source += "$";
+  return new RegExp(source);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}

package/lib/repo/state.mjs

@@ -3,13 +3,18 @@ import fs from "fs";
 import path from "path";
 import { execFileSync } from "child_process";
 import { parseGitHubRepoSlug } from "../regressions/github.mjs";
+import {
+  appendFingerprintPathToHash,
+  normalizeFingerprintPolicy,
+  normalizePath,
+  shouldIgnoreFingerprintPath,
+} from "./fingerprint-policy.mjs";
 
-const IGNORED_DIRS = new Set([".git", ".testkit", "node_modules"]);
-
-export function collectRepoState(productDir) {
+export function collectRepoState(productDir, options = {}) {
+  const fingerprints = normalizeFingerprintPolicy(options.fingerprints);
   const repoRoot = readGit(productDir, ["rev-parse", "--show-toplevel"]);
   if (!repoRoot) {
-    const fingerprint = fingerprintDirectory(productDir);
+    const fingerprint = fingerprintDirectory(productDir, fingerprints);
     return {
       kind: "nogit",
       repoRoot: null,
@@ -30,7 +35,7 @@ export function collectRepoState(productDir) {
   const branchName = readGit(productDir, ["rev-parse", "--abbrev-ref", "HEAD"]);
   const remoteUrl = readGit(productDir, ["remote", "get-url", "origin"]);
   const detached = branchName === "HEAD";
-  const dirtyFingerprint = fingerprintGitDirtyState(productDir);
+  const dirtyFingerprint = fingerprintGitDirtyState(productDir, fingerprints);
   const dirty = Boolean(dirtyFingerprint);
   const baseCommit = commitSha || "unborn";
 
@@ -70,24 +75,30 @@ export function summarizeRepoStateForMetadata(repoState) {
   };
 }
 
-function fingerprintGitDirtyState(productDir) {
+function fingerprintGitDirtyState(productDir, fingerprints) {
   const hash = crypto.createHash("sha256");
   let hasChanges = false;
 
-  const trackedStatus = readGit(productDir, ["status", "--porcelain=v1", "-uno"]) || "";
-  if (trackedStatus.trim()) {
+  const trackedStatus = readGitRaw(productDir, ["status", "--porcelain=v1", "-z", "-uno"]) || "";
+  const trackedFiles = parsePorcelainStatusPaths(trackedStatus)
+    .filter((entry) => !shouldIgnoreFingerprintPath(productDir, entry, fingerprints))
+    .sort();
+  if (trackedFiles.length > 0) {
     hasChanges = true;
     hash.update("tracked-status\0");
-    hash.update(trackedStatus);
-    appendGitOutput(hash, productDir, ["diff", "--binary", "--no-ext-diff"]);
-    appendGitOutput(hash, productDir, ["diff", "--binary", "--cached", "--no-ext-diff"]);
+    for (const relativePath of trackedFiles) {
+      hash.update(`${relativePath}\0`);
+    }
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--no-ext-diff", "--", ...trackedFiles]);
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--cached", "--no-ext-diff", "--", ...trackedFiles]);
   }
 
-  const untracked = readGit(productDir, ["ls-files", "--others", "--exclude-standard", "-z"]) || "";
+  const untracked = readGitRaw(productDir, ["ls-files", "--others", "--exclude-standard", "-z"]) || "";
   const untrackedFiles = untracked
     .split("\0")
     .filter(Boolean)
-    .filter((entry) => !hasIgnoredPathSegment(entry))
+    .map(normalizePath)
+    .filter((entry) => !shouldIgnoreFingerprintPath(productDir, entry, fingerprints))
     .sort();
   if (untrackedFiles.length > 0) {
     hasChanges = true;
@@ -106,58 +117,49 @@ function fingerprintGitDirtyState(productDir) {
 }
 
 function appendGitOutput(hash, cwd, args) {
-  const output = readGit(cwd, args) || "";
+  const output = readGitRaw(cwd, args) || "";
   hash.update(args.join(" "));
   hash.update("\0");
   hash.update(output);
   hash.update("\0");
 }
 
-function fingerprintDirectory(rootDir) {
+function fingerprintDirectory(rootDir, fingerprints) {
   const hash = crypto.createHash("sha256");
-  appendDirectoryToHash(hash, rootDir, rootDir);
+  appendFingerprintPathToHash(hash, rootDir, rootDir, fingerprints);
   return hash.digest("hex").slice(0, 24);
 }
 
-function appendDirectoryToHash(hash, rootDir, absPath) {
-  if (!fs.existsSync(absPath)) {
-    hash.update(`missing:${normalizePath(path.relative(rootDir, absPath))}`);
-    return;
-  }
-  const stat = fs.statSync(absPath);
-  if (stat.isDirectory()) {
-    const relative = path.relative(rootDir, absPath);
-    if (relative && hasIgnoredPathSegment(relative)) return;
-    hash.update(`dir:${normalizePath(relative)}`);
-    for (const entry of fs.readdirSync(absPath).sort()) {
-      if (IGNORED_DIRS.has(entry)) continue;
-      appendDirectoryToHash(hash, rootDir, path.join(absPath, entry));
+function parsePorcelainStatusPaths(output) {
+  const entries = output.split("\0").filter(Boolean);
+  const paths = [];
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (entry.length < 4) continue;
+    const status = entry.slice(0, 2);
+    const relativePath = entry.slice(3);
+    if (relativePath) paths.push(normalizePath(relativePath));
+    if (status.includes("R") || status.includes("C")) {
+      const previousPath = entries[index + 1];
+      if (previousPath) paths.push(normalizePath(previousPath));
+      index += 1;
     }
-    return;
   }
-  if (!stat.isFile()) return;
-  const relative = normalizePath(path.relative(rootDir, absPath));
-  hash.update(`file:${relative}:${stat.size}:${stat.mtimeMs}`);
-  hash.update(fs.readFileSync(absPath));
+  return [...new Set(paths)];
 }
 
-function hasIgnoredPathSegment(relativePath) {
-  return normalizePath(relativePath)
-    .split("/")
-    .some((segment) => IGNORED_DIRS.has(segment));
-}
-
-function normalizePath(value) {
-  return String(value).split(path.sep).join("/");
+function readGit(cwd, args) {
+  const output = readGitRaw(cwd, args);
+  return output?.trim() || null;
 }
 
-function readGit(cwd, args) {
+function readGitRaw(cwd, args) {
   try {
     return execFileSync("git", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
-    }).trim() || null;
+    }) || null;
   } catch {
     return null;
   }

package/lib/runner/maintenance.mjs

@@ -9,9 +9,18 @@ import {
 import { cleanupRuns, formatRunSummary, isPidRunning, listRunManifests } from "./lifecycle.mjs";
 import { findGraphDirsForService, findRuntimeStateDirs } from "./state.mjs";
 import { collectCleanupTargets, collectStatusModel } from "./status-model.mjs";
+import {
+  cleanupStaleLocalEnvironments,
+  formatLocalEnvironmentSummary,
+  listLocalEnvironmentManifests,
+  stopLocalEnvironment,
+} from "../local/lifecycle.mjs";
 
 export async function destroy(config) {
   await cleanupRuns(config.productDir, { includeActive: true });
+  for (const manifest of listLocalEnvironmentManifests(config.productDir)) {
+    await stopLocalEnvironment(config.productDir, manifest.name, { removeRuntimeState: true });
+  }
   const roots = new Set([
     config.stateDir,
     ...findGraphDirsForService(config.productDir, config.name),
@@ -45,6 +54,9 @@ export async function cleanup(productDir, options = {}) {
   const summary = dryRun
     ? collectRunCleanupPreview(productDir)
     : await cleanupRuns(productDir, { includeActive: false });
+  const localCleaned = dryRun
+    ? collectLocalEnvironmentCleanupPreview(productDir)
+    : await cleanupStaleLocalEnvironments(productDir);
   const targets = collectCleanupTargets(productDir, {
     allConfigs,
     serviceName,
@@ -78,6 +90,9 @@ export async function cleanup(productDir, options = {}) {
   for (const manifest of summary.skippedActive) {
     lines.push(`Active run still present: ${formatRunSummary(manifest)}`);
   }
+  for (const manifest of localCleaned) {
+    lines.push(`${dryRun ? "Would mark stopped" : "Marked stopped"} stale local environment ${formatLocalEnvironmentSummary(manifest)}`);
+  }
   for (const target of targets.runtime) {
     lines.push(`${dryRun ? "Would remove" : "Removed"} stale runtime ${target.graph}/${target.runtimeId}`);
   }
@@ -102,6 +117,7 @@ export async function cleanup(productDir, options = {}) {
       runtimeCleaned,
       bundleCleaned,
       assistantCleaned,
+      localCleaned,
       lines: ["No stale runs to clean."],
     };
   }
@@ -113,6 +129,7 @@ export async function cleanup(productDir, options = {}) {
     runtimeCleaned,
     bundleCleaned,
     assistantCleaned,
+    localCleaned,
     lines,
   };
 }
@@ -182,3 +199,9 @@ function collectRunCleanupPreview(productDir) {
   }
   return summary;
 }
+
+function collectLocalEnvironmentCleanupPreview(productDir) {
+  return listLocalEnvironmentManifests(productDir).filter((manifest) =>
+    (manifest.services || []).some((service) => !isPidRunning(Number(service.processGroupId || service.pid)))
+  );
+}