@luanpdd/kit-mcp 1.1.0 → 1.2.0

package/src/ui/auto-spawn.js

@@ -0,0 +1,108 @@
+// src/ui/auto-spawn.js
+// Spawn the sidecar in a detached subprocess and wait until it's healthy.
+// Used by MCP tool handlers when the caller passes `autoSpawn: true` and no
+// sidecar lockfile is present for the project.
+//
+// Discipline: stderr/file logging only. Audit gate enforced.
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { readLock } from './lockfile.js';
+import { openBrowser } from './browser.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// src/ui → src → repo root → bin/ui.js
+const UI_BIN = path.resolve(HERE, '..', '..', 'bin', 'ui.js');
+
+const POLL_INTERVAL_MS = 100;
+const POLL_TIMEOUT_MS = 5000;
+
+// healthzOk returns true if GET /healthz on this port responds 200 within 1s.
+function healthzOk(port) {
+  return new Promise((resolve) => {
+    const req = http.request({
+      method: 'GET',
+      host: '127.0.0.1',
+      port,
+      path: '/healthz',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, connection: 'close' },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(800, () => { try { req.destroy(); } catch { /* noop */ } resolve(false); });
+    req.end();
+  });
+}
+
+async function waitForHealth(projectRoot, deadline) {
+  // Poll for lockfile + healthz until deadline.
+  while (Date.now() < deadline) {
+    const lock = readLock(projectRoot);
+    if (lock?.port) {
+      // eslint-disable-next-line no-await-in-loop
+      if (await healthzOk(lock.port)) return lock;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  return null;
+}
+
+// ensureSidecar({projectRoot, openBrowser?}): if a sidecar is already running
+// for this projectRoot, returns immediately with its lock metadata. Otherwise
+// spawns bin/ui.js detached and waits for it to come online, then optionally
+// opens the browser. Resolves to:
+//   { ready: true, port, spawned: bool, opened: bool }   on success
+//   { ready: false, reason }                             on timeout/spawn-fail
+export async function ensureSidecar({ projectRoot, openBrowserOnSpawn = true } = {}) {
+  if (!projectRoot) return { ready: false, reason: 'no_project_root' };
+
+  // Already running?
+  const existing = readLock(projectRoot);
+  if (existing?.port) {
+    if (await healthzOk(existing.port)) {
+      return { ready: true, port: existing.port, spawned: false, opened: false };
+    }
+    // Stale lockfile — let the spawn step reclaim it.
+  }
+
+  // Spawn detached. Inherits stderr only — stdout is closed so a buggy child
+  // can never poison parent's stdout (e.g. when the parent is the MCP server
+  // running on stdio).
+  let child;
+  try {
+    child = spawn(process.execPath, [UI_BIN, '--project-root', projectRoot], {
+      detached: true,
+      stdio: ['ignore', 'ignore', 'inherit'],
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (err) {
+    return { ready: false, reason: `spawn_failed: ${err.message}` };
+  }
+
+  // Wait for it to come online.
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  const lock = await waitForHealth(projectRoot, deadline);
+  if (!lock) {
+    return { ready: false, reason: 'healthz_timeout' };
+  }
+
+  let opened = false;
+  if (openBrowserOnSpawn) {
+    const url = `http://127.0.0.1:${lock.port}/`;
+    const r = await openBrowser(url);
+    opened = r.opened === true;
+  }
+
+  return { ready: true, port: lock.port, spawned: true, opened };
+}
+
+export const __test = { healthzOk, UI_BIN, POLL_INTERVAL_MS, POLL_TIMEOUT_MS };

package/src/ui/browser.js

@@ -0,0 +1,78 @@
+// src/ui/browser.js
+// Cross-platform browser opener. Wraps `open@11` with detection for environments
+// where launching a browser silently fails (CI, headless SSH, WSL, sandboxed
+// macOS Terminal). In those environments we DON'T attempt to launch — we just
+// print the URL to stderr so the user can copy it.
+//
+// Discipline: nothing on stdout. Audit gate enforced by Phase 11 CI.
+
+import process from 'node:process';
+
+let openModule = null;
+
+async function loadOpen() {
+  if (openModule) return openModule;
+  try {
+    const mod = await import('open');
+    openModule = mod.default || mod;
+    return openModule;
+  } catch (err) {
+    return null;
+  }
+}
+
+// isHeadless heuristics — designed to err on the side of NOT launching.
+// Returns a reason string when headless, or null when a browser launch is plausible.
+export function detectHeadless(env = process.env, plat = process.platform) {
+  if (env.CI && env.CI !== 'false') return 'CI=' + env.CI;
+  if (env.KIT_MCP_NO_OPEN === '1' || env.KIT_MCP_NO_OPEN === 'true') return 'KIT_MCP_NO_OPEN';
+  if (env.TERM === 'dumb') return 'TERM=dumb';
+  // Linux without a display server is headless. WSL is special: it forwards
+  // to the Windows host browser via wslview, so we let `open` try.
+  if (plat === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    if (env.WSL_DISTRO_NAME || env.WSLENV) return null; // WSL — let `open` try (it'll use wslview)
+    return 'no_display';
+  }
+  // SSH session without local display — no good way to open in user's browser.
+  if (env.SSH_CONNECTION && plat !== 'win32' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    return 'ssh_no_display';
+  }
+  return null;
+}
+
+// openBrowser(url, opts):
+//   { opened: true,  via: 'open' }                    on success
+//   { opened: false, reason: 'headless:<why>', url }  when headless detected
+//   { opened: false, reason: 'no_module' }            if `open` package missing
+//   { opened: false, reason: 'launch_failed:<msg>' }  if open() throws
+//
+// Always calls process.stderr.write with the URL so the user can copy it manually.
+export async function openBrowser(url, { force = false } = {}) {
+  process.stderr.write(`[kit-mcp ui] ${url}\n`);
+
+  if (!force) {
+    const headless = detectHeadless();
+    if (headless) {
+      process.stderr.write(`[kit-mcp ui] not opening browser (${headless}) — open the URL above manually\n`);
+      return { opened: false, reason: `headless:${headless}`, url };
+    }
+  }
+
+  const open = await loadOpen();
+  if (!open) {
+    process.stderr.write('[kit-mcp ui] `open` package not available — open the URL above manually\n');
+    return { opened: false, reason: 'no_module' };
+  }
+
+  try {
+    // open() returns a child process; we don't await its exit (it's the browser).
+    // We just need to know that the spawn succeeded.
+    await open(url);
+    return { opened: true, via: 'open' };
+  } catch (err) {
+    process.stderr.write(`[kit-mcp ui] browser launch failed: ${err.message} — open the URL above manually\n`);
+    return { opened: false, reason: `launch_failed:${err.message}` };
+  }
+}
+
+export const __test = { loadOpen };

package/src/ui/client.js

@@ -0,0 +1,115 @@
+// src/ui/client.js
+// Fire-and-forget publisher. Reads the lockfile to discover the running sidecar's
+// port, then POSTs an event to /publish. If the sidecar isn't running (no lockfile,
+// ECONNREFUSED, healthz mismatch), publish() resolves silently — publishers MUST NOT
+// fail just because the optional UI isn't up.
+
+import http from 'node:http';
+import { readLock } from './lockfile.js';
+import { validateEvent } from './events.js';
+
+// Cache the resolved port across calls in a single process.
+const portCache = new Map(); // projectRoot -> port (or 0 = no sidecar)
+const PORT_CACHE_TTL_MS = 5_000;
+const cacheTimestamps = new Map();
+
+function readCachedPort(projectRoot) {
+  const ts = cacheTimestamps.get(projectRoot);
+  if (!ts || Date.now() - ts > PORT_CACHE_TTL_MS) return undefined;
+  return portCache.get(projectRoot);
+}
+
+function writeCachedPort(projectRoot, port) {
+  portCache.set(projectRoot, port);
+  cacheTimestamps.set(projectRoot, Date.now());
+}
+
+export function clearPortCache() {
+  portCache.clear();
+  cacheTimestamps.clear();
+}
+
+function resolvePort(projectRoot) {
+  const cached = readCachedPort(projectRoot);
+  if (cached !== undefined) return cached;
+  const lock = readLock(projectRoot);
+  const port = lock?.port ?? 0;
+  writeCachedPort(projectRoot, port);
+  return port;
+}
+
+// publish(event, { projectRoot, timeoutMs }): always resolves. Returns
+//   { sent: true, status }    on 2xx
+//   { sent: false, reason }   in every other case (no sidecar, validation, network)
+export async function publish(event, { projectRoot, timeoutMs = 1500 } = {}) {
+  if (!projectRoot) return { sent: false, reason: 'no_project_root' };
+
+  const validationErr = validateEvent(event);
+  if (validationErr) return { sent: false, reason: `invalid_event: ${validationErr.message}` };
+
+  const port = resolvePort(projectRoot);
+  if (!port) return { sent: false, reason: 'no_sidecar' };
+
+  const body = JSON.stringify(event);
+
+  return new Promise((resolve) => {
+    const req = http.request({
+      method: 'POST',
+      host: '127.0.0.1',
+      port,
+      path: '/publish',
+      agent: false,
+      headers: {
+        'host': `127.0.0.1:${port}`,
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body, 'utf8'),
+        'origin': `http://127.0.0.1:${port}`,
+        'connection': 'close',
+      },
+    }, (res) => {
+      // Drain — we don't actually care about the body, just the status.
+      res.resume();
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ sent: true, status: res.statusCode });
+        } else {
+          // Stale lockfile? Drop the cache so the next call re-reads.
+          if (res.statusCode === 403 || res.statusCode === 404) {
+            portCache.delete(projectRoot);
+            cacheTimestamps.delete(projectRoot);
+          }
+          resolve({ sent: false, reason: `http_${res.statusCode}` });
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      // Most common: ECONNREFUSED (lockfile points at a dead port).
+      if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET') {
+        portCache.delete(projectRoot);
+        cacheTimestamps.delete(projectRoot);
+      }
+      resolve({ sent: false, reason: `error: ${err.code || err.message}` });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      try { req.destroy(); } catch { /* noop */ }
+      resolve({ sent: false, reason: 'timeout' });
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+// publishMany emits a sequence of events one after another. Used by callers
+// that want best-effort guaranteed ordering — http.request is async, so
+// firing in parallel doesn't preserve order at the server.
+export async function publishMany(events, opts) {
+  const results = [];
+  for (const evt of events) {
+    // eslint-disable-next-line no-await-in-loop
+    results.push(await publish(evt, opts));
+  }
+  return results;
+}

package/src/ui/events.js

@@ -0,0 +1,65 @@
+// src/ui/events.js
+// Schema and helpers for sidecar event payloads.
+// Pure module: no I/O, no module-level state. Safe to import from any context.
+
+import { randomBytes } from 'node:crypto';
+
+export const EVENT_TYPES = Object.freeze([
+  'run.start',
+  'run.end',
+  'tool_invocation',
+  'progress',
+  'milestone',
+  'error',
+  'shutdown',
+]);
+
+export const EVENT_TYPE_SET = new Set(EVENT_TYPES);
+
+const MAX_PAYLOAD_BYTES = 64 * 1024;
+
+export function newRunId() {
+  return randomBytes(8).toString('hex');
+}
+
+export function makeEvent({ type, runId, payload, ts }) {
+  if (!EVENT_TYPE_SET.has(type)) {
+    throw new TypeError(`Unknown event type: ${type}. Valid: ${EVENT_TYPES.join(', ')}`);
+  }
+  return {
+    type,
+    ts: typeof ts === 'number' ? ts : Date.now(),
+    runId: runId ?? null,
+    payload: payload ?? null,
+  };
+}
+
+// validateEvent returns null on success, or an Error explaining the rejection.
+// Used by the server's POST /publish endpoint. Never throws.
+export function validateEvent(value) {
+  if (value === null || typeof value !== 'object') {
+    return new Error('event must be an object');
+  }
+  if (!EVENT_TYPE_SET.has(value.type)) {
+    return new Error(`event.type must be one of ${EVENT_TYPES.join(', ')}`);
+  }
+  if (typeof value.ts !== 'number' || !Number.isFinite(value.ts)) {
+    return new Error('event.ts must be a finite number (epoch ms)');
+  }
+  if (value.runId !== null && value.runId !== undefined && typeof value.runId !== 'string') {
+    return new Error('event.runId must be string or null');
+  }
+  // payload may be anything serializable; cap raw size
+  let serialized;
+  try {
+    serialized = JSON.stringify(value);
+  } catch (err) {
+    return new Error(`event not serializable: ${err.message}`);
+  }
+  if (Buffer.byteLength(serialized, 'utf8') > MAX_PAYLOAD_BYTES) {
+    return new Error(`event exceeds ${MAX_PAYLOAD_BYTES} bytes (got ${Buffer.byteLength(serialized, 'utf8')})`);
+  }
+  return null;
+}
+
+export const __test = { MAX_PAYLOAD_BYTES };

package/src/ui/lockfile.js

@@ -0,0 +1,147 @@
+// src/ui/lockfile.js
+// Single-instance lockfile per projectRoot, located in os.tmpdir().
+//
+// Atomic create via fs.openSync(path, 'wx') (O_EXCL semantics — fails if file exists).
+// Stale detection in two layers:
+//   1. process.kill(pid, 0) — ESRCH/EPERM means the holder is gone
+//   2. optional HTTP healthz probe (injected by caller; keeps this module pure of net)
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+export const LOCK_VERSION = 1;
+
+export function lockPathFor(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('projectRoot must be a non-empty string');
+  }
+  const hash = createHash('sha1').update(projectRoot).digest('hex').slice(0, 16);
+  return path.join(os.tmpdir(), `kit-mcp-ui-${hash}.lock`);
+}
+
+// readLock returns parsed lockfile content, or null if the file doesn't exist
+// or is unreadable/unparseable. Never throws.
+export function readLock(projectRoot) {
+  const file = lockPathFor(projectRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.pid === 'number') {
+      return { ...parsed, _path: file };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// acquireLock attempts to create the lockfile atomically. On success returns
+// the lock metadata. On EEXIST, throws an Error tagged with .code = 'ELOCKED'
+// — the caller is expected to call probeStale + maybe retry.
+export function acquireLock({ projectRoot, port, version, startedAt }) {
+  const file = lockPathFor(projectRoot);
+  const meta = {
+    pid: process.pid,
+    port,
+    version: version ?? null,
+    startedAt: startedAt ?? Date.now(),
+    lockSchema: LOCK_VERSION,
+  };
+  let fd;
+  try {
+    fd = fs.openSync(file, 'wx');
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      const lockErr = new Error(`Lockfile already exists: ${file}`);
+      lockErr.code = 'ELOCKED';
+      lockErr.path = file;
+      throw lockErr;
+    }
+    throw err;
+  }
+  try {
+    fs.writeSync(fd, JSON.stringify(meta, null, 2));
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { ...meta, _path: file };
+}
+
+export function releaseLock(projectRoot) {
+  const file = lockPathFor(projectRoot);
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+// probeStale checks if the lockfile holder is still alive.
+// Uses two strategies in order:
+//   1. process.kill(pid, 0) — synchronous, no network. ESRCH = dead, EPERM = different user (rare on dev box, treat as alive to be safe).
+//   2. healthzProbe(port) — optional async function injected by caller. Should return truthy if the holder responds OK.
+//
+// Returns:
+//   { stale: false, reason: 'pid_alive' }       — process exists
+//   { stale: false, reason: 'healthz_ok' }      — process exists AND healthz responded
+//   { stale: true,  reason: 'pid_gone' }        — pid is ESRCH
+//   { stale: true,  reason: 'healthz_failed' }  — pid alive but no healthz response (used when healthzProbe provided)
+export async function probeStale(lock, { healthzProbe } = {}) {
+  if (!lock || typeof lock.pid !== 'number') {
+    return { stale: true, reason: 'invalid_lock' };
+  }
+  let pidAlive = false;
+  try {
+    process.kill(lock.pid, 0);
+    pidAlive = true;
+  } catch (err) {
+    if (err.code === 'ESRCH') {
+      return { stale: true, reason: 'pid_gone' };
+    }
+    // EPERM: pid exists but is owned by another user. Treat as alive (safe default).
+    pidAlive = true;
+  }
+  if (!healthzProbe) {
+    return { stale: false, reason: 'pid_alive' };
+  }
+  try {
+    const ok = await healthzProbe(lock.port);
+    if (ok) return { stale: false, reason: 'healthz_ok' };
+    return { stale: true, reason: 'healthz_failed' };
+  } catch {
+    return { stale: true, reason: 'healthz_failed' };
+  }
+}
+
+// Convenience: take + retry once if stale lock is detected.
+export async function acquireLockOrReclaim(opts) {
+  try {
+    return acquireLock(opts);
+  } catch (err) {
+    if (err.code !== 'ELOCKED') throw err;
+    const existing = readLock(opts.projectRoot);
+    const probe = await probeStale(existing, { healthzProbe: opts.healthzProbe });
+    if (probe.stale) {
+      releaseLock(opts.projectRoot);
+      return acquireLock(opts);
+    }
+    const liveErr = new Error(
+      `Sidecar already running for this project (pid=${existing?.pid}, port=${existing?.port}). ` +
+      `Use \`kit ui status\` to inspect or \`kit ui stop\` to shut it down.`,
+    );
+    liveErr.code = 'ELIVE';
+    liveErr.lock = existing;
+    throw liveErr;
+  }
+}

package/src/ui/port.js

@@ -0,0 +1,67 @@
+// src/ui/port.js
+// Find a free TCP port within a bounded range.
+// Pure utility: no module-level state, no logging.
+
+import net from 'node:net';
+
+export const DEFAULT_PORT_RANGE = Object.freeze({ start: 7100, end: 7199 });
+
+// Probes a single port: resolves to true if free (could bind+close), false if taken.
+function probePort(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    let settled = false;
+    const finish = (free) => {
+      if (settled) return;
+      settled = true;
+      server.removeAllListeners();
+      try { server.close(); } catch { /* ignore */ }
+      resolve(free);
+    };
+    server.once('error', () => finish(false));
+    server.once('listening', () => finish(true));
+    try {
+      server.listen(port, host);
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+// findFreePort scans [start..end] inclusive on host (default 127.0.0.1) and
+// returns the first port where a transient bind succeeds. Returns null if none.
+//
+// Race note: between probe-close and the caller's bind, the port can be
+// reclaimed by another process. The lockfile + healthz probe in upper layers
+// covers this — port.js is best-effort discovery, not exclusive reservation.
+export async function findFreePort({
+  start = DEFAULT_PORT_RANGE.start,
+  end = DEFAULT_PORT_RANGE.end,
+  host = '127.0.0.1',
+} = {}) {
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start > end) {
+    throw new TypeError(`invalid port range: ${start}..${end}`);
+  }
+  for (let port = start; port <= end; port += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await probePort(port, host)) {
+      return port;
+    }
+  }
+  return null;
+}
+
+// findFreePortOrThrow is the eager variant — surfaces an error message that
+// includes the exhausted range, so callers don't have to format it.
+export async function findFreePortOrThrow(opts = {}) {
+  const port = await findFreePort(opts);
+  if (port === null) {
+    const start = opts.start ?? DEFAULT_PORT_RANGE.start;
+    const end = opts.end ?? DEFAULT_PORT_RANGE.end;
+    throw new Error(
+      `No free TCP port in ${start}..${end} (host ${opts.host ?? '127.0.0.1'}). ` +
+      `Run \`kit ui status\` to inspect a running sidecar, or kill whatever is using these ports.`,
+    );
+  }
+  return port;
+}