@luanpdd/kit-mcp 1.27.0 → 1.28.0

package/src/core/watch.js

@@ -1,121 +1,121 @@
-// Watch the canonical kit/ and re-sync to one or more IDE targets on every change.
-//
-// Usage from CLI: `kit sync watch <target...> [--all]`
-// Usage from code: `await watchKit(['claude-code', 'cursor'], opts) → { stop }`
-//
-// Behavior:
-//   - Initial full sync to each target on start
-//   - Debounced re-sync (default 300ms) on add/change/unlink under kit/
-//   - Per-event log to opts.onLog (defaults to no-op so callers control output)
-//   - Returns { stop } to cleanly tear down the watcher
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { syncTo } from './sync.js';
-import { listTargets } from './registry.js';
-import { resolveKitRoot, clearKitCache } from './kit.js';
-
-// PERF-16-06: chokidar é optionalDependency. Carregamos lazy dentro de watchKit()
-// para que (a) `kit sync install` (que NÃO usa watch) não pague o custo de boot,
-// e (b) `npm install --omit=optional` produza CLI core funcional (apenas
-// `kit sync watch` falha com mensagem descritiva).
-let _chokidarModule = null;
-async function loadChokidar() {
-  if (_chokidarModule) return _chokidarModule;
-  try {
-    const mod = await import('chokidar');
-    _chokidarModule = mod.default || mod;
-    return _chokidarModule;
-  } catch (err) {
-    throw new Error(
-      'kit sync watch requires chokidar. Install with `npm i chokidar` or use `kit sync install <target>` for one-shot syncing instead.'
-    );
-  }
-}
-
-export async function watchKit(targets, opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const kitRoot     = resolveKitRoot(opts.kitRoot);
-  const mode        = opts.mode ?? 'reference';
-  // PERF-16-02: bump default 300 → 500ms to coalesce IDE save-bursts (typical
-  // IDE auto-save fires 5-10 events in < 500ms during a single user save).
-  const debounceMs  = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 500;
-  const onLog       = opts.onLog ?? (() => {});
-
-  if (!Array.isArray(targets) || targets.length === 0) {
-    throw new Error('watchKit: targets[] required (or use detectTargets()).');
-  }
-
-  // Initial sync
-  for (const t of targets) {
-    const r = await syncTo(t, { projectRoot, kitRoot, mode });
-    onLog(`✓ initial sync → ${t} (${r.written.length} files)`);
-  }
-
-  const chokidar = await loadChokidar();
-  const watcher = chokidar.watch(kitRoot, {
-    ignored: (p) => /(^|[/\\])\.[^/\\]/.test(p),  // ignore dotfiles/dotdirs
-    persistent: true,
-    ignoreInitial: true,
-    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
-  });
-
-  let pending = null;
-  const trigger = (label, p) => {
-    onLog(`${label} ${path.relative(kitRoot, p)}`);
-    if (pending) clearTimeout(pending);
-    pending = setTimeout(async () => {
-      pending = null;
-      // PERF-16-02: invalidate kitCache (TTL 30s in kit.js PERF-01) BEFORE
-      // re-sync — otherwise listKit() inside syncTo can return the pre-edit
-      // cached value if the burst happened within the TTL window. Coalescing
-      // the edit-burst via debounce means clearKitCache fires AT MOST ONCE
-      // per 500ms window, regardless of how many save events came in.
-      clearKitCache();
-      for (const t of targets) {
-        try {
-          const r = await syncTo(t, { projectRoot, kitRoot, mode });
-          onLog(`↻ resynced → ${t} (${r.written.length} files)`);
-        } catch (e) {
-          onLog(`✗ resync → ${t}: ${e.message}`);
-        }
-      }
-    }, debounceMs);
-  };
-
-  watcher.on('add',    (p) => trigger('+', p));
-  watcher.on('change', (p) => trigger('~', p));
-  watcher.on('unlink', (p) => trigger('-', p));
-  watcher.on('error',  (e) => onLog(`! watcher error: ${e.message}`));
-
-  return {
-    stop: async () => {
-      if (pending) { clearTimeout(pending); pending = null; }
-      await watcher.close();
-      onLog('watcher stopped');
-    },
-  };
-}
-
-// Detect which targets currently have any files projected into projectRoot.
-// Used by `--all` so the user doesn't have to re-list IDEs they already synced to.
-export async function detectExistingTargets(opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const all = listTargets();
-  const existing = [];
-  for (const t of all) {
-    // We just check if at least one of the capability directories/files exists.
-    const probes = [];
-    const reg = (await import('./registry.js')).getTarget(t.id);
-    if (reg.rules)    probes.push(path.join(projectRoot, reg.rules.path));
-    if (reg.agents)   probes.push(path.join(projectRoot, reg.agents.path));
-    if (reg.commands) probes.push(path.join(projectRoot, reg.commands.path));
-    if (reg.skills)   probes.push(path.join(projectRoot, reg.skills.path));
-    let found = false;
-    for (const p of probes) {
-      try { await fs.access(p); found = true; break; } catch {}
-    }
-    if (found) existing.push(t.id);
-  }
-  return existing;
-}
+// Watch the canonical kit/ and re-sync to one or more IDE targets on every change.
+//
+// Usage from CLI: `kit sync watch <target...> [--all]`
+// Usage from code: `await watchKit(['claude-code', 'cursor'], opts) → { stop }`
+//
+// Behavior:
+//   - Initial full sync to each target on start
+//   - Debounced re-sync (default 300ms) on add/change/unlink under kit/
+//   - Per-event log to opts.onLog (defaults to no-op so callers control output)
+//   - Returns { stop } to cleanly tear down the watcher
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { syncTo } from './sync.js';
+import { listTargets } from './registry.js';
+import { resolveKitRoot, clearKitCache } from './kit.js';
+
+// PERF-16-06: chokidar é optionalDependency. Carregamos lazy dentro de watchKit()
+// para que (a) `kit sync install` (que NÃO usa watch) não pague o custo de boot,
+// e (b) `npm install --omit=optional` produza CLI core funcional (apenas
+// `kit sync watch` falha com mensagem descritiva).
+let _chokidarModule = null;
+async function loadChokidar() {
+  if (_chokidarModule) return _chokidarModule;
+  try {
+    const mod = await import('chokidar');
+    _chokidarModule = mod.default || mod;
+    return _chokidarModule;
+  } catch (err) {
+    throw new Error(
+      'kit sync watch requires chokidar. Install with `npm i chokidar` or use `kit sync install <target>` for one-shot syncing instead.'
+    );
+  }
+}
+
+export async function watchKit(targets, opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const kitRoot     = resolveKitRoot(opts.kitRoot);
+  const mode        = opts.mode ?? 'reference';
+  // PERF-16-02: bump default 300 → 500ms to coalesce IDE save-bursts (typical
+  // IDE auto-save fires 5-10 events in < 500ms during a single user save).
+  const debounceMs  = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 500;
+  const onLog       = opts.onLog ?? (() => {});
+
+  if (!Array.isArray(targets) || targets.length === 0) {
+    throw new Error('watchKit: targets[] required (or use detectTargets()).');
+  }
+
+  // Initial sync
+  for (const t of targets) {
+    const r = await syncTo(t, { projectRoot, kitRoot, mode });
+    onLog(`✓ initial sync → ${t} (${r.written.length} files)`);
+  }
+
+  const chokidar = await loadChokidar();
+  const watcher = chokidar.watch(kitRoot, {
+    ignored: (p) => /(^|[/\\])\.[^/\\]/.test(p),  // ignore dotfiles/dotdirs
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+  });
+
+  let pending = null;
+  const trigger = (label, p) => {
+    onLog(`${label} ${path.relative(kitRoot, p)}`);
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(async () => {
+      pending = null;
+      // PERF-16-02: invalidate kitCache (TTL 30s in kit.js PERF-01) BEFORE
+      // re-sync — otherwise listKit() inside syncTo can return the pre-edit
+      // cached value if the burst happened within the TTL window. Coalescing
+      // the edit-burst via debounce means clearKitCache fires AT MOST ONCE
+      // per 500ms window, regardless of how many save events came in.
+      clearKitCache();
+      for (const t of targets) {
+        try {
+          const r = await syncTo(t, { projectRoot, kitRoot, mode });
+          onLog(`↻ resynced → ${t} (${r.written.length} files)`);
+        } catch (e) {
+          onLog(`✗ resync → ${t}: ${e.message}`);
+        }
+      }
+    }, debounceMs);
+  };
+
+  watcher.on('add',    (p) => trigger('+', p));
+  watcher.on('change', (p) => trigger('~', p));
+  watcher.on('unlink', (p) => trigger('-', p));
+  watcher.on('error',  (e) => onLog(`! watcher error: ${e.message}`));
+
+  return {
+    stop: async () => {
+      if (pending) { clearTimeout(pending); pending = null; }
+      await watcher.close();
+      onLog('watcher stopped');
+    },
+  };
+}
+
+// Detect which targets currently have any files projected into projectRoot.
+// Used by `--all` so the user doesn't have to re-list IDEs they already synced to.
+export async function detectExistingTargets(opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const all = listTargets();
+  const existing = [];
+  for (const t of all) {
+    // We just check if at least one of the capability directories/files exists.
+    const probes = [];
+    const reg = (await import('./registry.js')).getTarget(t.id);
+    if (reg.rules)    probes.push(path.join(projectRoot, reg.rules.path));
+    if (reg.agents)   probes.push(path.join(projectRoot, reg.agents.path));
+    if (reg.commands) probes.push(path.join(projectRoot, reg.commands.path));
+    if (reg.skills)   probes.push(path.join(projectRoot, reg.skills.path));
+    let found = false;
+    for (const p of probes) {
+      try { await fs.access(p); found = true; break; } catch {}
+    }
+    if (found) existing.push(t.id);
+  }
+  return existing;
+}

package/src/mcp-server/index.js

@@ -32,6 +32,8 @@ import { installMcp, listInstallTargets } from './install.js';
 import { ensureSidecar } from '../ui/auto-spawn.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
 import { incrementInvocation, recordLatency, snapshot as metricsSnapshot, persistSnapshot } from '../core/metrics.js';
+import { logEvent } from '../core/logger.js';
+import { notify, isNotifyEnabled } from '../core/notify.js';
 
 const TOOLS = [
   {
@@ -384,18 +386,58 @@ export async function createServer() {
     // being ready. Date.now() is sub-millisecond-cheap and aligns with the bucket
     // granularity we report (50/100/250/500ms thresholds in CONTEXT.md).
     const start = Date.now();
+    const argsSize = args ? JSON.stringify(args).length : 0;
     try {
       const result = await handler(args ?? {});
-      recordLatency(name, Date.now() - start);
+      const duration = Date.now() - start;
+      recordLatency(name, duration);
       incrementInvocation(name, 'ok');
+      // Phase 158 (v1.28): JSONL log per tool call → ~/.kit-mcp/logs/*.log.
+      // Fire-and-forget; never blocks the handler.
+      try {
+        const ev = {
+          tool: name,
+          action: args?.action,
+          args_size: argsSize,
+          result_size: result ? JSON.stringify(result).length : 0,
+          duration_ms: duration,
+          status: 'ok',
+        };
+        // Phase 163 (v1.28): when KIT_MCP_INSPECT=1, also capture raw args/result
+        // so `kit inspect` can render full request/response live. Off by default
+        // because payloads can be large and may contain user paths.
+        if (process.env.KIT_MCP_INSPECT === '1' || process.env.KIT_MCP_INSPECT === 'true') {
+          ev.args = args ?? null;
+          ev.result = result ?? null;
+        }
+        logEvent(ev);
+      } catch { /* swallow */ }
+      // Phase 164 (v1.28): opt-in OS notification on success path.
+      if (isNotifyEnabled()) {
+        try { notify({ title: `kit-mcp ${name}`, body: `${args?.action ?? ''} ok (${duration}ms)` }); } catch { /* swallow */ }
+      }
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
       // OBS-18: still record latency on the error path — half the value of a
       // latency histogram is catching tail-latency-then-fail patterns. Status
       // 'error' covers any thrown exception, including Phase 79.01 gates guard
       // and the validateProjectRoot rejection (Phase 83.01).
-      recordLatency(name, Date.now() - start);
+      const duration = Date.now() - start;
+      recordLatency(name, duration);
       incrementInvocation(name, 'error');
+      try {
+        logEvent({
+          tool: name,
+          action: args?.action,
+          args_size: argsSize,
+          duration_ms: duration,
+          status: 'error',
+          error_type: e?.code || e?.name || 'Error',
+        });
+      } catch { /* swallow */ }
+      if (isNotifyEnabled()) {
+        try { notify({ title: `kit-mcp ${name} (error)`, body: e?.code || e?.name || 'Error' }); } catch { /* swallow */ }
+      }
       // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
       // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
       // EMANIFESTMISMATCH invariant), and emits NO stack field.
@@ -424,4 +466,25 @@ export async function startStdio() {
   // the boot path, where it's invisible behind IDE startup. See skill
   // production-readiness-review (Performance axe) for the rationale.
   listKit(BUNDLED_KIT_ROOT).catch(() => {});
+
+  // Phase 157 (v1.28): sidecar UI auto-spawn ON by default. Resolves the
+  // "kit-mcp has no terminal feedback" pain — operators can now see live
+  // tool calls in a browser without needing to set autoSpawn: true per tool.
+  // Escape hatch: KIT_MCP_NO_UI=1 (CI, headless, opt-out). Fire-and-forget:
+  // sidecar failure must never block the MCP transport (spec requires clean
+  // stdout). Errors are swallowed silently — kit doctor will surface them.
+  //
+  // Skip when running under node --test (or coverage) to avoid leaking detached
+  // child processes that hold the event loop and cause non-zero exits. Same
+  // for CI=true (GitHub Actions, etc.) — sidecar is interactive and meaningless
+  // there. End users running locally still get the default-on behavior.
+  const isTestRun = (process.execArgv || []).some(
+    (a) => a === '--test' || a === '--experimental-test-coverage',
+  ) || process.env.NODE_TEST_CONTEXT !== undefined;
+  const noUi = process.env.KIT_MCP_NO_UI === '1' || process.env.KIT_MCP_NO_UI === 'true';
+  const isCi = process.env.CI === 'true' || process.env.CI === '1';
+  if (!noUi && !isTestRun && !isCi) {
+    const projectRoot = process.cwd();
+    ensureSidecar({ projectRoot, openBrowserOnSpawn: false }).catch(() => {});
+  }
 }