@luanpdd/kit-mcp 1.0.0 → 1.2.0

package/src/cli/index.js

@@ -7,8 +7,15 @@
 //   kit gates list
 //   kit forensics collect --project-root /path/to/project
 //   kit install dry-run claude-code
+//
+// Default output: human-readable colored panels + summaries.
+// `--json` flag (global) restores the v1.0 JSON-to-stdout behavior for
+// programmatic consumers.
 
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import { listKit, searchKit, findItem } from '../core/kit.js';
 import { listTargets } from '../core/registry.js';
 import { syncTo, statusOf, removeFrom } from '../core/sync.js';
@@ -20,49 +27,176 @@ import { collectFailures, summarizeByAgent, writeLearnings } from '../core/failu
 import { reflect } from '../core/reflect.js';
 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 http from 'node:http';
+
+// 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).
+function readPkgVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.resolve(here, '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
 
 const program = new Command()
   .name('kit')
   .description('Personal kit (agents/commands/skills) — CLI mirror of the kit-mcp server.')
-  .version('0.2.0')
-  .option('--kit-root <path>', 'Override the kit root (default: bundled example kit, or KIT_MCP_KIT_ROOT env)');
+  .version(readPkgVersion())
+  .option('--kit-root <path>', 'Override the kit root (default: bundled example kit, or KIT_MCP_KIT_ROOT env)')
+  .option('--json', 'Output JSON to stdout (machine-readable, restores pre-1.1 default)')
+  .option('--no-ui', 'Suppress sidecar event publishing for this run (default: auto-detect lockfile)');
 
-// Apply --kit-root globally by setting the env so all helpers pick it up.
 program.hook('preAction', (thisCommand, actionCommand) => {
   const opts = program.opts();
   if (opts.kitRoot) process.env.KIT_MCP_KIT_ROOT = opts.kitRoot;
 });
 
+// `out(value, humanRenderer)` — uses the human renderer unless --json is set.
+function out(value, humanRenderer) {
+  const opts = program.opts();
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+  } else if (typeof humanRenderer === 'function') {
+    process.stdout.write(humanRenderer(value));
+  } else {
+    process.stdout.write(render.renderFallback(value));
+  }
+}
+
+// withSpinner wraps a short opaque op with a spinner; auto-disabled in --json mode.
+async function withSpinner(text, fn) {
+  const opts = program.opts();
+  if (opts.json) return fn();
+  const sp = spinner({ text });
+  try {
+    const r = await fn();
+    sp.succeed();
+    return r;
+  } catch (e) {
+    sp.fail(e.message);
+    throw e;
+  }
+}
+
+// withProgress wraps a long op; passes onProgress callback to the core fn.
+// Also auto-detects a running sidecar (via lockfile) and multiplexes events to
+// it when present. Opt-out via --no-ui or KIT_MCP_NO_UI=1.
+async function withProgress(label, total, fn, { tool, projectRoot } = {}) {
+  const opts = program.opts();
+  let onProgress;
+  let p = null;
+  if (opts.json) {
+    onProgress = () => {};
+  } else {
+    p = progress({ total, label });
+    let last = '';
+    onProgress = ({ current, label }) => { last = label || last; p.tick({ label: last }); };
+  }
+
+  // Auto-wrap if a sidecar is running for this projectRoot.
+  const wrapper = maybeWrapForUi(onProgress, { tool, projectRoot });
+  try {
+    const r = await fn(wrapper);
+    if (p) p.finish(label);
+    if (wrapper.done) wrapper.done({ ok: true });
+    return r;
+  } catch (e) {
+    if (p) p.finish();
+    if (wrapper.error) wrapper.error(e);
+    throw e;
+  }
+}
+
+// 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 } = {}) {
+  const globalOpts = program.opts();
+  // commander stores `--no-ui` as opts.ui === false
+  if (globalOpts.ui === false || process.env.KIT_MCP_NO_UI === '1') {
+    return passthroughWrapper(onProgress);
+  }
+  const root = projectRoot || process.cwd();
+  if (!readLock(root)) {
+    return passthroughWrapper(onProgress);
+  }
+  return wrapProgressForUi(onProgress, { projectRoot: root, tool: tool ?? null });
+}
+
+function passthroughWrapper(onProgress) {
+  const cb = (p) => { if (typeof onProgress === 'function') onProgress(p); };
+  cb.done = () => {};
+  cb.error = () => {};
+  cb.emit = () => {};
+  return cb;
+}
+
+function fail(msg) {
+  process.stderr.write(`${c.red(icons.cross)} ${msg}\n`);
+  process.exit(1);
+}
+
+function slim(x) {
+  return { kind: x.kind, name: x.name, description: x.description, absPath: x.absPath };
+}
+
 // --- kit ---
 const kit = program.command('kit').description('Browse the canonical kit.');
-kit.command('list-agents').action(async () => print((await listKit()).agents.map(slim)));
-kit.command('list-commands').action(async () => print((await listKit()).commands.map(slim)));
+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 listKit();
-  print([...k.skills, ...k.skillsExtras].map(slim));
+  const k = await withSpinner('Loading kit...', () => listKit());
+  out([...k.skills, ...k.skillsExtras].map(slim), v => render.renderKitList(v, 'skill'));
 });
 kit.command('get <kind> <name>').action(async (kind, name) => {
   const k = await listKit();
   const item = findItem(k, kind, name);
   if (!item) return fail(`Not found: ${kind}/${name}`);
+  // Always raw for `kit get` — it's intended to be cat-like
   process.stdout.write(item.content ?? item.skillContent);
 });
-kit.command('search <query>').action(async (q) => print(searchKit(await listKit(), q)));
+kit.command('search <query>').action(async (q) => out(searchKit(await listKit(), q), render.renderKitSearch));
 
 // --- sync ---
 const sync = program.command('sync').description('Project the kit into an IDE.');
-sync.command('targets').action(async () => print(listTargets()));
+sync.command('targets').action(async () => {
+  const targets = await withSpinner('Loading capability matrix...', async () => listTargets());
+  out(targets, render.renderSyncTargets);
+});
 sync.command('status <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await statusOf(target, { projectRoot: opts.projectRoot })));
-sync.command('install <target>')
+  .action(async (target, opts) => out(await statusOf(target, { projectRoot: opts.projectRoot }), render.renderSyncStatus));
+sync.command('install [target]')
   .option('--project-root <path>')
   .option('--mode <mode>', 'reference | copy', 'reference')
   .option('--dry-run')
-  .action(async (target, opts) => print(await syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun })));
+  .action(async (target, opts) => {
+    if (!target) target = await pickTarget(listTargets(), 'Which IDE do you want to sync the kit into?');
+    const result = await withProgress(
+      `Syncing kit → ${target}`,
+      300,
+      (onProgress) => syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun, onProgress }),
+      { tool: 'sync.install', projectRoot: opts.projectRoot },
+    );
+    out(result, render.renderSyncInstall);
+  });
 sync.command('remove <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await removeFrom(target, { projectRoot: opts.projectRoot })));
+  .action(async (target, opts) => out(await removeFrom(target, { projectRoot: opts.projectRoot }), render.renderSyncRemove));
 sync.command('watch [targets...]')
   .description('Watch kit/ and re-sync to one or more IDEs on every change. Use --all to pick up every IDE that already has files in the project.')
   .option('--project-root <path>')
@@ -93,50 +227,58 @@ sync.command('watch [targets...]')
 const reverse = program.command('reverse-sync').description('Detect and apply edits made directly in an IDE back to the canonical kit/.');
 reverse.command('detect <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await detectReverse(target, { projectRoot: opts.projectRoot })));
+  .action(async (target, opts) => out(await detectReverse(target, { projectRoot: opts.projectRoot }), render.renderReverseDetect));
 reverse.command('apply <target>')
   .option('--project-root <path>')
   .option('--strategy <s>', 'skip | overwrite | merge | rename', 'skip')
-  .option('--only <items...>', 'Limit to these kind/name pairs (e.g. agent/planner skill/paperclip)')
+  .option('--only <items...>', 'Limit to these kind/name pairs (e.g. agent/planner skill/paperclip framework/workflows/foo.md)')
   .option('--dry-run')
-  .action(async (target, opts) => print(await applyReverse(target, { projectRoot: opts.projectRoot, strategy: opts.strategy, only: opts.only, dryRun: opts.dryRun })));
+  .action(async (target, opts) => {
+    const result = await withProgress(
+      `Applying reverse-sync (${opts.strategy})`,
+      50,
+      (onProgress) => applyReverse(target, { projectRoot: opts.projectRoot, strategy: opts.strategy, only: opts.only, dryRun: opts.dryRun, onProgress }),
+      { tool: 'reverse-sync.apply', projectRoot: opts.projectRoot },
+    );
+    out(result, render.renderReverseApply);
+  });
 
 // --- gates ---
 const gates = program.command('gates').description('Reusable workflow gates.');
-gates.command('list').action(async () => print(await listGates()));
+gates.command('list').action(async () => out(await listGates(), render.renderGatesList));
 gates.command('get <id>').action(async (id) => process.stdout.write((await getGate(id)).content));
-gates.command('for-stage <stage>').action(async (stage) => print(await gatesForStage(stage)));
+gates.command('for-stage <stage>').action(async (stage) => out(await gatesForStage(stage), render.renderGatesList));
 gates.command('run <id>')
   .description('Execute a gate (with confirmation in interactive mode). Returns a structured verdict.')
   .option('--project-root <path>')
   .option('--yes', 'Skip confirmation (CI/non-interactive)')
   .option('--no-interactive', 'Never prompt; manual gates return verdict=manual')
-  .action(async (id, opts) => print(await runGate(id, {
+  .action(async (id, opts) => out(await runGate(id, {
     projectRoot: opts.projectRoot,
     yes: opts.yes,
     interactive: opts.interactive !== false,
-  })));
+  }), render.renderGateRun));
 
 // --- forensics ---
 const forensics = program.command('forensics').description('Failure dataset & replays.');
 forensics.command('collect')
   .option('--project-root <path>')
-  .action(async (opts) => print(await collectFailures({ projectRoot: opts.projectRoot })));
+  .action(async (opts) => out(await collectFailures({ projectRoot: opts.projectRoot }), render.renderForensicsCollect));
 forensics.command('summarize')
   .option('--project-root <path>')
   .action(async (opts) => {
     const f = await collectFailures({ projectRoot: opts.projectRoot });
-    print(await summarizeByAgent(f));
+    out(await summarizeByAgent(f), render.renderForensicsSummarize);
   });
 forensics.command('write-learnings')
   .option('--project-root <path>')
   .action(async (opts) => {
     const f = await collectFailures({ projectRoot: opts.projectRoot });
-    print(await writeLearnings(f, { projectRoot: opts.projectRoot }));
+    out(await writeLearnings(f, { projectRoot: opts.projectRoot }), render.renderFallback);
   });
 forensics.command('list-replays')
   .option('--project-root <path>')
-  .action(async (opts) => print(await listReplays({ projectRoot: opts.projectRoot })));
+  .action(async (opts) => out(await listReplays({ projectRoot: opts.projectRoot }), render.renderListReplays));
 forensics.command('reflect')
   .description('LLM-pass: read learnings + current agent, propose minimal prompt edits, optionally apply.')
   .requiredOption('--agent <name>', 'Agent name (matches kit/agents/<name>.md)')
@@ -144,39 +286,233 @@ forensics.command('reflect')
   .option('--dry-run', 'Save the assembled prompt without calling the LLM')
   .option('--apply', 'Skip confirmation; apply the proposal directly')
   .option('--no-interactive', 'Save proposal but never prompt to apply')
-  .action(async (opts) => print(await reflect({
+  .action(async (opts) => out(await reflect({
     agent: opts.agent,
     projectRoot: opts.projectRoot,
     dryRun: opts.dryRun,
     apply: opts.apply,
     interactive: opts.interactive !== false,
-  })));
+  }), render.renderFallback));
 forensics.command('load-replay <id>')
   .option('--project-root <path>')
-  .action(async (id, opts) => print(await loadReplay(id, { projectRoot: opts.projectRoot })));
+  .action(async (id, opts) => out(await loadReplay(id, { projectRoot: opts.projectRoot }), render.renderFallback));
 
 // --- install (the MCP server itself into an IDE) ---
 const install = program.command('install').description('Register kit-mcp into an IDE\'s MCP config.');
-install.command('targets').action(async () => print(listInstallTargets()));
+install.command('targets').action(async () => out(listInstallTargets(), render.renderInstallTargets));
 install.command('dry-run <target>')
   .option('--scope <scope>', 'user | project', 'user')
   .option('--name <name>', 'Server name in IDE config', 'kit')
   .option('--via <via>', 'local | npx | global  (how the IDE will invoke the server)', 'local')
   .option('--pkg <name>', 'npm package name (only with --via npx)', '@luanpdd/kit-mcp')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await installMcp(target, { ...opts, dryRun: true })));
-install.command('write <target>')
+  .action(async (target, opts) => out(await installMcp(target, { ...opts, dryRun: true }), render.renderInstallResult));
+install.command('write [target]')
   .option('--scope <scope>', 'user | project', 'user')
   .option('--name <name>', 'Server name in IDE config', 'kit')
   .option('--via <via>', 'local | npx | global', 'local')
   .option('--pkg <name>', 'npm package name (only with --via npx)', '@luanpdd/kit-mcp')
   .option('--force')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await installMcp(target, opts)));
+  .option('--yes', 'Skip confirmation prompt (CI mode)')
+  .action(async (target, opts) => {
+    const globalOpts = program.opts();
+    if (!target) target = await pickTarget(listInstallTargets(), 'Where do you want to register kit-mcp?');
+
+    // Preview first (dry-run)
+    const preview = await installMcp(target, { ...opts, dryRun: true });
+    if (!preview.ok) {
+      out(preview, render.renderInstallResult);
+      process.exit(1);
+    }
+
+    // Show the preview unless --json
+    if (!globalOpts.json) {
+      process.stdout.write(`\n${c.bold('Preview:')} ${c.dim(preview.configPath)}\n\n`);
+      if (preview.preview) {
+        process.stdout.write(c.dim(JSON.stringify(preview.preview, null, 2)) + '\n');
+      } else if (preview.snippet) {
+        process.stdout.write(c.dim(preview.snippet) + '\n');
+      }
+    }
+
+    // Confirm unless --yes or --json (programmatic consumers must pass --yes)
+    if (!opts.yes && !globalOpts.json) {
+      let proceed;
+      try {
+        proceed = await confirm({ message: 'Apply these changes?', default: false });
+      } catch (e) {
+        return fail(`${e.message} (use --yes to skip)`);
+      }
+      if (!proceed) {
+        process.stdout.write(`${c.yellow(icons.warn)} Aborted by user.\n`);
+        process.exit(0);
+      }
+    }
+
+    out(await installMcp(target, opts), render.renderInstallResult);
+  });
+
+// pickTarget — interactive selector for IDE targets, falls back to error in non-TTY/--json
+async function pickTarget(targets, message) {
+  const globalOpts = program.opts();
+  if (globalOpts.json) {
+    return fail('--target is required when using --json mode');
+  }
+  try {
+    return await select({
+      message,
+      choices: targets.map(t => ({
+        name: `${t.label.padEnd(22)} ${c.dim(`(${t.id})`)}`,
+        value: t.id,
+      })),
+    });
+  } catch (e) {
+    return fail(`${e.message} (or pass <target> as argument)`);
+  }
+}
+
+// --- ui (sidecar process viewer) ---
+const ui = program.command('ui').description('Live process viewer in a localhost browser tab.');
+
+ui.command('start')
+  .description('Start the sidecar HTTP server in foreground (Ctrl+C to stop). Prints URL on stderr.')
+  .option('--project-root <path>', 'Project root for lockfile keying (default: cwd)')
+  .option('--port <n>', 'Bind to a specific port (default: auto-pick 7100-7199)')
+  .option('--idle-ms <ms>', 'Idle shutdown timeout (default 30min; 0 = never)')
+  .option('--no-open', 'Skip auto-opening the browser')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const port = opts.port ? Number(opts.port) : undefined;
+    const idleMs = opts.idleMs !== undefined ? Number(opts.idleMs) : undefined;
+    const srv = createServer({ projectRoot, idleMs });
+    try {
+      const { port: actualPort } = await srv.start({ port });
+      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`);
+      if (opts.open !== false) {
+        await openBrowser(url);
+      }
+      // The server's own SIGINT handler will perform shutdown + cleanup.
+      // We just stay alive — server is foreground.
+    } catch (err) {
+      if (err.code === 'ELIVE') {
+        process.stderr.write(`${c.yellow(icons.warn)} sidecar already running for this project\n`);
+        process.stderr.write(`  pid: ${err.lock?.pid}, port: ${err.lock?.port}\n`);
+        process.stderr.write(`  use 'kit ui status' or 'kit ui open' to inspect\n`);
+        process.exit(2);
+      }
+      fail(err.message);
+    }
+  });
+
+ui.command('stop')
+  .description('Stop the sidecar running for this project (POST /shutdown).')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const lock = readLock(projectRoot);
+    if (!lock) return out({ ok: false, reason: 'no_sidecar' }, () => `${icons.warn} no sidecar running for this project\n`);
+    try {
+      await postShutdown(lock.port);
+      out({ ok: true, port: lock.port }, () => `${icons.check} sidecar at port ${lock.port} stopped\n`);
+    } catch (err) {
+      fail(`could not stop sidecar at port ${lock.port}: ${err.message}`);
+    }
+  });
+
+ui.command('status')
+  .description('Show whether a sidecar is running for this project.')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const lock = readLock(projectRoot);
+    if (!lock) {
+      out({ running: false, reason: 'no_lockfile' }, () => `${icons.warn} no sidecar running\n`);
+      process.exit(1);
+    }
+    try {
+      const health = await getHealthz(lock.port);
+      out({ running: true, ...health, lockfile: lockPathFor(projectRoot) }, render.renderUiStatus ?? renderUiStatusFallback);
+    } catch (err) {
+      out({ running: false, reason: 'unreachable', lockfile: lockPathFor(projectRoot), error: err.message },
+          () => `${icons.cross} lockfile present but sidecar unreachable: ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+ui.command('open')
+  .description('Open the running sidecar in a browser. Fails if no sidecar is up.')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    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}/`;
+    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`);
+      process.exit(1);
+    }
+  });
+
+// Helpers for kit ui (live in cli/ — stdout/console allowed here)
+async function postShutdown(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      method: 'POST',
+      host: '127.0.0.1',
+      port,
+      path: '/shutdown',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, origin: `http://127.0.0.1:${port}`, 'content-length': 0, connection: 'close' },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => res.statusCode < 400 ? resolve() : reject(new Error(`http_${res.statusCode}`)));
+    });
+    req.on('error', reject);
+    req.setTimeout(2000, () => { try { req.destroy(); } catch {} ; reject(new Error('timeout')); });
+    req.end();
+  });
+}
+
+async function getHealthz(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      method: 'GET',
+      host: '127.0.0.1',
+      port,
+      path: '/healthz',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, connection: 'close' },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        if (res.statusCode >= 400) return reject(new Error(`http_${res.statusCode}`));
+        try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+        catch (e) { reject(e); }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(2000, () => { try { req.destroy(); } catch {} ; reject(new Error('timeout')); });
+    req.end();
+  });
+}
 
-// --- helpers ---
-function print(x) { process.stdout.write(JSON.stringify(x, null, 2) + '\n'); }
-function fail(msg) { process.stderr.write(msg + '\n'); process.exit(1); }
-function slim(x) { return { kind: x.kind, name: x.name, description: x.description, absPath: x.absPath }; }
+function renderUiStatusFallback(v) {
+  if (!v.running) return `${icons.warn} not running\n`;
+  return [
+    `${icons.check} sidecar running`,
+    `  port:        ${v.port}`,
+    `  pid (sdcr):  ${v.lockfile ? readLock(process.cwd())?.pid : '?'}`,
+    `  uptime:      ${Math.round((v.uptime || 0) / 1000)}s`,
+    `  events:      ${v.eventsTotal}`,
+    `  subscribers: ${v.subscribers}`,
+    `  url:         http://127.0.0.1:${v.port}/`,
+    '',
+  ].join('\n');
+}
 
 program.parseAsync(process.argv);