@luanpdd/kit-mcp 1.5.4 → 1.6.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-05-05
+
+DX patch: comando `kit doctor` + upgrade-check no boot do sidecar + cache de gates.
+
+### Adicionado
+
+- **`kit doctor`** ([src/cli/index.js](src/cli/index.js), nova função `runDoctorChecks`) — comando único de diagnóstico que checa: versão local vs npm latest, sidecar reachability via lockfile + healthz, validade do `~/.claude/settings.json`, presença do hook PostToolUse `sidecar-tool-publisher`, dirs do kit bundled, integridade do `.planning/`, e lockfiles órfãos em tmpdir. Retorna checklist colorido com `fix:` específico em cada falha. Suporta `--json` (via flag global) pra consumo programático.
+- **Upgrade-check no `kit ui start`** ([src/cli/index.js](src/cli/index.js), [src/cli/upgrade-check.js](src/cli/upgrade-check.js)) — verifica npm registry em background; se versão local atrás da latest, imprime banner amarelo "v1.6 → v1.6.1 disponível, atualize com npm i -g". Cache TTL 24h em `~/.kit-mcp/version-check.json` evita hit no registry em todo boot. Falha gracefully em modo offline.
+- **Cache TTL em `listGates`** ([src/core/gates.js](src/core/gates.js)) — mesmo padrão de PERF-01 (`listKit`). Sequência `listGates → getGate → gatesForStage` num único processo agora faz 1 walk de disco em vez de 3.
+
+### Sem mudanças de API
+
+`mcp__kit__gates` action=list e action=get continuam funcionando com mesma assinatura. Doctor e upgrade-check são CLI-only.
+
+### Testes
+
++10 unit (112 total): 8 cobrindo `compareVersions`/`getLocalVersion`/constantes do upgrade-check, 2 cobrindo cache hit/miss em gates.
+
 ## [1.6.0] - 2026-05-05
 
 Milestone v1.6 — perf+lean: 16 itens de auditoria de codebase entregues em 3 fases (Phase 19 quick wins, Phase 20 hardening, Phase 21 token economy) + observability hook (Phase 19.5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "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": {

package/src/cli/index.js

@@ -33,7 +33,10 @@ 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 http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
 
 // Read package.json version at boot so `--version` is always accurate. Falls
 // back to a string if the file lookup fails (e.g. unusual install layout).
@@ -391,6 +394,14 @@ ui.command('start')
       const url = `http://127.0.0.1:${actualPort}/`;
       process.stderr.write(`${c.cyan(icons.info)} kit-mcp ui listening on ${url}\n`);
       process.stderr.write(`${c.dim(`  project: ${projectRoot}`)}\n`);
+      // U4: non-blocking upgrade check. Warns if local install is behind npm latest.
+      // Cached for 24h via ~/.kit-mcp/version-check.json so we don't hit npm on every start.
+      checkUpgrade().then((info) => {
+        if (info?.behind) {
+          process.stderr.write(`${c.yellow(icons.warn)} kit-mcp v${info.local} → v${info.latest} disponível\n`);
+          process.stderr.write(`${c.dim('   atualize com: npm i -g @luanpdd/kit-mcp@latest')}\n`);
+        }
+      }).catch(() => { /* offline / silent */ });
       if (opts.open !== false) {
         await openBrowser(url);
       }
@@ -457,6 +468,174 @@ ui.command('open')
     }
   });
 
+// --- doctor (DX diagnostic) ---
+program.command('doctor')
+  .description('Diagnose kit-mcp setup: version, sidecar, hook, settings.json, lockfile, .planning/.')
+  .option('--project-root <path>', 'Project to diagnose (default: cwd)')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const checks = await runDoctorChecks(projectRoot);
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+
+    if (program.opts().json) {
+      out({ checks, failed, warned }, () => '');
+      process.exit(failed > 0 ? 1 : 0);
+    }
+
+    process.stdout.write(`\n${c.bold('kit-mcp doctor')} — ${projectRoot}\n\n`);
+    for (const check of checks) {
+      const sym = check.status === 'pass' ? c.green(icons.check)
+                : check.status === 'warn' ? c.yellow(icons.warn)
+                : c.red(icons.cross);
+      process.stdout.write(`${sym}  ${c.bold(check.label)}\n`);
+      if (check.detail)  process.stdout.write(`   ${c.dim(check.detail)}\n`);
+      if (check.fix)     process.stdout.write(`   ${c.cyan('fix:')} ${check.fix}\n`);
+    }
+    process.stdout.write('\n');
+    if (failed > 0) {
+      process.stdout.write(`${c.red(icons.cross)} ${failed} check(s) failed\n`);
+      process.exit(1);
+    } else if (warned > 0) {
+      process.stdout.write(`${c.yellow(icons.warn)} ${warned} warning(s) — kit-mcp is functional\n`);
+    } else {
+      process.stdout.write(`${c.green(icons.check)} all checks passed\n`);
+    }
+  });
+
+async function runDoctorChecks(projectRoot) {
+  const checks = [];
+
+  // 1. Version + upgrade availability
+  const upgrade = await checkUpgrade();
+  if (!upgrade) {
+    checks.push({ label: 'version', status: 'fail',
+      detail: 'could not read local package.json',
+      fix: 'reinstall via `npm i -g @luanpdd/kit-mcp@latest`' });
+  } else if (upgrade.latest === null) {
+    checks.push({ label: 'version', status: 'warn',
+      detail: `local v${upgrade.local} (offline — could not check npm)` });
+  } else if (upgrade.behind) {
+    checks.push({ label: 'version', status: 'warn',
+      detail: `local v${upgrade.local}, latest v${upgrade.latest}`,
+      fix: 'npm i -g @luanpdd/kit-mcp@latest' });
+  } else {
+    checks.push({ label: 'version', status: 'pass',
+      detail: `v${upgrade.local} (latest)` });
+  }
+
+  // 2. Sidecar lockfile + healthz
+  const lock = readLock(projectRoot);
+  if (!lock) {
+    checks.push({ label: 'sidecar', status: 'warn',
+      detail: 'not running for this project',
+      fix: 'kit ui start (or omit if you don\'t need the live viewer)' });
+  } else {
+    try {
+      await getHealthz(lock.port);
+      checks.push({ label: 'sidecar', status: 'pass',
+        detail: `running on port ${lock.port} (pid ${lock.pid})` });
+    } catch (err) {
+      checks.push({ label: 'sidecar', status: 'fail',
+        detail: `lockfile says port ${lock.port} but unreachable: ${err.message}`,
+        fix: 'kit ui stop && kit ui start' });
+    }
+  }
+
+  // 3. ~/.claude/settings.json — exists + valid JSON + hooks present?
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  let settings = null;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    checks.push({ label: 'settings.json', status: 'pass',
+      detail: settingsPath });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      checks.push({ label: 'settings.json', status: 'warn',
+        detail: 'not found (expected for fresh Claude Code)',
+        fix: 'will be created automatically by Claude Code' });
+    } else {
+      checks.push({ label: 'settings.json', status: 'fail',
+        detail: `invalid JSON at ${settingsPath}: ${err.message}`,
+        fix: 'edit the file or restore from .claude/settings.json.bak' });
+    }
+  }
+
+  // 4. Hook installed?
+  if (settings) {
+    const hooks = settings.hooks?.PostToolUse;
+    const hasHook = Array.isArray(hooks) && hooks.some((h) =>
+      Array.isArray(h.hooks) && h.hooks.some((cmd) =>
+        typeof cmd.command === 'string' && cmd.command.includes('sidecar-tool-publisher')));
+    if (hasHook) {
+      checks.push({ label: 'observability hook', status: 'pass',
+        detail: 'sidecar-tool-publisher registered as PostToolUse' });
+    } else {
+      checks.push({ label: 'observability hook', status: 'warn',
+        detail: 'sidecar-tool-publisher not registered',
+        fix: 'see kit/hooks/sidecar-tool-publisher.js for installation snippet' });
+    }
+  }
+
+  // 5. Bundled kit dirs exist
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const kitRoot = path.resolve(here, '..', '..', 'kit');
+  const expected = ['agents', 'commands', 'skills'];
+  const missing = expected.filter((d) => {
+    try { return !fs.statSync(path.join(kitRoot, d)).isDirectory(); }
+    catch { return true; }
+  });
+  if (missing.length === 0) {
+    checks.push({ label: 'bundled kit', status: 'pass',
+      detail: `agents/, commands/, skills/ found in ${kitRoot}` });
+  } else {
+    checks.push({ label: 'bundled kit', status: 'fail',
+      detail: `missing: ${missing.join(', ')} in ${kitRoot}`,
+      fix: 'reinstall via `npm i -g @luanpdd/kit-mcp@latest`' });
+  }
+
+  // 6. .planning/ in projectRoot — only warn if absent (not all projects use the framework)
+  const planningDir = path.join(projectRoot, '.planning');
+  if (fs.existsSync(planningDir)) {
+    const stateOk = fs.existsSync(path.join(planningDir, 'STATE.md'));
+    const roadmapOk = fs.existsSync(path.join(planningDir, 'ROADMAP.md'));
+    if (stateOk && roadmapOk) {
+      checks.push({ label: '.planning/', status: 'pass',
+        detail: 'STATE.md + ROADMAP.md present' });
+    } else {
+      checks.push({ label: '.planning/', status: 'warn',
+        detail: `present but missing ${[!stateOk && 'STATE.md', !roadmapOk && 'ROADMAP.md'].filter(Boolean).join(', ')}`,
+        fix: 'run `kit saude` to repair, or `/novo-marco` if mid-cycle' });
+    }
+  } else {
+    checks.push({ label: '.planning/', status: 'warn',
+      detail: 'no framework state in this project',
+      fix: 'run `/novo-projeto` to bootstrap, or skip if not using the framework' });
+  }
+
+  // 7. Stale lockfile cleanup hint
+  try {
+    const tmpdir = os.tmpdir();
+    const orphans = fs.readdirSync(tmpdir).filter(n => /^kit-mcp-ui-[0-9a-f]{16}\.lock$/.test(n));
+    const stale = [];
+    for (const name of orphans) {
+      try {
+        const lock = JSON.parse(fs.readFileSync(path.join(tmpdir, name), 'utf8'));
+        try { process.kill(lock.pid, 0); } catch (err) {
+          if (err.code === 'ESRCH') stale.push(name);
+        }
+      } catch { /* skip unreadable */ }
+    }
+    if (stale.length > 0) {
+      checks.push({ label: 'orphan lockfiles', status: 'warn',
+        detail: `${stale.length} stale lockfile(s) in ${tmpdir}`,
+        fix: stale.map(n => `rm "${path.join(tmpdir, n)}"`).join(' && ') });
+    }
+  } catch { /* tmpdir scan is best-effort */ }
+
+  return checks;
+}
+
 // Helpers for kit ui (live in cli/ — stdout/console allowed here)
 async function postShutdown(port) {
   return new Promise((resolve, reject) => {

package/src/cli/upgrade-check.js

@@ -0,0 +1,135 @@
+// upgrade-check.js — non-blocking check for newer kit-mcp on npm.
+//
+// Both `kit doctor` (U1) and `kit ui start` (U4) call this. Result is cached
+// to ~/.kit-mcp/version-check.json for 24h so we don't hit the npm registry on
+// every boot. Falls back gracefully when offline or when the request fails.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PACKAGE_NAME = '@luanpdd/kit-mcp';
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const REQUEST_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  return path.join(os.homedir(), '.kit-mcp', 'version-check.json');
+}
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(cacheFile(), 'utf8');
+    const obj = JSON.parse(raw);
+    if (typeof obj.checkedAt !== 'number' || typeof obj.latest !== 'string') return null;
+    if (Date.now() - obj.checkedAt > CHECK_TTL_MS) return null;
+    return obj;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(obj) {
+  try {
+    await fs.mkdir(path.dirname(cacheFile()), { recursive: true });
+    await fs.writeFile(cacheFile(), JSON.stringify(obj), 'utf8');
+  } catch {
+    /* cache failures are silent — not critical */
+  }
+}
+
+function fetchLatest() {
+  // Use the registry's package endpoint. Falls back to gracefully on any error.
+  return new Promise((resolve) => {
+    const req = https.request({
+      method: 'GET',
+      hostname: 'registry.npmjs.org',
+      path: `/${encodeURIComponent(PACKAGE_NAME)}/latest`,
+      headers: { 'accept': 'application/json' },
+      timeout: REQUEST_TIMEOUT_MS,
+    }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); resolve(null); return; }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          resolve(typeof j.version === 'string' ? j.version : null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { try { req.destroy(); } catch { /* noop */ } resolve(null); });
+    req.end();
+  });
+}
+
+export async function getLocalVersion() {
+  // Read package.json from the kit-mcp install root (parent of src/).
+  try {
+    const pkgPath = path.resolve(__dirname, '../../package.json');
+    const raw = await fs.readFile(pkgPath, 'utf8');
+    const j = JSON.parse(raw);
+    return typeof j.version === 'string' ? j.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// Compare semver-like x.y.z lexically by component. Returns -1/0/1.
+// Missing components default to 0 ("1.5" === "1.5.0").
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const parts = v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return parts;
+  };
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 < b1 ? -1 : 1;
+  if (a2 !== b2) return a2 < b2 ? -1 : 1;
+  if (a3 !== b3) return a3 < b3 ? -1 : 1;
+  return 0;
+}
+
+// checkUpgrade({ force }): returns { local, latest, behind, source } or null on failure.
+//   force=true bypasses the 24h cache.
+export async function checkUpgrade({ force = false } = {}) {
+  const local = await getLocalVersion();
+  if (!local) return null;
+
+  if (!force) {
+    const cached = await readCache();
+    if (cached?.latest) {
+      return {
+        local,
+        latest: cached.latest,
+        behind: compareVersions(local, cached.latest) < 0,
+        source: 'cache',
+      };
+    }
+  }
+
+  const latest = await fetchLatest();
+  if (!latest) {
+    // Network failed; surface what we have.
+    return { local, latest: null, behind: false, source: 'offline' };
+  }
+
+  await writeCache({ checkedAt: Date.now(), latest });
+  return {
+    local,
+    latest,
+    behind: compareVersions(local, latest) < 0,
+    source: 'network',
+  };
+}
+
+export const __test = { compareVersions, PACKAGE_NAME, CHECK_TTL_MS };

package/src/core/gates.js

@@ -22,7 +22,19 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
 export const DEFAULT_GATES_ROOT = path.resolve(__dirname, '../../gates');
 
+// P2: TTL cache for listGates (mirrors PERF-01 in kit.js). Gates change rarely;
+// inside a single Claude Code session we may call listGates → getGate → gatesForStage
+// in sequence — without cache, that's 3 full directory walks of the gates dir.
+const GATES_CACHE_TTL_MS = 30_000;
+const gatesCache = new Map(); // gatesRoot -> { value, ts }
+
+export function clearGatesCache() { gatesCache.clear(); }
+
 export async function listGates(gatesRoot = DEFAULT_GATES_ROOT) {
+  const cached = gatesCache.get(gatesRoot);
+  if (cached && Date.now() - cached.ts < GATES_CACHE_TTL_MS) {
+    return cached.value;
+  }
   let entries;
   try { entries = await fs.readdir(gatesRoot, { withFileTypes: true }); }
   catch { return []; }
@@ -40,7 +52,9 @@ export async function listGates(gatesRoot = DEFAULT_GATES_ROOT) {
       absPath: abs,
     });
   }
-  return out.sort((a, b) => a.id.localeCompare(b.id));
+  const value = out.sort((a, b) => a.id.localeCompare(b.id));
+  gatesCache.set(gatesRoot, { value, ts: Date.now() });
+  return value;
 }
 
 export async function getGate(id, gatesRoot = DEFAULT_GATES_ROOT) {