@gleapai/kai-bridge 0.2.9 → 0.6.0

package/src/deps.mjs

@@ -0,0 +1,113 @@
+// JS dependencies for fresh session worktrees.
+//
+// A worktree starts without `node_modules`, and installing them cost ~2
+// minutes per repo per session (the Gleap dashboard: 1975 packages) —
+// paid before the agent could run a single test, and again by the preview
+// boot. The primary checkout on the same machine almost always has a
+// `node_modules` built from the SAME lockfile, so we clone it: APFS
+// `clonefile` (cp -c) on macOS and reflinks on Linux make that a few
+// seconds and share the blocks until a file is written. When the lockfile
+// differs (a dependency bump on the base branch the primary hasn't pulled
+// yet) we leave the directory absent and the install path takes over with
+// the lockfile-driven, cache-first command instead of a bare `npm install`.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { platform } from "node:os";
+import { join } from "node:path";
+
+/** Lockfiles we recognise, in lookup order, with the package manager they imply. */
+export const LOCKFILES = [
+  { name: "package-lock.json", pm: "npm" },
+  { name: "npm-shrinkwrap.json", pm: "npm" },
+  { name: "pnpm-lock.yaml", pm: "pnpm" },
+  { name: "yarn.lock", pm: "yarn" },
+  { name: "bun.lockb", pm: "bun" },
+  { name: "bun.lock", pm: "bun" },
+];
+
+/** `{ name, pm, hash }` of the first lockfile in `dir`, or null when there is none. */
+export function lockfileFingerprint(dir) {
+  for (const { name, pm } of LOCKFILES) {
+    const p = join(dir, name);
+    if (!existsSync(p)) continue;
+    try {
+      return { name, pm, hash: createHash("sha256").update(readFileSync(p)).digest("hex") };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The install command for a service dir when no `node_modules` could be
+ * seeded. Lockfile-driven and cache-first where the package manager
+ * supports it: `npm ci --prefer-offline` skips the resolution pass that
+ * made `npm install` slow on a cold tree, and falls back to `npm install`
+ * when the lockfile and package.json disagree (npm ci refuses that).
+ */
+export function installCommandFor(dir) {
+  const lock = lockfileFingerprint(dir);
+  switch (lock?.pm) {
+    case "npm":
+      return "npm ci --prefer-offline --no-audit --no-fund || npm install --no-audit --no-fund";
+    case "pnpm":
+      return "pnpm install --frozen-lockfile --prefer-offline";
+    case "yarn":
+      return "yarn install";
+    case "bun":
+      return "bun install --frozen-lockfile";
+    default:
+      return "npm install --no-audit --no-fund";
+  }
+}
+
+/** Whether `cwd` can take a copy of `primaryPath`'s node_modules; `reason` explains a no. */
+export function canSeedNodeModules({ primaryPath, cwd }) {
+  if (!primaryPath || !cwd || primaryPath === cwd) return { ok: false, reason: "same_checkout" };
+  if (!existsSync(join(cwd, "package.json"))) return { ok: false, reason: "no_package_json" };
+  if (existsSync(join(cwd, "node_modules"))) return { ok: false, reason: "already_present" };
+  const src = join(primaryPath, "node_modules");
+  let srcStat = null;
+  try {
+    srcStat = statSync(src);
+  } catch {
+    /* absent */
+  }
+  if (!srcStat?.isDirectory()) return { ok: false, reason: "primary_has_none" };
+  const a = lockfileFingerprint(primaryPath);
+  const b = lockfileFingerprint(cwd);
+  if (!a || !b) return { ok: false, reason: "no_lockfile" };
+  if (a.name !== b.name || a.hash !== b.hash) return { ok: false, reason: "lockfile_differs" };
+  return { ok: true, reason: "lockfile_match", pm: b.pm };
+}
+
+/**
+ * Copy the primary checkout's `node_modules` into a fresh worktree when
+ * the lockfiles match. Returns `{ seeded, reason, ms }`; never throws — a
+ * failed or partial copy is removed so the install path still runs.
+ *
+ * macOS `cp -c` clones via clonefile(2) and falls back to a plain copy on
+ * filesystems without it; `-R` without `-L` keeps symlinks as symlinks
+ * (`.bin` shims, pnpm's store links — all relative, so they stay valid).
+ */
+export function seedNodeModules({ primaryPath, cwd, os = platform(), exec = execFileSync }) {
+  const started = Date.now();
+  const check = canSeedNodeModules({ primaryPath, cwd });
+  if (!check.ok) return { seeded: false, reason: check.reason, ms: 0 };
+  const src = join(primaryPath, "node_modules");
+  const dst = join(cwd, "node_modules");
+  try {
+    if (os === "darwin") exec("cp", ["-c", "-R", src, dst], { stdio: "ignore" });
+    else if (os === "linux") exec("cp", ["-R", "--reflink=auto", src, dst], { stdio: "ignore" });
+    else return { seeded: false, reason: "unsupported_platform", ms: 0 };
+    return { seeded: true, reason: check.reason, ms: Date.now() - started };
+  } catch (err) {
+    // A half-copied tree would make the install path see `node_modules`
+    // and skip — never leave one behind.
+    rmSync(dst, { recursive: true, force: true });
+    return { seeded: false, reason: `copy_failed: ${err?.message || err}`, ms: Date.now() - started };
+  }
+}

package/src/executor.mjs

@@ -9,7 +9,7 @@
 import { spawn } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { createInterface } from "node:readline";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ambientConfigDir, managedConfigDir } from "./profiles.mjs";
@@ -70,10 +70,22 @@ export function buildRunnerArgs(turn, workDir, profile) {
  *   transcript is read from there too.
  *   gleap-key → keys handed over in `turn.credentials`, isolated state dir.
  */
-export function buildRunnerEnv(turn, profile, kaiHome = KAI_HOME) {
+export function buildRunnerEnv(turn, profile, kaiHome = KAI_HOME, extraEnv = null) {
   const env = { ...process.env, KAI_RUNNER_DEBUG: process.env.KAI_RUNNER_DEBUG || "0", KAI_PERSONA_DIR: join(dirname(RUNNER), "personas") };
+  // Host-only values for the runner's MCP bridges (the verify tool's
+  // request policy: KAI_VERIFY_*). Never part of the prompt.
+  for (const [k, v] of Object.entries(extraEnv || {})) if (v != null && v !== "") env[k] = String(v);
   // Never leak the Gleap device token into the harness.
   delete env.KAI_DEVICE_TOKEN;
+  // The daemon's own node first on PATH for the runner, the harness and
+  // every shell the agent opens. Under launchd PATH is frozen at install
+  // time and a stale /usr/local/bin/node (v20 here) beat the nvm node the
+  // daemon runs on: `npx vitest` died with ERR_REQUIRE_ESM and the agent
+  // spent its build turn hunting for a Node 24 (2026-09-08). Same fix the
+  // preview boot got in withDaemonNode.
+  const nodeDir = dirname(process.execPath);
+  const pathEntries = String(env.PATH || "").split(delimiter).filter(Boolean);
+  if (pathEntries[0] !== nodeDir) env.PATH = [nodeDir, ...pathEntries.filter((p) => p !== nodeDir)].join(delimiter);
   if (profile.kind === "gleap-key") {
     env.KAI_ACP_STATE_DIR = join(kaiHome, "state", "gleap-key");
     for (const [k, v] of Object.entries(turn.credentials || {})) env[k] = String(v);
@@ -124,10 +136,10 @@ export function buildRunnerEnv(turn, profile, kaiHome = KAI_HOME) {
  * `onSpawn(handle)` hands out `handle.control(obj)` for the runner's stdin
  * control channel (mid-turn steering).
  */
-export function runTurn({ turn, profile, workDir, onEvent, onLog = () => {}, onSpawn, signal, kaiHome = KAI_HOME }) {
+export function runTurn({ turn, profile, workDir, onEvent, onLog = () => {}, onSpawn, signal, kaiHome = KAI_HOME, extraEnv = null }) {
   return new Promise((resolve) => {
     const args = buildRunnerArgs(turn, workDir, profile);
-    const env = buildRunnerEnv(turn, profile, kaiHome);
+    const env = buildRunnerEnv(turn, profile, kaiHome, extraEnv);
     // stdin is the runner's control channel (JSONL: steer / cancel) — see
     // startControlChannel in runner/acp-runner.mjs. Never closed from
     // here; the runner exits on its own when the turn ends.

package/src/ports.mjs

@@ -0,0 +1,134 @@
+// Who owns a port? (kai-bridge 0.5.0)
+//
+// Local mode used to adopt ANY listener on a service's declared port as
+// "your running dev server". A stale `node` from another project on :3000
+// then became the preview and the tester clicked through the wrong app.
+// Adoption now needs proof: the listening pid's working directory must be
+// inside the repo root. `lsof` answers both questions on macOS/Linux
+// (`-iTCP:<port> -sTCP:LISTEN -Fpc` → pid + command, `-p <pid> -d cwd -Fn`
+// → cwd). Windows never adopts (no lsof) — the port is simply busy.
+//
+// The same tool counts ESTABLISHED connections on a port, which is what
+// makes the preview's idle stop mean "nobody is connected" instead of "30
+// minutes since boot".
+//
+// Parsers are pure; the lookups take an injectable `execFile` for tests.
+
+import { execFile as nodeExecFile, execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+function run(execFile, cmd, args, { timeoutMs = 4_000 } = {}) {
+  return new Promise((resolveP) => {
+    try {
+      // lsof exits 1 when nothing matched — that is an answer, not a failure.
+      execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }, (_err, stdout) => resolveP(stdout ? String(stdout) : ""));
+    } catch {
+      resolveP("");
+    }
+  });
+}
+
+/** `lsof -Fpc` output → `[{ pid, command }]` (one entry per process). */
+export function parseLsofListeners(output) {
+  const out = [];
+  let current = null;
+  for (const line of String(output || "").split(/\r?\n/)) {
+    if (!line) continue;
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      current = { pid: Number(value), command: null };
+      if (Number.isInteger(current.pid) && current.pid > 0) out.push(current);
+      else current = null;
+    } else if (tag === "c" && current) {
+      current.command = value;
+    }
+  }
+  return out;
+}
+
+/** `lsof -p <pid> -d cwd -Fn` output → the cwd path, or null. */
+export function parseLsofCwd(output) {
+  let inCwd = false;
+  for (const line of String(output || "").split(/\r?\n/)) {
+    if (!line) continue;
+    if (line[0] === "f") inCwd = line.slice(1) === "cwd";
+    else if (line[0] === "n" && inCwd) return line.slice(1) || null;
+  }
+  // Without the `f` marker (some lsof builds), the first `n` line is the cwd.
+  const first = String(output || "")
+    .split(/\r?\n/)
+    .find((l) => l[0] === "n");
+  return first ? first.slice(1) || null : null;
+}
+
+/** Number of distinct `p` lines — how many processes matched. */
+export function parseLsofCount(output) {
+  return parseLsofListeners(output).length;
+}
+
+/**
+ * `{ pid, command, cwd }` of the process listening on `port`, or null when
+ * nothing listens / the platform has no lsof. Only the first listener is
+ * described (a dev server is one process).
+ */
+export async function describeListener(port, { execFile = nodeExecFile, platform = process.platform } = {}) {
+  if (platform === "win32" || !Number.isInteger(port)) return null;
+  const listeners = parseLsofListeners(await run(execFile, "lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fpc"]));
+  if (listeners.length === 0) return null;
+  const { pid, command } = listeners[0];
+  const cwd = parseLsofCwd(await run(execFile, "lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]));
+  return { pid, command, cwd };
+}
+
+/**
+ * Pure: may the daemon adopt this listener as the repo's own dev server?
+ * Only when its cwd is the repo root or below it (symlinks resolved when
+ * `realpath` can). Windows never adopts.
+ */
+export function canAdoptPort({ listener, repoRoot, platform = process.platform, realpath = defaultRealpath, gitCommonDir = defaultGitCommonDir } = {}) {
+  if (platform === "win32") return false;
+  if (!listener?.cwd || !repoRoot) return false;
+  const root = realpath(resolve(repoRoot));
+  const cwd = realpath(resolve(listener.cwd));
+  if (!root || !cwd) return false;
+  if (cwd === root || cwd.startsWith(root.endsWith(sep) ? root : root + sep)) return true;
+  // A dev server started from another worktree of the SAME repository is
+  // still ours (worktree-heavy workflows): both resolve to one common dir.
+  const ours = gitCommonDir(root);
+  return !!ours && ours === gitCommonDir(cwd);
+}
+
+function defaultGitCommonDir(dir) {
+  try {
+    const out = execFileSync("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000 }).trim();
+    return out ? defaultRealpath(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultRealpath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** ESTABLISHED TCP connections on `port` (0 when none, or on Windows). */
+export async function establishedConnections(port, { execFile = nodeExecFile, platform = process.platform } = {}) {
+  if (platform === "win32" || !Number.isInteger(port)) return 0;
+  return parseLsofCount(await run(execFile, "lsof", ["-nP", `-iTCP:${port}`, "-sTCP:ESTABLISHED", "-Fp"]));
+}
+
+/** `port_busy` detail for the card: "used by node (pid 4242, ~/code/other-app)". */
+export function describeBusyPort(port, listener, { home } = {}) {
+  const detail = { port };
+  if (listener?.pid) detail.pid = listener.pid;
+  if (listener?.command) detail.command = listener.command;
+  if (listener?.cwd) detail.cwd = home && listener.cwd.startsWith(home) ? `~${listener.cwd.slice(home.length)}` : listener.cwd;
+  const who = listener ? ` by ${listener.command || "another process"}${listener.pid ? ` (pid ${listener.pid}${detail.cwd ? `, ${detail.cwd}` : ""})` : ""}` : "";
+  return { detail, message: `Port ${port} is already in use${who}.` };
+}

package/src/preview-errors.mjs

@@ -0,0 +1,283 @@
+// Structured preview failures (kai-bridge 0.5.0).
+//
+// Every way a preview can fail to boot ends in ONE payload shape the
+// dashboard turns into a diagnosis with a verb the user can take:
+//
+//   { status: "error", urls: [], error, errorCode, errorKind, errorRepo?,
+//     errorService?, errorDetail?: { pid?, command?, cwd?, dependency?, port?,
+//     envKeys?, remote?, cloneCommand? }, hint?, note?, skipped? }
+//
+// `errorKind` routes the failure: `config` → the repo's setup is wrong
+// (the team gets "Configure"); `machine` / `deps` → this device only
+// (Retry). Log tails are classified BEFORE they are truncated, so a Mongo
+// refusing connections on :27017 becomes `dependency_missing` with the
+// dependency named instead of "web did not start — …".
+//
+// Pure module: no I/O beyond what callers inject (`exists`, `read`).
+
+export const PREVIEW_ERROR_CODES = new Set([
+  "companion_missing",
+  "companion_clone_failed",
+  "companion_unconfigured",
+  "dependency_missing",
+  "port_busy",
+  "deps_failed",
+  "no_dev_config",
+  "service_crashed",
+  "env_missing",
+  "no_browser",
+  "idle_stopped",
+  "daemon_restarted",
+  "other",
+]);
+
+/** Default routing per code (`config` flips the repo to failing; the rest stay per device). */
+export const ERROR_KIND_BY_CODE = {
+  companion_missing: "machine",
+  companion_clone_failed: "machine",
+  companion_unconfigured: "config",
+  dependency_missing: "machine",
+  port_busy: "machine",
+  deps_failed: "deps",
+  no_dev_config: "config",
+  service_crashed: "machine",
+  env_missing: "machine",
+  no_browser: "machine",
+  idle_stopped: "machine",
+  daemon_restarted: "machine",
+  other: "machine",
+};
+
+const DEPENDENCY_BY_PORT = { 27017: "mongodb", 6379: "redis", 5432: "postgres", 3306: "mysql", 9200: "opensearch", 5672: "rabbitmq", 9092: "kafka" };
+
+/** A preview failure the daemon can report without guessing: code + kind + detail travel with it. */
+export class PreviewError extends Error {
+  constructor(message, { code = "other", kind, repo, service, detail, hint } = {}) {
+    super(message);
+    this.name = "PreviewError";
+    this.code = PREVIEW_ERROR_CODES.has(code) ? code : "other";
+    this.kind = kind ?? ERROR_KIND_BY_CODE[this.code] ?? "machine";
+    this.repo = repo ?? null;
+    this.service = service ?? null;
+    this.detail = detail && typeof detail === "object" ? detail : null;
+    this.hint = hint ?? null;
+  }
+}
+
+/**
+ * Classify a service log (the whole tail, not the last three lines) into
+ * `{ code, line, detail }`; null when nothing matches. The FIRST matching
+ * rule wins in order of specificity, and `line` is the matching log line
+ * (trimmed, ≤ 300 chars) — what the dashboard shows as `error`.
+ */
+export function classifyLogTail(text) {
+  const lines = String(text || "")
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\[[0-9;]*m/g, "").trim())
+    .filter(Boolean);
+  const rules = [
+    {
+      re: /ECONNREFUSED\s+(?:127\.0\.0\.1|localhost|::1|\[::1\]):(\d{2,5})/i,
+      build: (m) => ({ code: "dependency_missing", detail: { dependency: DEPENDENCY_BY_PORT[Number(m[1])] ?? `service on :${m[1]}`, port: Number(m[1]) } }),
+    },
+    { re: /MongoServerSelectionError|MongoNetworkError|failed to connect to server \[[^\]]*:27017\]/i, build: () => ({ code: "dependency_missing", detail: { dependency: "mongodb", port: 27017 } }) },
+    { re: /getaddrinfo ENOTFOUND\s+([\w.-]+)/i, build: (m) => ({ code: "dependency_missing", detail: { dependency: m[1] } }) },
+    { re: /EADDRINUSE(?:[^\d]*:(\d{2,5}))?/i, build: (m) => ({ code: "port_busy", detail: m[1] ? { port: Number(m[1]) } : {} }) },
+    // zsh names the missing command AFTER the message ("zsh: command not
+    // found: pnpm"), bash BEFORE it ("sh: vite: command not found"). The
+    // zsh form must be tried first or the shell's own name ("zsh") ends up
+    // on the card as the missing tool.
+    { re: /command not found:\s*([\w.-]+)/i, build: (m) => ({ code: "deps_failed", detail: { command: m[1] } }) },
+    { re: /([\w.-]+): command not found/i, build: (m) => ({ code: "deps_failed", detail: { command: m[1] } }) },
+    { re: /'([\w.-]+)' is not recognized as an internal or external command/i, build: (m) => ({ code: "deps_failed", detail: { command: m[1] } }) },
+    { re: /Cannot find module '([^']+)'|Error: Cannot find package '([^']+)'/i, build: (m) => ({ code: "deps_failed", detail: { dependency: m[1] || m[2] } }) },
+    { re: /ENOSPC/i, build: () => ({ code: "other", detail: { dependency: "disk space" } }) },
+    { re: /Missing required env(?:ironment)? (?:var(?:iable)?s?)?[:\s]*([A-Z0-9_,\s]+)?/i, build: (m) => ({ code: "env_missing", detail: { envKeys: (m[1] || "").split(/[,\s]+/).filter((k) => /^[A-Z][A-Z0-9_]*$/.test(k)) } }) },
+    { re: /\b(?:process\.env\.)?([A-Z][A-Z0-9_]{2,}) is not defined\b/, build: (m) => ({ code: "env_missing", detail: { envKeys: [m[1]] } }) },
+    { re: /\b(?:Missing|undefined) (?:env(?:ironment)? )?(?:variable|var) ([A-Z][A-Z0-9_]{2,})/i, build: (m) => ({ code: "env_missing", detail: { envKeys: [m[1].toUpperCase()] } }) },
+  ];
+  for (const rule of rules) {
+    for (const line of lines) {
+      const m = rule.re.exec(line);
+      if (!m) continue;
+      const built = rule.build(m);
+      return { code: built.code, line: line.slice(0, 300), detail: built.detail };
+    }
+  }
+  return null;
+}
+
+/** The three-line fallback when nothing classifies (kept short for the card). */
+/**
+ * The card's one-line summary of a dead service's log. Stack frames
+ * (`    at …`) are noise — the line that names the failure is the one
+ * with `Error`/`error:`/`failed`/`Cannot`/an errno; take the LAST such
+ * line (the fatal one), then a couple of non-frame lines around it.
+ */
+export function logTailSummary(text, lines = 3) {
+  const all = String(text || "")
+    .trim()
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const isFrame = (l) => /^at\s/.test(l) || /^\s*at\s/.test(l) || /^node:internal/.test(l) || /^\{\s*$|^\}\s*$/.test(l);
+  const isError = (l) => /\b(error|err!|failed|cannot|exception|not found|missing|refused|EADDRINUSE|ENOENT|EACCES|ECONNREFUSED)\b/i.test(l) && !isFrame(l);
+  const errorIdx = all.map((l, i) => (isError(l) ? i : -1)).filter((i) => i >= 0).pop();
+  const base = all.filter((l) => !isFrame(l));
+  let picked;
+  if (errorIdx !== undefined) {
+    const errLine = all[errorIdx];
+    const after = all.slice(errorIdx + 1).filter((l) => !isFrame(l)).slice(0, lines - 1);
+    picked = [errLine, ...after];
+  } else {
+    picked = base.slice(-lines);
+  }
+  if (picked.length === 0) picked = all.slice(-lines);
+  return picked.join(" · ").slice(0, 300);
+}
+
+/**
+ * Build the error payload the daemon posts. `code` defaults to `other`;
+ * `kind` defaults from the code table; `urls` is always emptied on error
+ * (a failed preview must never keep stale links).
+ */
+export function previewErrorPayload({ code = "other", error, kind, repo, service, detail, hint, note, skipped } = {}) {
+  const errorCode = PREVIEW_ERROR_CODES.has(code) ? code : "other";
+  const payload = {
+    status: "error",
+    urls: [],
+    previews: [],
+    error: String(error || "The preview could not be started.").slice(0, 500),
+    errorCode,
+    errorKind: kind ?? ERROR_KIND_BY_CODE[errorCode] ?? "machine",
+  };
+  if (repo) payload.errorRepo = String(repo);
+  if (service) payload.errorService = String(service);
+  if (detail && typeof detail === "object" && Object.keys(detail).length > 0) payload.errorDetail = detail;
+  if (hint) payload.hint = String(hint).slice(0, 300);
+  if (note) payload.note = String(note).slice(0, 300);
+  if (Array.isArray(skipped) && skipped.length > 0) payload.skipped = skipped;
+  return payload;
+}
+
+/** Any thrown error → payload (a PreviewError keeps its code; anything else is classified from its message). */
+export function toPreviewErrorPayload(err, { repo, service, note, skipped } = {}) {
+  if (err instanceof PreviewError) {
+    return previewErrorPayload({ code: err.code, kind: err.kind, error: err.message, repo: err.repo ?? repo, service: err.service ?? service, detail: err.detail, hint: err.hint, note, skipped });
+  }
+  const message = err?.message || String(err);
+  const classified = classifyLogTail(message);
+  return previewErrorPayload({ code: classified?.code ?? "other", error: message, repo, service, detail: classified?.detail, note, skipped });
+}
+
+/**
+ * Dev servers that pop a browser tab (`vite --open`, `next dev -o`) must
+ * not do so on the daemon's machine: strip `--open`, `--open=<x>` and a
+ * standalone `-o` (vite/astro/vitepress spell it that way; `-o <file>`
+ * for other tools is untouched because it takes a value).
+ */
+export function stripOpenFlag(run) {
+  const text = String(run || "");
+  const withoutLong = text.replace(/(^|\s)--open(?:=\S+)?(?=\s|$)/g, "$1");
+  const shortToo = /\b(vite|astro|vitepress)\b/.test(withoutLong) ? withoutLong.replace(/(^|\s)-o(?=\s|$)/g, "$1") : withoutLong;
+  return shortToo.replace(/\s{2,}/g, " ").trim();
+}
+
+const MONOREPO_MARKERS = [
+  ["turbo.json", "turbo"],
+  ["nx.json", "nx"],
+  ["lerna.json", "lerna"],
+  ["pnpm-workspace.yaml", "pnpm workspaces"],
+  ["rush.json", "rush"],
+];
+
+/**
+ * A workspace root (turbo/nx/lerna/pnpm -r/yarn workspaces) has no single
+ * dev command worth guessing: `npm run dev` there fans out into every
+ * package and the preview would point at nothing. Returns `{ hint }` with
+ * the tool's name, or null. `pkg` is the parsed root package.json.
+ */
+export function detectMonorepo(repoRoot, pkg, { exists } = {}) {
+  for (const [file, name] of MONOREPO_MARKERS) {
+    if (exists(`${repoRoot}/${file}`)) return { hint: `monorepo (${name})` };
+  }
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? Object.values(pkg.scripts).join("\n") : "";
+  if (/\bpnpm\s+(?:-r|--recursive)\b|\byarn\s+workspaces?\s+(?:run|foreach)\b|\bturbo\s+run\b|\bnx\s+run(?:-many)?\b|\blerna\s+run\b/.test(scripts)) {
+    return { hint: "monorepo (workspace scripts)" };
+  }
+  if (pkg && (Array.isArray(pkg.workspaces) || (pkg.workspaces && typeof pkg.workspaces === "object"))) return { hint: "monorepo (yarn/npm workspaces)" };
+  return null;
+}
+
+/** dotenv → `{ KEY: value }` (quotes stripped, `export` prefix tolerated, comments skipped). */
+export function parseDotenv(text) {
+  const out = {};
+  for (const raw of String(text || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    else value = value.replace(/\s+#.*$/, "");
+    out[m[1]] = value;
+  }
+  return out;
+}
+
+/**
+ * Keys `.env.example` declares that neither the service's `.env*` files nor
+ * the process env provide — the hint on `env_missing`. Injected `exists` /
+ * `read` keep it pure.
+ */
+export function missingEnvKeys(cwd, { exists, read, env = {} } = {}) {
+  const example = ["/.env.example", "/.env.sample", "/.env.template"].map((n) => `${cwd}${n}`).find((p) => exists(p));
+  if (!example) return [];
+  const wanted = Object.keys(parseDotenv(safeRead(read, example)));
+  if (wanted.length === 0) return [];
+  const present = new Set(Object.keys(env));
+  for (const name of [".env", ".env.local", ".env.development", ".env.development.local"]) {
+    const p = `${cwd}/${name}`;
+    if (!exists(p)) continue;
+    for (const k of Object.keys(parseDotenv(safeRead(read, p)))) present.add(k);
+  }
+  return wanted.filter((k) => !present.has(k));
+}
+
+function safeRead(read, path) {
+  try {
+    return read(path);
+  } catch {
+    return "";
+  }
+}
+
+const PLACEHOLDER_RE = /^(?:changeme|change-me|change_me|replace-?me|todo|tbd|xxx+|your[-_ ].*|<[^>]*>|\$\{[^}]*\}|example.*|.*example\.(?:com|org|net).*|placeholder|secret|password|true|false|null|undefined|none|localhost.*|0+|\d+)$/i;
+
+/** Is this env value worth redacting (≥ 12 chars, not a placeholder, not a URL/number/bool)? */
+export function isRedactableEnvValue(value) {
+  if (typeof value !== "string") return false;
+  const text = value.trim();
+  if (text.length < 12) return false;
+  if (PLACEHOLDER_RE.test(text)) return false;
+  // URLs / connection strings: only ones carrying `user:password@` are secrets.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) return /\/\/[^/@\s]+:[^/@\s]+@/.test(text);
+  if (/^[\d.,\s-]+$/.test(text)) return false;
+  if (/^\d{4}-\d{2}-\d{2}/.test(text)) return false;
+  return true;
+}
+
+/**
+ * Every value from the given dotenv texts that looks like a secret (the
+ * redaction set grows by these so a leaked `.env` value never reaches the
+ * Server in a tool row). Longest first, like `redactionSet`.
+ */
+export function envRedactionValues(texts) {
+  const values = new Set();
+  for (const text of texts || []) {
+    for (const value of Object.values(parseDotenv(text))) {
+      if (isRedactableEnvValue(value)) values.add(value.trim());
+    }
+  }
+  return new Set([...values].sort((a, b) => b.length - a.length));
+}