@luanpdd/kit-mcp 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.14.0",
+  "version": "1.16.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": {
@@ -44,14 +44,16 @@
     "test": "node test/run.mjs test/unit",
     "test:integration": "node test/run.mjs test/integration",
     "test:all": "node test/run.mjs test",
-    "prepublishOnly": "node test/run.mjs test/unit && node test/run.mjs test/integration"
+    "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"
   }
 }

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';
+// 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 });
 }
 
@@ -154,20 +165,36 @@ function slim(x) {
   return { kind: x.kind, name: x.name, description: summarize(x.description) };
 }
 
+// PERF-15-01: terse variant — paridade com mcp-server slimTerse. CLI flag --terse
+// controla seleção. Mantém o mesmo shape {kind, name} para programmatic consumers
+// que parseiam --json output (consistência cross-surface).
+function slimTerse(x) {
+  return { kind: x.kind, name: x.name };
+}
+
 // --- kit ---
 const kit = program.command('kit').description('Browse the canonical kit.');
-kit.command('list-agents').action(async () => {
-  const k = await withSpinner('Loading kit...', () => listKit());
-  out(k.agents.map(slim), v => render.renderKitList(v, 'agent'));
-});
-kit.command('list-commands').action(async () => {
-  const k = await withSpinner('Loading kit...', () => listKit());
-  out(k.commands.map(slim), v => render.renderKitList(v, 'command'));
-});
-kit.command('list-skills').action(async () => {
-  const k = await withSpinner('Loading kit...', () => listKit());
-  out([...k.skills, ...k.skillsExtras].map(slim), v => render.renderKitList(v, 'skill'));
-});
+kit.command('list-agents')
+  .option('--terse', 'Omit description; return only {kind, name} (PERF-15-01)')
+  .action(async (opts) => {
+    const k = await withSpinner('Loading kit...', () => listKit());
+    const variant = opts.terse ? slimTerse : slim;
+    out(k.agents.map(variant), v => render.renderKitList(v, 'agent'));
+  });
+kit.command('list-commands')
+  .option('--terse', 'Omit description; return only {kind, name} (PERF-15-01)')
+  .action(async (opts) => {
+    const k = await withSpinner('Loading kit...', () => listKit());
+    const variant = opts.terse ? slimTerse : slim;
+    out(k.commands.map(variant), v => render.renderKitList(v, 'command'));
+  });
+kit.command('list-skills')
+  .option('--terse', 'Omit description; return only {kind, name} (PERF-15-01)')
+  .action(async (opts) => {
+    const k = await withSpinner('Loading kit...', () => listKit());
+    const variant = opts.terse ? slimTerse : slim;
+    out([...k.skills, ...k.skillsExtras].map(variant), v => render.renderKitList(v, 'skill'));
+  });
 kit.command('get <kind> <name>').action(async (kind, name) => {
   const k = await listKit();
   const item = findItem(k, kind, name);
@@ -391,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 });
@@ -406,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.
@@ -464,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

@@ -59,7 +59,11 @@ export async function verifyManifest(kitRoot) {
       missing.push(rel);
       continue;
     }
-    const actual = crypto.createHash('sha256').update(buf).digest('hex');
+    // 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.
+    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) });
     }

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,18 @@ 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;
+}
+
 export async function syncTo(targetId, opts = {}) {
   const target      = getTarget(targetId);
   const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
@@ -100,16 +112,35 @@ 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;
+
+    // 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.
+      completed += 1;
+      onProgress({ phase: op.kind, current: completed, total, label: path.basename(op.path) });
+    };
+
+    // 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);
+      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 });

package/src/mcp-server/index.js

@@ -42,6 +42,7 @@ const TOOLS = [
         kind:   { type: 'string', enum: ['agent', 'command', 'skill'], description: 'For action=get' },
         name:   { type: 'string', description: 'For action=get' },
         query:  { type: 'string', description: 'For action=search' },
+        terse:  { type: 'boolean', description: 'For action=list-*: omit description, return only {kind, name}. Default false (PERF-15-01).' },
       },
       required: ['action'],
     },
@@ -152,10 +153,13 @@ export const PKG_VERSION = readPkgVersion();
 
 async function handleKit(args) {
   const kit = await listKit();
+  // PERF-15-01: terse mode skips description payload entirely. Backward-compat:
+  // args.terse undefined/false preserves slim()+summarize() cap-80 behavior.
+  const variant = args.terse === true ? slimTerse : slim;
   switch (args.action) {
-    case 'list-agents':   return kit.agents.map(slim);
-    case 'list-commands': return kit.commands.map(slim);
-    case 'list-skills':   return [...kit.skills, ...kit.skillsExtras].map(slim);
+    case 'list-agents':   return kit.agents.map(variant);
+    case 'list-commands': return kit.commands.map(variant);
+    case 'list-skills':   return [...kit.skills, ...kit.skillsExtras].map(variant);
     case 'get': {
       const item = findItem(kit, args.kind, args.name);
       if (!item) return { error: `Not found: ${args.kind}/${args.name}` };
@@ -305,6 +309,13 @@ function slim(x) {
   return { kind: x.kind, name: x.name, description: summarize(x.description) };
 }
 
+// PERF-15-01: terse variant — omits description entirely. Used when MCP client
+// only needs name discovery (e.g. populating UI lists, validating slug references).
+// Default action=list-* still returns description capped via slim()/summarize().
+function slimTerse(x) {
+  return { kind: x.kind, name: x.name };
+}
+
 // --- server bootstrap ---
 
 export async function createServer() {