@luanpdd/kit-mcp 1.16.0 → 1.17.0

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.16.0",
-  "timestamp": "2026-05-09T14:17:38.936Z",
+  "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.16.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": {
@@ -49,11 +49,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "commander": "^14.0.3",
-    "open": "^11.0.0",
     "picocolors": "^1.1.1"
   },
   "optionalDependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "chokidar": "^5.0.0"
+    "chokidar": "^5.0.0",
+    "open": "^11.0.0"
   }
 }

package/src/cli/index.js

@@ -30,7 +30,7 @@ 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 { readLock, lockPathFor } from '../ui/lockfile.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)

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/sync.js

@@ -31,6 +31,40 @@ function resolveBatchSize() {
   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());
@@ -116,6 +150,51 @@ export async function syncTo(targetId, opts = {}) {
     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
@@ -129,17 +208,20 @@ export async function syncTo(targetId, opts = {}) {
       }
       // 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 < ops.length; i += BATCH_SIZE) {
-      const slice = ops.slice(i, i + BATCH_SIZE);
+    for (let i = 0; i < writeOps.length; i += BATCH_SIZE) {
+      const slice = writeOps.slice(i, i + BATCH_SIZE);
       await Promise.all(slice.map(applyOp));
     }
   }