@luanpdd/kit-mcp 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,154 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-05-04
+
+**GUI sidecar de acompanhamento.** Janela web localhost paralela mostra ao vivo (via Server-Sent Events) o que kit-mcp está fazendo enquanto sua IDE chama tools — `sync install`, `reverse-sync apply`, `gates run`. Sidecar é totalmente opt-in: quem não invoca `kit ui` continua com a experiência v1.1 idêntica.
+
+### Adicionado — Phase 11: Lock arquitetural
+- ADR consolidado em `.planning/decisions.md` (porta 7100-7199, lockfile em `os.tmpdir()` keyed por sha1(projectRoot), idle 30min default, sem auth no v1.2 com mitigação compensatória)
+- Threat model em `docs/sidecar-security.md`
+- 2 audit gates novos no CI: stdout discipline em `src/ui/` (proíbe `console.log`/`process.stdout.write`) e dep budget (≤ baseline+1)
+
+### Adicionado — Phase 12: Fundações
+- `src/ui/events.js` — schema de evento, validador puro, `makeEvent`, `newRunId`
+- `src/ui/port.js` — `findFreePort` na faixa 7100-7199 com retry-loop
+- `src/ui/lockfile.js` — `acquireLock` atômico via `O_EXCL`, `probeStale` via `process.kill(pid, 0)` + healthz HTTP
+
+### Adicionado — Phase 13: Servidor HTTP + SSE
+- `src/ui/server.js` — http.Server nativo, bind 127.0.0.1 literal, 5 rotas (`/`, `/events` SSE, `/healthz`, `/state`, `/publish`, `/shutdown`)
+- Heartbeat `: ping\n\n` cada 15s; reconnect auto via EventSource native + `retry: 3000`
+- Ring buffer in-memory de 200 eventos (FIFO; sem persistência em disco)
+- Cap de 32 conexões SSE; cleanup quádruplo (req+res × close+error)
+- Idle shutdown 30min default (`--idle-ms 0` desabilita)
+- Encerramento gracioso em SIGINT/SIGTERM com active sockets destruídos
+- Validação de `Host` header (mitiga DNS rebinding) e `Origin` em endpoints non-GET
+- `bin/ui.js` entry detached
+
+### Adicionado — Phase 14: UI estática single-file
+- `src/ui/static/index.html` (~470 LOC) — vanilla DOM + EventSource, sem build step
+- Lista cronológica + auto-scroll + `<details>` expand
+- Badges coloridos por tipo (`run.start`, `run.end`, `tool_invocation`, `progress`, `milestone`, `error`, `shutdown`)
+- Status conexão (CONNECTING/OPEN/CLOSED) + reconexão automática
+- Filter por tipo (chips) + substring search
+- Pause/resume com buffer + autoscroll toggle
+- Dark mode automático via `prefers-color-scheme`
+- Banner de shutdown PT-BR em CLOSED >5s ou evento `shutdown`
+- CSP estrito (`default-src 'self'; ...; frame-ancestors 'none'`)
+
+### Adicionado — Phase 15: Publisher + wrapper + browser-open
+- `src/ui/client.js` — `publish(event, {projectRoot})` fire-and-forget, cache TTL 5s, falha silenciosa em ECONNREFUSED
+- `src/ui/wrapper.js` — `wrapProgressForUi(onProgress, ctx)` multiplexa terminal + sidecar; helpers `.done/.error/.emit`; `redactPath` central scrubando `$HOME → ~` e `projectRoot → <project>` em TODO payload
+- `src/ui/browser.js` — wrapper sobre `open@11` com detection de headless (CI, DISPLAY, SSH, WSL, sandbox); fallback "imprime URL no stderr"
+- Nova dep: `open@^11.0.0` (única adição; budget atingido em 6/6)
+
+### Adicionado — Phase 16: CLI integration
+- `kit ui start` — sobe sidecar foreground (Ctrl+C mata); flags `--port`, `--idle-ms`, `--no-open`
+- `kit ui stop` — POST /shutdown
+- `kit ui status` — exibe pid, port, uptime, eventos, subscribers
+- `kit ui open` — reabre browser na sidecar atual
+- Auto-detect: `kit sync install` e `kit reverse-sync apply` checam lockfile e wrappam `onProgress` automaticamente quando sidecar está rodando
+- Opt-out global via `--no-ui` flag ou `KIT_MCP_NO_UI=1` env var
+
+### Adicionado — Phase 17: MCP --auto-spawn
+- `src/ui/auto-spawn.js` — `ensureSidecar({projectRoot})` checa lockfile + healthz; se ausente, spawna `bin/ui.js` em **detached** com `windowsHide: true` e `stdio: ['ignore', 'ignore', 'inherit']` (fecha stdout completamente — não pode poluir canal MCP do parent)
+- 3 tools MCP ganham campo opcional `autoSpawn: boolean` no inputSchema:
+  - `sync` (action=install)
+  - `reverse-sync` (action=apply)
+  - `gates` (nova action `run`, com autoSpawn)
+- Tools triviais (`kit`, `forensics`, `install`) **não** ganham autoSpawn — explicit-out por design
+
+### Adicionado — Phase 18: Hardening + release
+- 3 hardening tests novos: kill -9 recovery, multi-publisher race, MCP stdio uncorrupted (validação rigorosa do REQ SEC-04 em produção)
+- README seção "Live UI" com primeiros passos
+- `npm pack --dry-run` valida que `src/ui/static/index.html` é incluído no tarball
+
+### Corrigido
+- **REL-01 (bug pré-existente):** `kit --version` agora lê de `package.json` em vez de retornar string hardcoded `1.0.0`. Em v1.0/v1.1 o comando exibia versão errada — corrigido nesta release.
+
+### Stable API additions (1.x compatible)
+
+A v1.0 commitment continua válida. Estas adições são parte do contrato:
+
+- **MCP tool `sync` inputSchema:** campo opcional `autoSpawn: boolean` em action=install. Tools que não passam mantêm comportamento idêntico.
+- **MCP tool `reverse-sync` inputSchema:** campo opcional `autoSpawn: boolean` em action=apply.
+- **MCP tool `gates` inputSchema:** campo opcional `autoSpawn: boolean` E nova action `run` com `id`/`projectRoot`/`autoSpawn` campos.
+- **CLI subgroup `kit ui`:** novo grupo com `start | stop | status | open` subcommands.
+- **CLI flag `--no-ui` global** + env var `KIT_MCP_NO_UI=1` — opt-out do auto-detect de sidecar.
+- **Stable runtime guarantee:** core (`syncTo`, `applyReverse`, `runGate`) é literalmente intocado. Wrapper de `onProgress` é montado APENAS no callsite (CLI handler ou MCP tool handler).
+
+### Migration
+
+**Usuários v1.1 não precisam fazer nada.** Sidecar é estritamente opt-in.
+
+Para experimentar a UI:
+```bash
+# 1. Em um terminal:
+kit ui start
+
+# 2. Em outro (ou via Claude Code/Cursor):
+kit sync install claude-code
+
+# A janela mostra o progresso em tempo real.
+```
+
+Para tools MCP, passe `autoSpawn: true` quando quiser auto-abrir:
+```jsonc
+{ "tool": "sync", "arguments": { "action": "install", "target": "claude-code", "autoSpawn": true } }
+```
+
+### Threat model resumido
+
+Sidecar é **localhost only**, single-user, dev workstation. Sem auth (mitigado por bind 127.0.0.1 + Host/Origin check + CSP estrito + path scrubbing). Sem persistência. Sem TLS (loopback). Detalhes em [`docs/sidecar-security.md`](docs/sidecar-security.md).
+
+## [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 +367,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 |
@@ -258,6 +272,38 @@ kit forensics load-replay <id> --project-root .
 
 The proposal is always saved to `.planning/learnings/{agent}.proposal.md` first; the canonical is only modified after explicit confirmation (or `--apply`). MCP `forensics.reflect` never auto-applies.
 
+### `kit ui ...` — live process viewer (sidecar) — _new in 1.2_
+
+A tiny localhost web app that streams what kit-mcp is doing while your IDE drives it. Strictly opt-in: ignore it and v1.1 behavior is unchanged.
+
+```bash
+# In one terminal — keeps running until Ctrl+C
+kit ui start
+
+# In another terminal (or via Claude Code / Cursor) — runs as before, but events
+# are now also broadcast to the sidecar window
+kit sync install claude-code
+
+# Tools too: pass autoSpawn:true on the MCP side, or just `kit ui start` first
+kit ui status
+kit ui stop
+```
+
+What you get:
+
+- A single browser tab at `http://127.0.0.1:7100` (or the next free port up to 7199)
+- Live event stream over Server-Sent Events — `tool_invocation`, `progress`, `error`, `milestone`, `run.start`, `run.end`
+- Filters by event type and substring; pause/resume; auto-scroll; dark mode tracks the OS
+- The sidecar shuts itself down after 30 minutes of idle; `--idle-ms 0` disables that
+
+**Auto-spawn from MCP tools.** Pass `autoSpawn: true` in the inputSchema of `sync` (action=install), `reverse-sync` (action=apply), or `gates` (action=run). The MCP server will spawn `bin/ui.js` detached, wait for it to come online, open your default browser, and stream that tool's progress. Trivial tools (`kit list-*`, `forensics`, `install`) deliberately don't accept `autoSpawn` — the overhead isn't worth it.
+
+**Opt-out always available.** From the CLI: pass `--no-ui` or set `KIT_MCP_NO_UI=1`. The sidecar is never started behind your back; it's only used when a lockfile is already present (someone ran `kit ui start` or `autoSpawn: true`).
+
+**Security model.** Sidecar binds to `127.0.0.1` literally — never `0.0.0.0`, never `localhost` (which resolves to `::1` on Windows). Every route validates the `Host` header to mitigate DNS rebinding. CSP is strict (`default-src 'self'; …; frame-ancestors 'none'`). Paths in payloads are scrubbed (`$HOME → ~`, `<projectRoot> → <project>`) so screenshots don't leak directory structure. No persistence, no TLS, no auth — single-user dev workstation only. Full threat model in [`docs/sidecar-security.md`](docs/sidecar-security.md).
+
+**First-run quirks.** Windows Defender / macOS firewall may prompt the first time `kit ui start` binds. Approving "Private networks" is enough — the server doesn't accept anything from outside loopback regardless. On WSL, `kit ui start` opens the URL in the Windows host browser via `wslview`. In CI / SSH / `TERM=dumb`, browser launch is suppressed and the URL is printed to stderr instead.
+
 ---
 
 ## MCP usage

package/bin/ui.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// bin/ui.js — entry point for the sidecar HTTP server.
+//
+// Used both directly (when the user runs `kit ui start`) and as the spawn target
+// when `--auto-spawn` is enabled on an MCP tool.
+//
+// Logging discipline: all output goes to stderr. stdout is reserved so that
+// callers can pipe `node bin/ui.js | jq` without UI server chatter contaminating
+// data streams (and so that this file can never poison an MCP stdio channel).
+
+import process from 'node:process';
+import { createServer } from '../src/ui/server.js';
+
+function parseArgs(argv) {
+  const args = { projectRoot: process.cwd(), port: undefined, idleMs: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--project-root' && argv[i + 1]) { args.projectRoot = argv[i + 1]; i += 1; }
+    else if (a === '--port' && argv[i + 1]) { args.port = Number(argv[i + 1]); i += 1; }
+    else if (a === '--idle-ms' && argv[i + 1]) { args.idleMs = Number(argv[i + 1]); i += 1; }
+    else if (a === '--version') { args.printVersion = true; }
+    else if (a === '--help' || a === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  process.stderr.write([
+    'kit-mcp sidecar entry — usually invoked via `kit ui start`',
+    '',
+    'Usage: node bin/ui.js [options]',
+    '  --project-root <path>   project root for lockfile keying (default: cwd)',
+    '  --port <n>              bind to a specific port (default: auto-pick 7100-7199)',
+    '  --idle-ms <ms>          idle shutdown timeout (default: 1800000 = 30min; 0 = never)',
+    '  --version               print version and exit',
+    '  --help                  this text',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+let pkgVersion = null;
+try {
+  const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
+  pkgVersion = pkg.version;
+} catch {
+  // ok — version may not be available in some packaged contexts
+}
+
+if (args.printVersion) {
+  process.stderr.write(`${pkgVersion ?? 'unknown'}\n`);
+  process.exit(0);
+}
+
+const server = createServer({
+  projectRoot: args.projectRoot,
+  version: pkgVersion,
+  idleMs: args.idleMs,
+});
+
+try {
+  const { port } = await server.start({ port: args.port });
+  process.stderr.write(`[kit-mcp ui] listening on http://127.0.0.1:${port}/\n`);
+  process.stderr.write(`[kit-mcp ui] project: ${args.projectRoot}\n`);
+} catch (err) {
+  if (err.code === 'ELIVE') {
+    process.stderr.write(`[kit-mcp ui] sidecar already running for this project (pid=${err.lock?.pid}, port=${err.lock?.port})\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`[kit-mcp ui] failed to start: ${err.message}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.0.0",
+  "version": "1.2.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,11 @@
     "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",
+    "open": "^11.0.0",
+    "picocolors": "^1.1.1"
   }
 }