@luanpdd/kit-mcp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,54 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-05-03
+
+**Visual feedback in the terminal.** Running `kit ...` now prints colored tables, progress bars, summary panels and interactive selectors instead of the raw JSON-to-stdout default of v1.0. Programmatic consumers add `--json` to restore the previous behavior.
+
+### Added — Phase 6: UI primitives
+- `src/core/ui.js` — single module exposing `c` (color helpers), `icons`, `spinner`, `progress`, `select`, `confirm`, `summary`. Respects `NO_COLOR`, `FORCE_COLOR`, `process.stdout.isTTY`. Animations write to stderr so stdout stays clean for `--json` piping.
+- Deps: `picocolors` (~3KB, zero subdeps) and `@inquirer/prompts` (modular — only `select`+`confirm` imported).
+
+### Added — Phase 7: `--json` flag, default human
+- `--json` global flag preserves v1.0's JSON-to-stdout behavior for programmatic consumers.
+- Without `--json`: every subcommand renders a human-readable table or summary panel via `src/cli/render.js`.
+- `kit get` is unchanged (still raw, cat-like).
+
+### Added — Phase 8: Progress + spinner
+- `syncTo` and `applyReverse` accept an `opts.onProgress({ phase, current, total, label })` callback. Default no-op preserves backward compat.
+- CLI wraps long ops in `withProgress(label, total, fn)` and short ops in `withSpinner(text, fn)`. TTY animates; pipes/CI emit linear status text (`10%, 20%, ...`).
+
+### Added — Phase 9: Interactive selectors + diff confirm
+- `install write [target]` and `sync install [target]` — when target argument is omitted in TTY mode, opens a select prompt listing all 8 IDEs with labels.
+- `install write` always previews the JSON/TOML to be written and asks `Apply these changes? (y/N)` before applying. `--yes` or `--json` bypasses the prompt for CI/programmatic use.
+- In non-TTY mode without target: exits with a helpful message ("pass the value as a flag instead").
+
+### Stable API additions (1.x compatible)
+
+The 1.0 commitment is unchanged. These additions become part of the contract:
+
+- **`--json` global flag.** Behavior locked: JSON-to-stdout, no ANSI codes, no progress on stderr, prompts replaced by descriptive errors.
+- **`onProgress` callback signature** on `syncTo` and `applyReverse`: `({ phase, current, total, label }) => void`. Adding optional fields is non-breaking.
+- **Interactive selectors fall back to errors in non-TTY**, not to defaults — programs MUST pass the target as argument or use `--json`.
+
+### Migration
+
+Programs and scripts that piped `kit ... | jq` need to add `--json` explicitly:
+```bash
+# Before (v1.0):
+kit list-agents | jq '.[].name'
+
+# After (v1.1):
+kit list-agents --json | jq '.[].name'
+```
+
+Interactive shell users get the new visual output automatically — no flags needed.
+
+### Tests
+- `test/unit/ui.test.js` — 6 new tests covering `summary` rendering, `NO_COLOR` honored, icons set.
+- `test/integration/cli-roundtrip.test.js` — 4 new tests covering `--json` opt-in, default human output, selector fallback in non-TTY for `install write` / `sync install`.
+- Total: 49 unit + 9 integration = **58 tests** in ~4s. CI verde 6/6 (Ubuntu/macOS/Windows × Node 20/22).
+
 ## [1.0.0] - 2026-05-03
 
 **First stable release.** kit-mcp now commits to backwards compatibility on the surfaces listed under "Stable API" below; breaking changes there require a 2.0.0 bump.
@@ -219,7 +267,8 @@ npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 - CLI mirror of all MCP tools.
 - `install` command that registers kit-mcp into an IDE's MCP config (JSON for Claude/Cursor/Gemini/Windsurf, TOML for Codex).
 
-[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/luanpdd/kit-mcp/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/luanpdd/kit-mcp/compare/v0.5.0...v1.0.0
 [0.5.0]: https://github.com/luanpdd/kit-mcp/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/luanpdd/kit-mcp/compare/v0.4.0...v0.4.1

package/README.md

@@ -55,7 +55,7 @@ kit-mcp/
 └── README.md                   ← you are here
 ```
 
-**Lines of source code:** ~1100. **Runtime dependencies:** 3 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`). **Build step:** none — plain ESM Node.js 20+.
+**Lines of source code:** ~1300. **Runtime dependencies:** 5 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`, `picocolors`, `@inquirer/prompts`). **Build step:** none — plain ESM Node.js 20+.
 
 ### About the bundled workflow
 
@@ -128,7 +128,17 @@ For other IDEs, swap `claude-code` for `cursor`, `codex`, `gemini-cli`, `windsur
 
 ## CLI reference
 
-The CLI mirrors the MCP tools 1:1. Output is always JSON to stdout. The global `--kit-root` flag overrides the kit source for any subcommand.
+The CLI mirrors the MCP tools 1:1. **By default the CLI prints colored, human-readable tables and summary panels.** Add `--json` to restore raw JSON-to-stdout (machine-readable, the default in v1.0). The global `--kit-root` flag overrides the kit source for any subcommand.
+
+```bash
+kit list-agents              # human: colored table, name + description
+kit list-agents --json       # machine: JSON array
+
+kit sync install claude-code # human: progress bar + summary panel
+kit sync install claude-code --json  # machine: full result object
+```
+
+In non-TTY mode (pipes, CI), animations degrade to linear status lines automatically. `NO_COLOR=1` disables colors entirely; `FORCE_COLOR=1` forces them on even in pipes.
 
 ### `kit kit ...` — browse the kit
 
@@ -182,8 +192,12 @@ kit install dry-run claude-code --scope user --via npx        # preview the JSON
 kit install write claude-code   --scope user --via npx        # portable: uses `npx @luanpdd/kit-mcp`
 kit install write claude-code   --scope project --via local   # local clone: uses ./bin/mcp.js absolute path
 kit install write claude-code   --scope user --via global     # assumes `npm install -g @luanpdd/kit-mcp`
+kit install write                                             # no target: opens an interactive selector (TTY)
+kit install write claude-code --yes                           # CI: skip the confirm prompt
 ```
 
+Since v1.1, `install write` always **previews** the JSON/TOML it's about to write and asks you to confirm. Pass `--yes` (CI mode) or `--json` to bypass the prompt. Without a target argument in TTY mode, you get an arrow-key selector listing all 8 IDEs.
+
 `--via` decides how the IDE will invoke the server:
 
 | Mode | Command in IDE config | When to use |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.0.0",
+  "version": "1.1.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,8 +47,10 @@
     "test:all": "node test/run.mjs test"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chokidar": "^5.0.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
   }
 }

package/src/cli/index.js

@@ -7,6 +7,10 @@
 //   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 { listKit, searchKit, findItem } from '../core/kit.js';
@@ -20,49 +24,122 @@ 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';
 
 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('1.0.0')
+  .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)');
 
-// 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.
+async function withProgress(label, total, fn) {
+  const opts = program.opts();
+  if (opts.json) return fn(() => {});
+  const p = progress({ total, label });
+  let last = '';
+  const onProgress = ({ current, label }) => { last = label || last; p.tick({ label: last }); };
+  try {
+    const r = await fn(onProgress);
+    p.finish(label);
+    return r;
+  } catch (e) {
+    p.finish();
+    throw e;
+  }
+}
+
+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 }),
+    );
+    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 +170,57 @@ 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 }),
+    );
+    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 +228,90 @@ 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);
+      }
+    }
 
-// --- 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 }; }
+    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)`);
+  }
+}
 
 program.parseAsync(process.argv);

package/src/cli/render.js

@@ -0,0 +1,187 @@
+// Human-readable renderers for each CLI subcommand. The CLI default switched
+// from JSON-to-stdout to these in v1.1; --json restores the old behavior
+// (still useful for piping to jq, MCP-like consumers, etc.).
+//
+// Conventions:
+//   - Render functions write to process.stdout (no trailing newline beyond
+//     what the formatted output naturally has).
+//   - They never throw on missing fields — the result objects come from
+//     core/ which already shape them.
+//   - Cores happen via src/core/ui.js (which already disables in NO_COLOR
+//     or when --no-tty etc.).
+
+import path from 'node:path';
+import { c, icons, summary } from '../core/ui.js';
+
+// --- generic helpers ---
+
+function table(rows, headers) {
+  if (rows.length === 0) {
+    return `${c.dim('(empty)')}\n`;
+  }
+  const cols = headers.length;
+  const widths = new Array(cols).fill(0);
+  for (let i = 0; i < cols; i++) widths[i] = Math.max(headers[i].length, ...rows.map(r => String(r[i] ?? '').length));
+  const out = [];
+  out.push(headers.map((h, i) => c.bold(h.padEnd(widths[i]))).join('  '));
+  out.push(headers.map((_, i) => c.dim('─'.repeat(widths[i]))).join('  '));
+  for (const r of rows) {
+    out.push(r.map((v, i) => String(v ?? '').padEnd(widths[i])).join('  '));
+  }
+  return out.join('\n') + '\n';
+}
+
+// --- kit ---
+
+export function renderKitList(items, kind) {
+  if (items.length === 0) {
+    return `${c.dim(`No ${kind}s in kit.`)}\n`;
+  }
+  const rows = items.map(x => [x.name, (x.description ?? '').slice(0, 80)]);
+  return table(rows, ['name', 'description']);
+}
+
+export function renderKitSearch(results) {
+  if (results.length === 0) {
+    return `${c.dim('No matches.')}\n`;
+  }
+  const rows = results.map(x => [x.kind, x.name, (x.description ?? '').slice(0, 70)]);
+  return table(rows, ['kind', 'name', 'description']);
+}
+
+// --- sync ---
+
+export function renderSyncTargets(targets) {
+  const rows = targets.map(t => [
+    t.id,
+    t.label,
+    Object.entries(t.capabilities).filter(([, v]) => v).map(([k]) => k).join(', '),
+  ]);
+  return table(rows, ['id', 'label', 'capabilities']);
+}
+
+export function renderSyncStatus(result) {
+  const rows = result.checks.map(c => [c.capability, c.path, c.exists ? '✓' : '—']);
+  return `${c.bold(`Status: ${result.target}`)}  ${c.dim(result.projectRoot)}\n` + table(rows, ['cap', 'path', 'present']);
+}
+
+export function renderSyncInstall(result) {
+  // Tally written paths by capability prefix
+  const counts = {};
+  for (const p of result.written) {
+    const rel = path.relative(result.projectRoot, p).replace(/\\/g, '/');
+    // Hide internal markers from the user-facing tally (they're a kit-mcp impl detail)
+    if (rel.endsWith('/.kit-mcp-managed')) continue;
+    let cap = 'rules';
+    if (rel.includes('.claude/agents/'))    cap = 'agents';
+    else if (rel.includes('.claude/commands/'))  cap = 'commands';
+    else if (rel.includes('.claude/skills/'))    cap = 'skills';
+    else if (rel.includes('.claude/framework/')) cap = 'framework';
+    else if (rel.includes('.claude/hooks/'))     cap = 'hooks';
+    counts[cap] = (counts[cap] ?? 0) + 1;
+  }
+  const rows = [];
+  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
+    if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
+  }
+  const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  return summary({
+    title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
+    rows,
+    total: visibleTotal,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+export function renderSyncRemove(result) {
+  return summary({
+    title: `Removed kit-mcp stubs from ${result.target}`,
+    rows: [['Files removed', result.removed.length]],
+    total: result.removed.length,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+// --- reverse-sync ---
+
+export function renderReverseDetect(result) {
+  if (result.candidates.length === 0) {
+    return `${c.green(icons.check)} No edits to bring back. Canonical kit and ${result.target} are in sync.\n`;
+  }
+  const rows = result.candidates.map(x => [x.kind, x.name, x.reason, x.diffSummary ?? '']);
+  return `${c.bold(`Candidates: ${result.candidates.length}`)}  ${c.dim(`(${result.target})`)}\n` +
+    table(rows, ['kind', 'name', 'reason', 'diff']);
+}
+
+export function renderReverseApply(result) {
+  const rows = result.results.map(x => [
+    x.kind,
+    x.name,
+    x.action.startsWith('overwrit') || x.action.startsWith('merge') || x.action.startsWith('renamed')
+      ? c.green(x.action)
+      : x.action.startsWith('skipped') ? c.dim(x.action) : c.yellow(x.action),
+  ]);
+  return `${c.bold(`Applied (strategy=${result.strategy})`)}\n` + table(rows, ['kind', 'name', 'action']);
+}
+
+// --- gates ---
+
+export function renderGatesList(items) {
+  const rows = items.map(g => [g.id, g.stage, g.blocking ? c.red('blocking') : c.dim('warn-only'), g.description]);
+  return table(rows, ['id', 'stage', 'mode', 'description']);
+}
+
+export function renderGateRun(result) {
+  const verdictColor = result.verdict === 'passed' ? c.green
+                     : result.verdict === 'block'  ? c.red
+                     : result.verdict === 'warn'   ? c.yellow
+                     : c.dim;
+  return `${c.bold(`Gate ${result.id}`)}: ${verdictColor(result.verdict)} ${result.exitCode !== undefined ? c.dim(`(exit ${result.exitCode})`) : ''}\n`;
+}
+
+// --- forensics ---
+
+export function renderForensicsCollect(items) {
+  if (items.length === 0) return `${c.dim('No failures collected.')}\n`;
+  const rows = items.map(x => [x.agent ?? '?', x.kind ?? '?', x.absPath ?? x.path ?? '']);
+  return table(rows, ['agent', 'kind', 'path']);
+}
+
+export function renderForensicsSummarize(byAgent) {
+  const entries = Object.entries(byAgent ?? {});
+  if (entries.length === 0) return `${c.dim('No failures.')}\n`;
+  const rows = entries.map(([agent, items]) => [agent, Array.isArray(items) ? items.length : '?']);
+  return table(rows, ['agent', 'failures']);
+}
+
+export function renderListReplays(items) {
+  if (!Array.isArray(items) || items.length === 0) return `${c.dim('No replays recorded.')}\n`;
+  const rows = items.map(r => [r.id ?? '?', r.agent ?? '?', r.timestamp ?? '?']);
+  return table(rows, ['id', 'agent', 'recorded']);
+}
+
+// --- install ---
+
+export function renderInstallTargets(targets) {
+  const rows = targets.map(t => [t.id, t.label, t.scopes?.join(', ') ?? '?']);
+  return table(rows, ['id', 'label', 'scopes']);
+}
+
+export function renderInstallResult(result) {
+  return summary({
+    title: result.dryRun ? `Install preview (${result.target}, scope=${result.scope})` : `Registered kit-mcp → ${result.target} (scope=${result.scope})`,
+    rows: [
+      ['Path',  result.path ?? '?'],
+      ['Name',  result.name ?? 'kit'],
+      ['Via',   result.via ?? '?'],
+    ].map(([k, v]) => [k, v ?? '—']),
+    hint: result.dryRun ? c.dim('No file written (dry-run)') : undefined,
+  }) + '\n';
+}
+
+// --- generic fallback ---
+
+export function renderFallback(value) {
+  // Used when we don't have a custom renderer yet.
+  return JSON.stringify(value, null, 2) + '\n';
+}

package/src/core/reverse-sync.js

@@ -171,17 +171,21 @@ async function walkRel(root) {
 
 export async function applyReverse(targetId, opts = {}) {
   const strategy = opts.strategy ?? 'skip';
+  const onProgress = opts.onProgress ?? (() => {});
   const { candidates } = await detectReverse(targetId, opts);
   const results = [];
 
-  for (const c of candidates) {
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
     if (opts.only && !opts.only.includes(`${c.kind}/${c.name}`)) {
       results.push({ ...c, action: 'skipped (filter)' });
+      onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
       continue;
     }
 
     const action = await applyOne(c, strategy, opts);
     results.push({ ...c, action });
+    onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
   }
 
   return { target: targetId, strategy, results };

package/src/core/sync.js

@@ -24,6 +24,7 @@ export async function syncTo(targetId, opts = {}) {
   const kitRoot     = resolveKitRoot(opts.kitRoot);
   const mode        = opts.mode ?? 'reference';
   const dryRun      = !!opts.dryRun;
+  const onProgress  = opts.onProgress ?? (() => {});
 
   const kit  = await listKit(kitRoot);
   const ops  = [];
@@ -82,6 +83,7 @@ export async function syncTo(targetId, opts = {}) {
   }
 
   if (!dryRun) {
+    let i = 0;
     for (const op of ops) {
       await fs.mkdir(path.dirname(op.path), { recursive: true });
       if (op.treeCopy) {
@@ -89,6 +91,8 @@ export async function syncTo(targetId, opts = {}) {
       } else {
         await fs.writeFile(op.path, op.content, 'utf8');
       }
+      i++;
+      onProgress({ phase: op.kind, current: i, total: ops.length, label: path.basename(op.path) });
     }
   }
 

package/src/core/ui.js

@@ -0,0 +1,167 @@
+// UI primitives for the CLI: colors, icons, spinner, progress bar,
+// interactive select/confirm prompts, and a summary panel.
+//
+// Design rules:
+//   - Respect process.stdout.isTTY: animations only when interactive.
+//     In pipes/CI, fall back to linear status text.
+//   - Respect NO_COLOR (https://no-color.org) and FORCE_COLOR=1.
+//   - Animations write to stderr to keep stdout clean for `--json` mode
+//     (the user can still pipe machine-readable output even with spinners).
+//   - Zero hidden globals — every primitive is a plain function/class.
+
+import pc from 'picocolors';
+import { select as inqSelect, confirm as inqConfirm } from '@inquirer/prompts';
+
+// --- color helpers ---
+
+const NO_COLOR = process.env.NO_COLOR && process.env.NO_COLOR !== '0';
+const FORCE    = process.env.FORCE_COLOR === '1';
+const COLOR_ON = FORCE || (!NO_COLOR && process.stdout.isTTY);
+
+function id(s) { return String(s); }
+export const c = COLOR_ON
+  ? {
+      green: pc.green, red: pc.red, yellow: pc.yellow, cyan: pc.cyan,
+      magenta: pc.magenta, blue: pc.blue, dim: pc.dim, bold: pc.bold,
+      gray: pc.gray, underline: pc.underline,
+    }
+  : {
+      green: id, red: id, yellow: id, cyan: id, magenta: id, blue: id,
+      dim: id, bold: id, gray: id, underline: id,
+    };
+
+export const icons = {
+  check:   '✓',
+  cross:   '✗',
+  warn:    '⚠',
+  dot:     '•',
+  arrow:   '→',
+  spinner: ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
+};
+
+// --- spinner ---
+
+export function spinner({ text = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  let i = 0;
+  let current = text;
+  let timer = null;
+
+  function render() {
+    process.stderr.write(`\r${c.cyan(icons.spinner[i])} ${current}\x1b[K`);
+    i = (i + 1) % icons.spinner.length;
+  }
+
+  if (tty) {
+    timer = setInterval(render, 80);
+    render();
+  } else {
+    process.stderr.write(`${icons.dot} ${current}\n`);
+  }
+
+  function clearLine() {
+    if (tty) process.stderr.write('\r\x1b[K');
+  }
+
+  return {
+    update(t) { current = t; if (!tty) process.stderr.write(`${icons.dot} ${t}\n`); },
+    succeed(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.green(icons.check)} ${t ?? current}\n`);
+    },
+    fail(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.red(icons.cross)} ${t ?? current}\n`);
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      clearLine();
+    },
+  };
+}
+
+// --- progress bar ---
+
+export function progress({ total, label = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  const width = 24;
+  let current = 0;
+  let lastLabel = label;
+
+  function render() {
+    const pct = total === 0 ? 100 : Math.min(100, Math.round((current / total) * 100));
+    const filled = Math.round((width * pct) / 100);
+    const bar = '━'.repeat(filled) + c.dim('━'.repeat(width - filled));
+    const line = `${c.cyan(bar)} ${pct.toString().padStart(3)}% ${c.dim(`(${current}/${total})`)} ${lastLabel}`;
+    process.stderr.write(`\r${line}\x1b[K`);
+  }
+
+  function tick({ label } = {}) {
+    current++;
+    if (label !== undefined) lastLabel = label;
+    if (tty) {
+      render();
+    } else if (current === total || current % Math.max(1, Math.floor(total / 10)) === 0) {
+      // Every ~10% in non-TTY mode
+      const pct = total === 0 ? 100 : Math.round((current / total) * 100);
+      process.stderr.write(`  ${pct}% ${lastLabel}\n`);
+    }
+  }
+
+  function finish(text) {
+    if (tty) {
+      process.stderr.write('\r\x1b[K');
+    }
+    if (text) process.stderr.write(`${c.green(icons.check)} ${text}\n`);
+  }
+
+  if (tty) render();
+  return { tick, finish };
+}
+
+// --- interactive prompts ---
+
+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.');
+  }
+  return inqSelect(opts);
+}
+
+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.');
+  }
+  return inqConfirm(opts);
+}
+
+// --- summary panel ---
+
+export function summary({ title, rows = [], total, hint }) {
+  const lines = [];
+  lines.push(`${c.green(icons.check)} ${c.bold(title)}`);
+  lines.push('');
+
+  // Compute label column width
+  const w = Math.max(...rows.map(r => String(r[0]).length), 0);
+  for (const [label, count, status] of rows) {
+    const cnt = count > 0 ? c.green(String(count).padStart(4)) : c.dim(String(count).padStart(4));
+    const tail = status === 'fail' ? c.red(icons.cross) : c.green(icons.check);
+    lines.push(`  ${label.padEnd(w)}  ${cnt}  ${tail}`);
+  }
+
+  if (total !== undefined || hint) {
+    lines.push('');
+    const totalStr = total !== undefined ? `Total: ${c.bold(total)}` : '';
+    const hintStr = hint ? c.dim(`· ${hint}`) : '';
+    lines.push(`  ${totalStr}${totalStr && hintStr ? ' ' : ''}${hintStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- helpers exposed for tests ---
+
+export const _internal = { COLOR_ON };