@elench/testkit 0.1.135 → 0.1.137

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

package/lib/runner/processes.mjs

@@ -1,3 +1,5 @@
+import fs from "fs";
+import path from "path";
 import { execFileSync, spawn } from "child_process";
 
 export function normalizeServiceStartCommand(command) {
@@ -10,28 +12,65 @@ export function normalizeServiceStartCommand(command) {
     throw new Error("Service start command must not be empty");
   }
 
-  return trimmed.replace(/^exec\s+/u, "");
+  return trimmed;
 }
 
-export function startDetachedCommand(command, cwd, env) {
+export function startDetachedCommand(command, cwd, env, options = {}) {
   const normalizedCommand = normalizeServiceStartCommand(command);
+  const { stdio, close } = resolveDetachedStdio(options);
+  let child;
   if (process.platform === "win32") {
-    return spawn(normalizedCommand, {
+    child = spawn(normalizedCommand, {
       cwd,
       env,
       detached: true,
       shell: true,
-      stdio: ["ignore", "pipe", "pipe"],
+      stdio,
     });
+    close();
+    if (options.unref) child.unref();
+    return child;
   }
 
   const shell = process.env.SHELL || "/bin/sh";
-  return spawn(shell, ["-lc", `exec ${normalizedCommand}`], {
+  child = spawn(shell, ["-lc", `exec ${normalizedCommand}`], {
     cwd,
     env,
     detached: true,
-    stdio: ["ignore", "pipe", "pipe"],
+    stdio,
   });
+  close();
+  if (options.unref) child.unref();
+  return child;
+}
+
+function resolveDetachedStdio(options = {}) {
+  if (!options.stdoutPath && !options.stderrPath) {
+    return { stdio: ["ignore", "pipe", "pipe"], close() {} };
+  }
+  const fds = [];
+  const openLog = (filePath) => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, "a");
+    fds.push(fd);
+    return fd;
+  };
+  return {
+    stdio: [
+      "ignore",
+      options.stdoutPath ? openLog(options.stdoutPath) : "ignore",
+      options.stderrPath ? openLog(options.stderrPath) : "ignore",
+    ],
+    close() {
+      for (const fd of fds) {
+        try {
+          fs.closeSync(fd);
+        } catch {
+          // Best-effort descriptor cleanup.
+        }
+      }
+    },
+  };
 }
 
 export function killChildProcess(child, signal) {

package/lib/runner/readiness.mjs

@@ -6,6 +6,11 @@ import {
   isPidRunning,
   listRunManifests,
 } from "./lifecycle.mjs";
+import {
+  cleanupStaleLocalEnvironments,
+  findLocalPortOwner,
+  formatLocalEnvironmentSummary,
+} from "../local/lifecycle.mjs";
 import { socketFromUrl } from "./template.mjs";
 
 export const DEFAULT_READY_TIMEOUT_MS = 120_000;
@@ -48,15 +53,21 @@ export async function assertLocalServicePortsAvailable(config, isPortInUse) {
 
     if (await isPortInUse(socket)) {
       await cleanupStaleRuns(config.productDir);
+      await cleanupStaleLocalEnvironments(config.productDir);
     }
 
     if (await isPortInUse(socket)) {
       const owner = findPortOwner(config.productDir, socket);
+      const localOwner = owner ? null : findLocalPortOwner(config.productDir, socket);
       const ownerDetail = owner
         ? owner.active
           ? ` Active testkit run ${formatRunSummary(owner.manifest)} owns ${key} via ${owner.service.runtimeLabel}:${owner.service.serviceName}.`
           : ` Stale testkit run ${formatRunSummary(owner.manifest)} owns ${key}.`
-        : "";
+        : localOwner
+          ? localOwner.active
+            ? ` Active testkit local environment ${formatLocalEnvironmentSummary(localOwner.manifest)} owns ${key} via ${localOwner.service.serviceName}.`
+            : ` Stale testkit local environment ${formatLocalEnvironmentSummary(localOwner.manifest)} owns ${key}.`
+          : "";
       throw new Error(
         `Cannot start "${config.runtimeLabel}:${config.name}" because ${key} is already in use. ` +
           `Stop the existing process and rerun testkit.${ownerDetail}`

package/lib/runner/runtime-preparation.mjs

@@ -41,7 +41,11 @@ export async function prepareRuntimeService(config, options = {}) {
   fs.mkdirSync(prepareDir, { recursive: true });
 
   const env = {
-    ...buildExecutionEnv(config, config.testkit.local?.env || {}, process.env),
+    ...buildExecutionEnv(
+      config,
+      { ...(config.testkit.local?.env || {}), ...(options.extraEnv || {}) },
+      process.env
+    ),
   };
   const databaseUrl = readDatabaseUrl(config.stateDir);
   if (databaseUrl) {
@@ -128,12 +132,13 @@ export async function computeRuntimePrepareFingerprint(config) {
     })
   );
   hash.update(JSON.stringify(collectRuntimeDatabaseFingerprintInputs(config)));
+  const fingerprints = config.testkit.fingerprints || {};
 
   for (const envFile of config.testkit.envFiles || []) {
-    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
+    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile), fingerprints);
   }
   for (const input of collectConfiguredInputs(config.productDir, config.testkit.runtime.prepare)) {
-    appendResolvedInputToHash(hash, config.productDir, input);
+    appendResolvedInputToHash(hash, config.productDir, input, fingerprints);
   }
 
   return hash.digest("hex");
@@ -174,9 +179,9 @@ function collectDatabasePlaceholderServices(value, out, defaultServiceName) {
   }
 }
 
-function appendResolvedInputToHash(hash, productDir, absPath) {
+function appendResolvedInputToHash(hash, productDir, absPath, fingerprints) {
   const relative = path.relative(productDir, absPath);
-  appendInputToHash(hash, productDir, relative);
+  appendInputToHash(hash, productDir, relative, fingerprints);
 }
 
 function readPrepareManifest(manifestPath) {

package/lib/runner/services.mjs

@@ -32,7 +32,7 @@ export async function startLocalService(config, lifecycle, options = {}) {
   const resolvedToolchain = await resolveConfiguredToolchain(config);
   await announceResolvedToolchain(config, resolvedToolchain, options.reporter);
   const env = applyToolchainEnv(
-    buildExecutionEnv(config, config.testkit.local.env, process.env),
+    buildExecutionEnv(config, { ...(config.testkit.local.env || {}), ...(options.extraEnv || {}) }, process.env),
     resolvedToolchain
   );
   const port = config.testkit.local.port || numericPortFromUrl(config.testkit.local.baseUrl);
@@ -48,29 +48,35 @@ export async function startLocalService(config, lifecycle, options = {}) {
   await assertLocalServicePortsAvailable(config, isPortInUse);
 
   options.reporter?.localServiceStarting?.(config, config.testkit.local.start);
-  const child = startDetachedCommand(config.testkit.local.start, cwd, env);
+  const serviceLogFiles = options.serviceLogFiles?.(config) || null;
+  const child = startDetachedCommand(config.testkit.local.start, cwd, env, {
+    ...(serviceLogFiles || {}),
+    unref: Boolean(serviceLogFiles),
+  });
   const logRecord = options.logRegistry?.ensureServiceLogRecord(config);
   const liveWriter =
     options.reporter?.outputMode === "debug"
       ? (line) => options.reporter.writeDebugLine?.(line)
       : null;
 
-  const outputDrains = [
-    captureOutput(child.stdout, {
-      livePrefix: `[${config.runtimeLabel}:${config.name}]`,
-      liveWriter,
-      onLine(line) {
-        if (logRecord) options.logRegistry.append(logRecord, "stdout", line);
-      },
-    }),
-    captureOutput(child.stderr, {
-      livePrefix: `[${config.runtimeLabel}:${config.name}]`,
-      liveWriter,
-      onLine(line) {
-        if (logRecord) options.logRegistry.append(logRecord, "stderr", line);
-      },
-    }),
-  ];
+  const outputDrains = serviceLogFiles
+    ? []
+    : [
+        captureOutput(child.stdout, {
+          livePrefix: `[${config.runtimeLabel}:${config.name}]`,
+          liveWriter,
+          onLine(line) {
+            if (logRecord) options.logRegistry.append(logRecord, "stdout", line);
+          },
+        }),
+        captureOutput(child.stderr, {
+          livePrefix: `[${config.runtimeLabel}:${config.name}]`,
+          liveWriter,
+          onLine(line) {
+            if (logRecord) options.logRegistry.append(logRecord, "stderr", line);
+          },
+        }),
+      ];
   registerManagedService(lifecycle, config, child, cwd, "SIGTERM");
 
   const readyTimeoutMs = config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;

package/lib/runner/status-model.mjs

@@ -3,6 +3,7 @@ import path from "path";
 import { buildRuntimeIds } from "./execution-config.mjs";
 import { buildGraphDirName, resolveRuntimeConfigs } from "./planning.mjs";
 import { isPidRunning, listRunManifests } from "./lifecycle.mjs";
+import { isLocalEnvironmentActive, listLocalEnvironmentManifests } from "../local/lifecycle.mjs";
 import { readGraphMetadata } from "./state.mjs";
 
 const BUNDLE_MANIFEST = "manifest.json";
@@ -18,6 +19,7 @@ export function collectStatusModel(config, { allConfigs = [config] } = {}) {
   });
   const serviceState = collectDirectorySummary(config.stateDir);
   const runs = collectRunStatus(productDir);
+  const localEnvironments = collectLocalEnvironmentStatus(productDir);
   const bundles = collectBundleCacheStatus(productDir, config.name);
   const assistant = collectAssistantResultStatus(productDir);
   const warnings = collectWarnings({ runtimeGraphs, bundles, assistant });
@@ -25,6 +27,7 @@ export function collectStatusModel(config, { allConfigs = [config] } = {}) {
     serviceState.exists ||
     runtimeGraphs.some((graph) => graph.exists) ||
     runs.total > 0 ||
+    localEnvironments.total > 0 ||
     bundles.exists ||
     assistant.exists;
 
@@ -40,6 +43,7 @@ export function collectStatusModel(config, { allConfigs = [config] } = {}) {
     },
     hasState,
     runs,
+    localEnvironments,
     serviceState,
     runtimeGraphs,
     caches: {
@@ -50,6 +54,29 @@ export function collectStatusModel(config, { allConfigs = [config] } = {}) {
   };
 }
 
+function collectLocalEnvironmentStatus(productDir) {
+  const environments = listLocalEnvironmentManifests(productDir).map((manifest) => {
+    const active = isLocalEnvironmentActive(manifest);
+    return {
+      name: manifest.name,
+      status: active ? "running" : manifest.status || "stopped",
+      target: manifest.target || null,
+      ports: [
+        ...new Set(
+          (manifest.services || []).flatMap((service) =>
+            (service.ports || []).map((socket) => `${socket.host}:${socket.port}`)
+          )
+        ),
+      ].sort(),
+    };
+  });
+  return {
+    total: environments.length,
+    active: environments.filter((environment) => environment.status === "running").length,
+    environments,
+  };
+}
+
 export function collectCleanupTargets(productDir, { allConfigs = [], serviceName = null, cache = [] } = {}) {
   const desiredGraphs = collectDesiredRuntimeGraphs(allConfigs);
   const runtimeGraphs = collectRuntimeGraphStatus(productDir, { desiredGraphs, serviceName });