@luanpdd/kit-mcp 1.15.0 → 1.17.0

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.15.0",
-  "timestamp": "2026-05-09T13:10:19.305Z",
+  "version": "1.17.0",
+  "timestamp": "2026-05-09T15:58:57.716Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {
@@ -47,11 +47,13 @@
     "prepublishOnly": "node scripts/regen-manifest.js && node scripts/update-readme-counts.js && node test/run.mjs test/unit && node test/run.mjs test/integration"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.4.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "chokidar": "^5.0.0",
     "commander": "^14.0.3",
-    "open": "^11.0.0",
     "picocolors": "^1.1.1"
+  },
+  "optionalDependencies": {
+    "@inquirer/prompts": "^8.4.2",
+    "chokidar": "^5.0.0",
+    "open": "^11.0.0"
   }
 }

package/src/cli/index.js

@@ -29,11 +29,16 @@ import { listReplays, loadReplay } from '../core/replays.js';
 import { installMcp, listInstallTargets } from '../mcp-server/install.js';
 import * as render from './render.js';
 import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
-import { createServer } from '../ui/server.js';
 import { readLock, lockPathFor } from '../ui/lockfile.js';
-import { wrapProgressForUi } from '../ui/wrapper.js';
-import { openBrowser } from '../ui/browser.js';
-import { checkUpgrade, getLocalVersion } from './upgrade-check.js';
+import { checkUpgrade } from './upgrade-check.js';
+// PERF-16-04: ui/server.js, ui/wrapper.js, ui/browser.js are loaded LAZILY
+// inside the subcommand handlers that need them. See:
+//   - maybeWrapForUi (gated on lockfile presence)
+//   - ui.start (createServer + openBrowser)
+//   - ui.open  (openBrowser)
+// This trims ~700 LOC + transitive deps off the cold-start path of non-UI
+// commands like `kit kit list-agents --terse`. lockfile.js stays eager because
+// readLock() is called by every withProgress() invocation and is dep-free.
 import http from 'node:http';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -106,7 +111,7 @@ async function withProgress(label, total, fn, { tool, projectRoot } = {}) {
   }
 
   // Auto-wrap if a sidecar is running for this projectRoot.
-  const wrapper = maybeWrapForUi(onProgress, { tool, projectRoot });
+  const wrapper = await maybeWrapForUi(onProgress, { tool, projectRoot });
   try {
     const r = await fn(wrapper);
     if (p) p.finish(label);
@@ -121,7 +126,11 @@ async function withProgress(label, total, fn, { tool, projectRoot } = {}) {
 
 // maybeWrapForUi — returns the original callback unchanged when no sidecar is up
 // or the user opted out. Otherwise returns a wrapped callback with .done/.error.
-function maybeWrapForUi(onProgress, { tool, projectRoot } = {}) {
+//
+// PERF-16-04: this is async because we lazy-load ../ui/wrapper.js only when a
+// sidecar lockfile is detected. Common path (no sidecar) returns synchronously
+// via passthroughWrapper without touching wrapper.js or its transitive deps.
+async function maybeWrapForUi(onProgress, { tool, projectRoot } = {}) {
   const globalOpts = program.opts();
   // commander stores `--no-ui` as opts.ui === false
   if (globalOpts.ui === false || process.env.KIT_MCP_NO_UI === '1') {
@@ -131,6 +140,8 @@ function maybeWrapForUi(onProgress, { tool, projectRoot } = {}) {
   if (!readLock(root)) {
     return passthroughWrapper(onProgress);
   }
+  // Lazy import — only paid when a sidecar IS up for this project.
+  const { wrapProgressForUi } = await import('../ui/wrapper.js');
   return wrapProgressForUi(onProgress, { projectRoot: root, tool: tool ?? null });
 }
 
@@ -407,6 +418,8 @@ ui.command('start')
     const projectRoot = opts.projectRoot || process.cwd();
     const port = opts.port ? Number(opts.port) : undefined;
     const idleMs = opts.idleMs !== undefined ? Number(opts.idleMs) : undefined;
+    // PERF-16-04: lazy-load the sidecar HTTP server module only when starting it.
+    const { createServer } = await import('../ui/server.js');
     const srv = createServer({ projectRoot, idleMs });
     try {
       const { port: actualPort } = await srv.start({ port });
@@ -422,6 +435,8 @@ ui.command('start')
         }
       }).catch(() => { /* offline / silent */ });
       if (opts.open !== false) {
+        // PERF-16-04: lazy-load browser-opener (it lazy-loads `open` package itself).
+        const { openBrowser } = await import('../ui/browser.js');
         await openBrowser(url);
       }
       // The server's own SIGINT handler will perform shutdown + cleanup.
@@ -480,6 +495,8 @@ ui.command('open')
     const lock = readLock(projectRoot);
     if (!lock) return fail('no sidecar running — start one with `kit ui start`');
     const url = `http://127.0.0.1:${lock.port}/`;
+    // PERF-16-04: lazy-load browser-opener.
+    const { openBrowser } = await import('../ui/browser.js');
     const r = await openBrowser(url, { force: true });
     if (!r.opened) {
       process.stderr.write(`${c.yellow(icons.warn)} could not open browser (${r.reason}); copy the URL above\n`);

package/src/core/manifest-verify.js

@@ -14,8 +14,39 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
 
+// PERF-17-01: parallelize SHA256 hashing in batches of 16. Same pattern
+// as Phase 88.01 sync.js. Hardcoded — env override is overengineering
+// for verifyManifest (single hot path, not user-facing latency budget).
+const BATCH_SIZE = 16;
+
+// PERF-17-01: in-memory cache for verifyManifest. Same pattern as kit.js
+// listKit cache (PERF-01). Watch triggers (file save → re-sync) call this
+// back-to-back; the 2nd+ call within TTL hits cache and returns <5ms.
+//
+// Caching rules:
+//   - Only cache ok=true results. mismatches/missing → recompute every call
+//     so devs see fixes immediately (don't punish them for the slow path).
+//   - Bypass via KIT_MCP_VERIFY_NO_CACHE=1 (test isolation + emergency dev escape).
+//   - Cache key is kitRoot — different roots are independent entries.
+const VERIFY_CACHE_TTL_MS = 30_000;
+const verifyManifestCache = new Map(); // kitRoot -> { value, ts }
+const NO_CACHE_ENV = 'KIT_MCP_VERIFY_NO_CACHE';
+
+/**
+ * Test/emergency helper — clears the cache. Exported for unit tests.
+ * Production code should never need this; use the env var instead.
+ */
+export function clearVerifyManifestCache() { verifyManifestCache.clear(); }
+
 const SKIP_ENV = 'KIT_MCP_SKIP_MANIFEST_CHECK';
 
+/**
+ * SEC-14-05: verify kit/file-manifest.json against actual file contents.
+ * PERF-17-01: hashes in Promise.all batches of 16 (was sequential pre-v1.17).
+ * Called by syncTo() in install path before any write — refuses to project a tampered kit.
+ * @param {string} kitRoot - absolute path to kit/ directory.
+ * @returns {Promise<{ok: boolean, skipped?: boolean, reason?: string, mismatches?: Array, missing?: string[]}>}
+ */
 export async function verifyManifest(kitRoot) {
   if (process.env[SKIP_ENV] === '1') {
     process.stderr.write(
@@ -24,6 +55,15 @@ export async function verifyManifest(kitRoot) {
     return { ok: true, skipped: true };
   }
 
+  // PERF-17-01: cache hit — repeated calls within TTL skip the I/O + hashing.
+  // Bypass via KIT_MCP_VERIFY_NO_CACHE=1 (tests + dev emergency escape).
+  if (process.env[NO_CACHE_ENV] !== '1') {
+    const cached = verifyManifestCache.get(kitRoot);
+    if (cached && Date.now() - cached.ts < VERIFY_CACHE_TTL_MS) {
+      return cached.value;
+    }
+  }
+
   const manifestPath = path.join(kitRoot, 'file-manifest.json');
   let manifest;
   try {
@@ -50,27 +90,54 @@ export async function verifyManifest(kitRoot) {
   const mismatches = [];
   const missing = [];
 
-  for (const [rel, expected] of Object.entries(manifest.files)) {
+  const entries = Object.entries(manifest.files);
+
+  // Per-file check — returns { rel, status: 'ok'|'mismatch'|'missing', expected?, actual? }.
+  // Pure function (no side effects on shared arrays) so Promise.all in batches
+  // is safe — caller aggregates after each batch resolves.
+  const checkOne = async ([rel, expected]) => {
     const abs = path.join(kitRoot, rel);
     let buf;
     try {
       buf = await fs.readFile(abs);
     } catch {
-      missing.push(rel);
-      continue;
+      return { rel, status: 'missing' };
     }
     // Normalize CRLF→LF before hashing so manifest is platform-stable.
     // git checkout converts EOL on Windows but Linux CI checks out LF —
-    // hashing raw bytes would diverge across platforms.
+    // hashing raw bytes would diverge across platforms. (PRESERVED from v1.15)
     const normalized = Buffer.from(buf.toString('binary').replace(/\r\n/g, '\n'), 'binary');
     const actual = crypto.createHash('sha256').update(normalized).digest('hex');
     if (actual !== expected) {
-      mismatches.push({ path: rel, expected: expected.slice(0, 16), actual: actual.slice(0, 16) });
+      return { rel, status: 'mismatch', expected, actual };
+    }
+    return { rel, status: 'ok' };
+  };
+
+  // Sequential batches — within a batch, Promise.all parallelizes hashing;
+  // between batches, await bounds max-in-flight at BATCH_SIZE (defensive
+  // against fd ulimit on large kits). Order of completion within a batch
+  // doesn't matter — aggregator below is order-independent.
+  for (let i = 0; i < entries.length; i += BATCH_SIZE) {
+    const slice = entries.slice(i, i + BATCH_SIZE);
+    const results = await Promise.all(slice.map(checkOne));
+    for (const r of results) {
+      if (r.status === 'mismatch') {
+        mismatches.push({ path: r.rel, expected: r.expected.slice(0, 16), actual: r.actual.slice(0, 16) });
+      } else if (r.status === 'missing') {
+        missing.push(r.rel);
+      }
     }
   }
 
   if (mismatches.length === 0 && missing.length === 0) {
-    return { ok: true };
+    const result = { ok: true };
+    // PERF-17-01: cache only ok=true. Mismatch/missing always recompute
+    // so dev fixing a tampered file sees the next sync recover immediately.
+    if (process.env[NO_CACHE_ENV] !== '1') {
+      verifyManifestCache.set(kitRoot, { value: result, ts: Date.now() });
+    }
+    return result;
   }
 
   // Build a concise reason — first 3 mismatches, plus counts.

package/src/core/path-safety.js

@@ -32,6 +32,36 @@ import fs from 'node:fs/promises';
 // six regexes; one suffices.
 const SENTINEL = 'MCP sync requires projectRoot to be a git workspace';
 
+/**
+ * SEC-14-03: validate that a `projectRoot` supplied via MCP message points to
+ * a real git workspace before any handler dispatches into sync.js / reverse-sync.js.
+ *
+ * Pure function — never throws. Returns a discriminated union so MCP handlers
+ * can wrap rejections in `{ error }` envelopes without try/catch boilerplate
+ * (matches handleSync/handleGates/handleForensics in src/mcp-server/index.js).
+ *
+ * Validation chain (each step short-circuits on rejection):
+ *   1. `projectRoot` is non-empty string (rejects nullish, empty, non-string types).
+ *   2. `path.resolve()` collapses `..` segments and produces an absolute path.
+ *   3. The resolved path exists and is a directory (UNC failures bubble up here).
+ *   4. A `.git` entry exists somewhere in the ancestor chain (file or directory —
+ *      `git worktree` uses a file). Walk-up bounded by `path.dirname()` fixed point.
+ *
+ * The CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same
+ * trust model as Phase 79.01's gates.run guard). Only MCP-message-sourced paths
+ * need this check.
+ *
+ * Rejection reasons all embed the literal `"git workspace"` string — public
+ * contract relied on by test/unit/mcp-projectroot-guard.test.js and downstream
+ * MCP clients. Don't rephrase without coordinating callers.
+ *
+ * @param {unknown} projectRoot - the candidate path supplied by an MCP client.
+ *   Expected to be an absolute filesystem path; any other shape is rejected.
+ * @returns {Promise<{ok: true, resolvedPath: string} | {ok: false, reason: string}>}
+ *   On success, `resolvedPath` is the path-resolved absolute form of `projectRoot`
+ *   (callers should use it instead of the raw input). On failure, `reason` is a
+ *   human-readable string suitable for MCP `{error}` envelopes.
+ */
 export async function validateProjectRoot(projectRoot) {
   // Reject empty / nullish up-front. We require an explicit projectRoot from
   // MCP messages — falling back to `process.cwd()` of the MCP server would let

package/src/core/reverse-sync.js

@@ -31,17 +31,34 @@ export async function detectReverse(targetId, opts = {}) {
 
   const candidates = [];
 
-  // For each capability that this target supports AND that has files on disk,
-  // walk and classify.
-  if (target.agents)   await scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot);
-  if (target.commands) await scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot);
-  if (target.skills)   await scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot);
+  // PERF-16-03: parallelize the 5 scans. Each scan reads a distinct subdirectory
+  // of the IDE layout (.claude/agents, .claude/commands, .claude/skills,
+  // .claude/framework, .claude/hooks) — there is no I/O contention between them.
+  //
+  // Each scan continues to push into the shared `candidates` array. This is safe
+  // under the single-threaded JS event loop: `Array.prototype.push` is a
+  // synchronous operation that completes between awaits, so concurrent scans
+  // never produce a torn write. The trade-off is that candidate ordering is no
+  // longer deterministic across categories — existing reverse-sync tests use
+  // `.find` / `.some` / `.filter` and never index `candidates[N]`, so this is a
+  // safe widening of the contract.
+  //
+  // Error semantics: `Promise.all` rejects on the first rejection — identical to
+  // the previous sequential `await` chain (which also propagated the first error
+  // and aborted the rest). Fail-fast is preserved.
+  const pending = [];
+
+  if (target.agents)   pending.push(scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot));
+  if (target.commands) pending.push(scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot));
+  if (target.skills)   pending.push(scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot));
   for (const cap of ['framework', 'hooks']) {
     const spec = target[cap];
     if (!spec || spec.mode !== 'mirror-tree') continue;
-    await scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot);
+    pending.push(scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot));
   }
 
+  await Promise.all(pending);
+
   return { target: targetId, projectRoot, kitRoot, candidates };
 }
 

package/src/core/sync.js

@@ -19,6 +19,52 @@ const STUB_MARKER = '<!-- kit-mcp:reference -->';
 const MANAGED_MARKER_FILE = '.kit-mcp-managed';
 const MANAGED_MARKER_BODY = '# Managed by @luanpdd/kit-mcp — this directory is overwritten on every `kit sync install`.\n# Do not edit files here directly; edit the canonical source under kit/ and re-run sync.\n# Removing this file disables `kit sync remove` cleanup of this tree.\n';
 
+// PERF-16-01: parallelize file writes in syncTo() via Promise.all batches.
+// BATCH_SIZE=16 default — safe under Linux ulimit 1024 fd default and
+// macOS/Windows equivalents. Configurable via env (e.g. on slow disks).
+// Values outside [1, 256] fall back to 16 (defensive — env vars are strings).
+function resolveBatchSize() {
+  const raw = process.env.KIT_MCP_SYNC_BATCH_SIZE;
+  if (!raw) return 16;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1 || n > 256) return 16;
+  return n;
+}
+
+// PERF-17-02: opt-out of stat-based diff skip. Forces full sync (every op writes)
+// for cleanup/recovery scenarios where target files may be subtly out of sync
+// (manual edits, partial fs corruption) but pass the mtime+size diff heuristic.
+function resolveForceFullSync() {
+  return process.env.KIT_MCP_FORCE_FULL_SYNC === '1';
+}
+
+/**
+ * Project the canonical kit/ into an IDE-specific layout (claude-code, cursor, etc.).
+ *
+ * Workflow:
+ *   1. SEC-14-05: verifyManifest(kitRoot) — refuses tampered kits (Phase 83+90).
+ *   2. Build ops[] (rules + agents + commands + skills + framework/hooks treeCopy).
+ *   3. PERF-17-02: stat-based diff filter — skip treeCopy ops whose target already
+ *      matches source (mtime+size). Bypassed via KIT_MCP_FORCE_FULL_SYNC=1.
+ *   4. PERF-16-01: Promise.all batches=16 over writeOps (Phase 88.01).
+ *
+ * onProgress callback receives one event per op (written or skipped); skipped ops
+ * carry `skipped: true` for UI granularity.
+ *
+ * Stable API v1.0+ preserved: return shape unchanged. `written[]` lists all op
+ * paths (projected files), not just actually-written — semantics: "what's in the
+ * target tree after this call", not "what fs.writeFile ran".
+ *
+ * @param {string} targetId - registry target id (e.g. 'claude-code', 'cursor').
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot=process.cwd()] - destination project root.
+ * @param {string} [opts.kitRoot] - canonical kit/ root (auto-resolved if absent).
+ * @param {'reference'|'copy'|'symlink'} [opts.mode='reference'] - projection mode.
+ * @param {boolean} [opts.dryRun=false] - skip all fs writes; ops still listed.
+ * @param {Function} [opts.onProgress] - per-op callback ({phase, current, total, label, skipped?}).
+ * @param {object} [opts.kit] - pre-loaded kit (skips listKit re-walk).
+ * @returns {Promise<{target, mode, projectRoot, kitRoot, written, dryRun}>}
+ */
 export async function syncTo(targetId, opts = {}) {
   const target      = getTarget(targetId);
   const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
@@ -100,16 +146,83 @@ export async function syncTo(targetId, opts = {}) {
   }
 
   if (!dryRun) {
-    let i = 0;
-    for (const op of ops) {
+    const BATCH_SIZE = resolveBatchSize();
+    let completed = 0;
+    const total = ops.length;
+
+    // PERF-17-02: stat-based diff filter — skip ops whose target already matches source.
+    // Only applies to treeCopy ops (framework/hooks subtrees) — content ops (agents,
+    // commands, skills, rules) include `Generated by kit-mcp at ${ISO timestamp}` so
+    // they re-render every time and can't safely diff. treeCopy ops dominate wall
+    // time on large kits (327+ files), so this captures the PERF-17-02 win.
+    //
+    // Filter logic per op:
+    //   - forceFullSync env set     → never skip
+    //   - !treeCopy (content op)    → never skip
+    //   - target stat fails (absent)→ never skip (must write)
+    //   - src stat fails (defensive)→ never skip (let copy fail naturally)
+    //   - target.size === src.size AND target.mtimeMs >= src.mtimeMs → SKIP
+    //
+    // Implementation: Promise.all over ops produces { op, skip } pairs. Skipped ops
+    // emit onProgress({ skipped: true }) and increment the same `completed` counter
+    // as written ops (so progress UI shows full ops.length total).
+    const forceFullSync = resolveForceFullSync();
+
+    const diffOne = async (op) => {
+      if (forceFullSync) return { op, skip: false };
+      if (!op.treeCopy) return { op, skip: false };
+      let targetStat;
+      try { targetStat = await fs.stat(op.path); }
+      catch { return { op, skip: false }; }
+      let srcStat;
+      try { srcStat = await fs.stat(op.srcAbs); }
+      catch { return { op, skip: false }; }
+      if (targetStat.size === srcStat.size && targetStat.mtimeMs >= srcStat.mtimeMs) {
+        return { op, skip: true };
+      }
+      return { op, skip: false };
+    };
+
+    // Stats are cheap — no batch limit needed (Promise.all over all ops is fine).
+    const diffResults = await Promise.all(ops.map(diffOne));
+    const writeOps = [];
+    for (const { op, skip } of diffResults) {
+      if (skip) {
+        completed += 1;
+        onProgress({ phase: op.kind, current: completed, total, label: path.basename(op.path), skipped: true });
+      } else {
+        writeOps.push(op);
+      }
+    }
+
+    // Apply one op (mkdir + write or copy + onProgress).
+    // Each op is independent: ops[] is built so writes don't share parent
+    // directories that need ordering — mkdir({recursive:true}) is idempotent
+    // even when 16 ops race for the same parent dir.
+    const applyOp = async (op) => {
       await fs.mkdir(path.dirname(op.path), { recursive: true });
       if (op.treeCopy) {
         await fs.copyFile(op.srcAbs, op.path);
       } else {
         await fs.writeFile(op.path, op.content, 'utf8');
       }
-      i++;
-      onProgress({ phase: op.kind, current: i, total: ops.length, label: path.basename(op.path) });
+      // Counter increment is single-threaded by JS event loop semantics —
+      // no torn reads even with 16 ops resolving in any order.
+      // (PERF-17-02: diff filter increments the same counter for skipped ops before
+      // this batch loop runs, so `current` in onProgress reflects total progress.)
+      completed += 1;
+      onProgress({ phase: op.kind, current: completed, total, label: path.basename(op.path) });
+    };
+
+    // PERF-16-01 batched writes — now operating on writeOps (post-diff filter).
+    // Sequential batches — within a batch, Promise.all parallelizes writes;
+    // between batches, we await to bound max-in-flight at BATCH_SIZE. If any
+    // op in a batch rejects, Promise.all rejects on first failure (matches
+    // existing behavior — sync.js had no retry logic, so a single fs error
+    // already aborted the install).
+    for (let i = 0; i < writeOps.length; i += BATCH_SIZE) {
+      const slice = writeOps.slice(i, i + BATCH_SIZE);
+      await Promise.all(slice.map(applyOp));
     }
   }
 

package/src/core/ui.js

@@ -10,7 +10,23 @@
 //   - Zero hidden globals — every primitive is a plain function/class.
 
 import pc from 'picocolors';
-import { select as inqSelect, confirm as inqConfirm } from '@inquirer/prompts';
+
+// PERF-16-05: @inquirer/prompts é optionalDependency. Carregamos lazy dentro
+// de select()/confirm() para que (a) modo MCP server e CI não paguem o custo
+// de boot, e (b) `npm install --omit=optional` produza CLI core funcional
+// (apenas comandos interativos falham com mensagem descritiva).
+let _inquirerModule = null;
+async function loadInquirer() {
+  if (_inquirerModule) return _inquirerModule;
+  try {
+    _inquirerModule = await import('@inquirer/prompts');
+    return _inquirerModule;
+  } catch (err) {
+    throw new Error(
+      'Interactive prompts require @inquirer/prompts. Install with `npm i @inquirer/prompts` or pass --yes / --no-interactive to skip the prompt.'
+    );
+  }
+}
 
 // --- color helpers ---
 
@@ -127,6 +143,7 @@ export async function select(opts) {
   if (!process.stdin.isTTY) {
     throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass the value as a flag instead.');
   }
+  const { select: inqSelect } = await loadInquirer();
   return inqSelect(opts);
 }
 
@@ -134,6 +151,7 @@ export async function confirm(opts) {
   if (!process.stdin.isTTY) {
     throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass --yes to skip confirmation.');
   }
+  const { confirm: inqConfirm } = await loadInquirer();
   return inqConfirm(opts);
 }
 

package/src/core/watch.js

@@ -11,16 +11,35 @@
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import chokidar from 'chokidar';
 import { syncTo } from './sync.js';
 import { listTargets } from './registry.js';
-import { resolveKitRoot } from './kit.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';
-  const debounceMs  = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 300;
+  // 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) {
@@ -33,6 +52,7 @@ export async function watchKit(targets, opts = {}) {
     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,
@@ -46,6 +66,12 @@ export async function watchKit(targets, opts = {}) {
     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 });