@luanpdd/kit-mcp 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -6,6 +6,51 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [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.
+
+### Added — Phase 1: Tooling debt
+- `.github/dependabot.yml` — weekly grouped npm + github-actions updates.
+- GitHub Release object created for v0.5.0 (was stuck on v0.2.0 "cleanup" as Latest).
+- `.github/workflows/publish.yml` now creates a GitHub Release object automatically on every `v*` tag push, with notes extracted from this CHANGELOG. Closes the gap permanently.
+
+### Fixed — Phase 2: Slash-command parser
+- `src/core/sync.js` — `renderReference` reorders the stub body so the first non-blank line is the H1 + description blockquote, not the `<!-- kit-mcp:reference -->` marker. Strict downstream parsers (notably Claude Desktop's skill listing) now surface the real description.
+- `src/core/kit.js` — `firstNonEmptyLine` skips lines starting with `<!--` as a defensive fallback when the canonical has no frontmatter description.
+- `kit/commands/*` — 8 commands (`adicionar-backlog`, `adicionar-fase`, `adicionar-tarefa`, `concluir-marco`, `definir-perfil`, `depurar`, `fio`, `inserir-fase`) had unquoted angle-bracket `argument-hint` values that strict YAML parsers misinterpreted as flow-style flags. Now consistently quoted.
+
+### Added — Phase 3: Reverse-sync for mirror-tree caps
+- `detectReverse` now walks `.claude/framework/` and `.claude/hooks/` and reports any byte-for-byte difference vs `kit/<source>/<rel>`. The `.kit-mcp-managed` marker is automatically excluded from candidates.
+- `applyReverse` adds `applyMirrorTreeOne` for `framework`/`hooks` candidates: `skip`, `overwrite`, `merge` (degenerates to overwrite — no frontmatter to preserve), `rename` (writes to `kit/<source>/<rel>.from-<tag>.<ext>` preserving the original).
+- `--only framework/<rel>` / `--only hooks/<file>` filters narrow apply to one file.
+- README "kit reverse-sync" section updated with the new examples.
+
+### Added — Phase 4: Test infrastructure
+- `node:test`-based runner — zero dependencies. `test/run.mjs` walks for `*.test.js` files (works on Node 20+ where `--test` glob support is partial).
+- 37 unit tests across `kit`, `sync`, `reverse-sync`, `gates`, `gate-runner`, `registry`.
+- 5 integration tests spawning `bin/cli.js` end-to-end (incl. MCP server boot smoke).
+- `test/fixtures/sample-kit/` minimal fixture (1 of each kind + framework template + hook + frontmatter-less command for fallback test).
+- CI runs `npm test` + `npm run test:integration` before existing smoke + MCP boot, on Ubuntu / macOS / Windows × Node 20 / 22 (6/6 combinations).
+- `package.json` scripts: `test`, `test:integration`, `test:all`.
+
+### Stable API (commitments locked at 1.0.0)
+
+The following surfaces are covered by SemVer — breaking changes require a 2.0.0 release:
+
+- **`src/core/registry.js` TARGETS table format.** Adding capabilities, IDEs, or new modes is non-breaking. Renaming or removing existing capability keys (`rules`, `agents`, `commands`, `skills`, `framework`, `hooks`, `mcpConfig`) is breaking.
+- **MCP tool action signatures.** Tool names (`kit`, `sync`, `reverse-sync`, `gates`, `forensics`, `install`) and their action-dispatch contracts are stable. New actions are non-breaking; renaming or removing existing actions is breaking.
+- **CLI subcommand surface.** Top-level commands (`kit`, `sync`, `reverse-sync`, `gates`, `forensics`, `install`) and their action sub-commands are stable. New flags are non-breaking; renaming or removing existing ones is breaking.
+- **`src/core/*.js` named exports.** Functions consumed programmatically (`listKit`, `searchKit`, `findItem`, `resolveKitRoot`, `BUNDLED_KIT_ROOT`, `syncTo`, `statusOf`, `removeFrom`, `detectReverse`, `applyReverse`, `listGates`, `getGate`, `gatesForStage`, `runGate`, `listTargets`, `getTarget`, `TARGETS`) keep their signatures. Adding new exports is non-breaking; signature changes are breaking.
+- **Stub format.** Files written by sync `--mode reference` keep the `<!-- kit-mcp:reference -->` marker somewhere in the body so `sync remove` and `reverse-sync detect` continue to identify them. Position within the body may change; presence is the contract.
+- **`.kit-mcp-managed` marker semantics.** Mirror-tree directories (`framework/`, `hooks/`) are managed only when the marker is present at the root. Without it, `sync remove` never deletes the tree.
+
+### Migration
+
+No code changes required for users on 0.5.0 — `npm install @luanpdd/kit-mcp@latest` brings in 1.0.0 with the same behavior plus the parser fixes, reverse-sync expansions, and test coverage.
+
+If you were on 0.4.0 (deprecated) or earlier, upgrade to skip the import-time crash and missing-framework regression entirely.
+
 ## [0.5.0] - 2026-05-03
 
 ### Added
@@ -174,7 +219,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/v0.5.0...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v1.0.0...HEAD
+[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
 [0.4.0]: https://github.com/luanpdd/kit-mcp/compare/v0.3.0...v0.4.0

package/README.md

@@ -194,16 +194,19 @@ kit install write claude-code   --scope user --via global     # assumes `npm ins
 
 ### `kit reverse-sync ...` — bring IDE edits back to the canonical kit
 
-If you edited an agent/command/skill **directly inside the IDE's folder** (`.claude/agents/foo.md`, `.cursor/agents/bar.md`, …) instead of in your kit, this brings those edits back so the canonical absorbs them.
+If you edited an agent/command/skill/framework/hook **directly inside the IDE's folder** (`.claude/agents/foo.md`, `.claude/framework/workflows/bar.md`, `.claude/hooks/baz.js`, …) instead of in your kit, this brings those edits back so the canonical absorbs them.
 
 ```bash
 kit reverse-sync detect claude-code --project-root .
 kit reverse-sync apply  claude-code --project-root . --strategy merge --dry-run
 kit reverse-sync apply  claude-code --project-root . --strategy merge
 kit reverse-sync apply  claude-code --project-root . --strategy overwrite --only agent/foo
+kit reverse-sync apply  claude-code --project-root . --strategy overwrite --only framework/workflows/new-milestone.md
 ```
 
-**Strategies:** `skip` (list-only), `merge` (canonical frontmatter + edited body), `overwrite`, `rename` (preserve both as `-from-{ide}.md`).
+**Strategies:** `skip` (list-only), `merge` (canonical frontmatter + edited body — for agents/commands/skills), `overwrite`, `rename` (preserve both as `-from-{ide}.md`).
+
+**Mirror-tree caps (`framework`, `hooks`):** files have no frontmatter, so `merge` degenerates to `overwrite` (with a note). The `.kit-mcp-managed` marker is automatically excluded from candidates. Filter individual files with `--only framework/<rel>` or `--only hooks/<file>`.
 
 ### `kit gates ...` — reusable workflow gates
 
@@ -469,16 +472,27 @@ PRs welcome.
 
 ---
 
-## Smoke tests
+## Tests
+
+Built on `node:test` (zero dependencies). Two suites:
+
+```bash
+npm test                # unit — kit parser, sync (all modes), reverse-sync, gates, registry
+npm run test:integration  # integration — spawns bin/cli.js end-to-end on a temp project
+npm run test:all          # both
+```
+
+Plus the original quick smokes:
 
 ```bash
 node bin/cli.js kit list-agents | head -5         # 19 bundled agents
 node bin/cli.js sync targets                      # 8 IDEs
 node bin/cli.js gates list                        # 5 gates
 node bin/cli.js install dry-run claude-code --via npx
-node bin/mcp.js < /dev/null & sleep 1; kill %1    # MCP server boots and waits on stdio
 ```
 
+CI runs unit + integration + smoke + MCP boot on Ubuntu / macOS / Windows × Node 20 / 22 on every push and PR.
+
 ---
 
 ## License

package/kit/commands/adicionar-backlog.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-backlog
 description: Adiciona uma ideia ao estacionamento de backlog (numeração 999.x)
-argument-hint: <description>
+argument-hint: "<description>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/adicionar-fase.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-fase
 description: Adiciona fase ao final do milestone atual no roadmap
-argument-hint: <description>
+argument-hint: "<description>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/adicionar-tarefa.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-tarefa
 description: Captura ideia ou tarefa como todo a partir do contexto da conversa atual
-argument-hint: [descrição opcional]
+argument-hint: "[descrição opcional]"
 allowed-tools:
   - Read
   - Write

package/kit/commands/concluir-marco.md

@@ -2,7 +2,7 @@
 type: prompt
 name: concluir-marco
 description: Arquiva milestone concluído e prepara para próxima versão
-argument-hint: <version>
+argument-hint: "<version>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/definir-perfil.md

@@ -1,7 +1,7 @@
 ---
 name: definir-perfil
 description: Altera o perfil de modelo para os agentes framework (quality/balanced/budget/inherit)
-argument-hint: <perfil (quality|balanced|budget|inherit)>
+argument-hint: "<perfil (quality|balanced|budget|inherit)>"
 model: haiku
 allowed-tools:
   - Bash

package/kit/commands/depurar.md

@@ -1,7 +1,7 @@
 ---
 name: depurar
 description: Depuração sistemática com estado persistente entre resets de contexto
-argument-hint: [descrição do problema]
+argument-hint: "[descrição do problema]"
 allowed-tools:
   - Read
   - Bash

package/kit/commands/fio.md

@@ -1,7 +1,7 @@
 ---
 name: fio
 description: Gerencia threads de contexto persistentes para trabalho entre sessões
-argument-hint: [nome | descrição]
+argument-hint: "[nome | descrição]"
 allowed-tools:
   - Read
   - Write

package/kit/commands/inserir-fase.md

@@ -1,7 +1,7 @@
 ---
 name: inserir-fase
 description: Insere trabalho urgente como fase decimal (ex: 72.1) entre fases existentes
-argument-hint: <after> <description>
+argument-hint: "<after> <description>"
 allowed-tools:
   - Read
   - Write

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "0.5.0",
+  "version": "1.0.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": {
@@ -41,7 +41,10 @@
   "scripts": {
     "start": "node bin/mcp.js",
     "cli": "node bin/cli.js",
-    "smoke": "node bin/cli.js kit list-agents | head -5"
+    "smoke": "node bin/cli.js kit list-agents | head -5",
+    "test": "node test/run.mjs test/unit",
+    "test:integration": "node test/run.mjs test/integration",
+    "test:all": "node test/run.mjs test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/core/kit.js

@@ -135,7 +135,10 @@ function parseLooseYaml(text) {
 function firstNonEmptyLine(body) {
   for (const line of body.split(/\r?\n/)) {
     const t = line.trim();
-    if (t && !t.startsWith('#')) return t.slice(0, 200);
+    if (!t) continue;                      // blank
+    if (t.startsWith('#')) continue;       // markdown heading
+    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
+    return t.slice(0, 200);
   }
   return '';
 }

package/src/core/reverse-sync.js

@@ -35,6 +35,11 @@ export async function detectReverse(targetId, opts = {}) {
   if (target.agents)   await scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot);
   if (target.commands) await scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot);
   if (target.skills)   await scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot);
+  for (const cap of ['framework', 'hooks']) {
+    const spec = target[cap];
+    if (!spec || spec.mode !== 'mirror-tree') continue;
+    await scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot);
+  }
 
   return { target: targetId, projectRoot, kitRoot, candidates };
 }
@@ -117,6 +122,51 @@ async function scanSkills(candidates, capCfg, projectRoot, kitSkills, kitRoot) {
   }
 }
 
+async function scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot) {
+  const dstRoot = path.join(projectRoot, spec.path);
+  const srcRoot = path.join(kitRoot, spec.source);
+  const files = await walkRel(dstRoot);
+  for (const rel of files) {
+    if (rel === '.kit-mcp-managed' || path.basename(rel) === '.kit-mcp-managed') continue;
+    const dstPath = path.join(dstRoot, rel);
+    const srcPath = path.join(srcRoot, rel);
+    let dstBuf, srcBuf;
+    try { dstBuf = await fs.readFile(dstPath); } catch { continue; }
+    try { srcBuf = await fs.readFile(srcPath); } catch { srcBuf = null; }
+    if (!srcBuf) {
+      candidates.push({
+        kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+        reason: 'new-in-ide',
+        diffSummary: `+${dstBuf.length} bytes (no kit source)`,
+      });
+      continue;
+    }
+    if (dstBuf.equals(srcBuf)) continue;
+    candidates.push({
+      kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+      reason: 'modified-in-ide',
+      diffSummary: `${dstBuf.length} bytes vs ${srcBuf.length} canonical (${dstBuf.length - srcBuf.length >= 0 ? '+' : ''}${dstBuf.length - srcBuf.length})`,
+    });
+  }
+}
+
+async function walkRel(root) {
+  const out = [];
+  async function visit(current, prefix) {
+    let entries;
+    try { entries = await fs.readdir(current, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) await visit(abs, rel);
+      else if (e.isFile()) out.push(rel);
+    }
+  }
+  await visit(root, '');
+  return out;
+}
+
 // --- apply ---
 
 export async function applyReverse(targetId, opts = {}) {
@@ -139,6 +189,13 @@ export async function applyReverse(targetId, opts = {}) {
 
 async function applyOne(c, strategy, opts) {
   const dryRun = !!opts.dryRun;
+  const isMirrorTree = c.kind === 'framework' || c.kind === 'hooks';
+
+  // Mirror-tree files don't have stub boilerplate — copy bytes verbatim.
+  if (isMirrorTree) {
+    return applyMirrorTreeOne(c, strategy, dryRun);
+  }
+
   const destContent = await fs.readFile(c.destPath, 'utf8');
   const stripped = stripStubBoilerplate(destContent);
 
@@ -147,7 +204,6 @@ async function applyOne(c, strategy, opts) {
       return 'skipped';
 
     case 'overwrite': {
-      // Replace canonical with the destination content (stripped of stub boilerplate)
       if (!dryRun) {
         await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
         await fs.writeFile(c.kitPath, stripped, 'utf8');
@@ -156,8 +212,6 @@ async function applyOne(c, strategy, opts) {
     }
 
     case 'merge': {
-      // Frontmatter from canonical (if present), body from destination.
-      // If canonical doesn't exist (new-in-ide), this degenerates to overwrite.
       let merged = stripped;
       if (c.reason === 'modified-in-ide') {
         try {
@@ -173,7 +227,6 @@ async function applyOne(c, strategy, opts) {
     }
 
     case 'rename': {
-      // Write next to canonical with a -from-<targetfolder>.md suffix
       const base = c.kitPath.replace(/\.md$/, '');
       const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '');
       const out = `${base}-from-${tag || 'ide'}.md`;
@@ -189,6 +242,42 @@ async function applyOne(c, strategy, opts) {
   }
 }
 
+async function applyMirrorTreeOne(c, strategy, dryRun) {
+  switch (strategy) {
+    case 'skip':
+      return 'skipped';
+
+    case 'overwrite':
+    case 'merge': {
+      // For framework/hooks files there's no frontmatter to preserve,
+      // so 'merge' degenerates to overwrite. Returning a verb that
+      // signals the degradation.
+      const verb = strategy === 'merge' ? 'merged (overwrite, no frontmatter)' : 'overwritten';
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
+        await fs.copyFile(c.destPath, c.kitPath);
+      }
+      return dryRun ? `${strategy} (dry-run)` : verb;
+    }
+
+    case 'rename': {
+      // Write to kit/<source>/<rel>.from-<tag> preserving extension after the tag.
+      const ext = path.extname(c.kitPath);
+      const stem = c.kitPath.slice(0, c.kitPath.length - ext.length);
+      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '') || 'ide';
+      const out = `${stem}.from-${tag}${ext}`;
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(out), { recursive: true });
+        await fs.copyFile(c.destPath, out);
+      }
+      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
+    }
+
+    default:
+      return `unknown strategy: ${strategy}`;
+  }
+}
+
 // --- helpers ---
 
 function isCleanStub(content) {

package/src/core/sync.js

@@ -196,15 +196,19 @@ function renderReference(item, kitRoot, outPath, isSkill) {
     ? item.frontmatterRaw
     : synthFrontmatter(item);
 
-  const desc = item.description ? `\n> ${item.description}\n` : '';
-  // Blank line between frontmatter and the stub marker so YAML parsers don't choke.
-  return `${fm}\n${STUB_MARKER}
+  // Body must NOT start with the STUB_MARKER comment — IDE listings (e.g. Claude Desktop)
+  // that take the first non-blank body line as the visible description would surface
+  // "<!-- kit-mcp:reference -->" instead of the real description. So we open with the
+  // H1 + description blockquote, and tuck the marker at the end as a trailing comment.
+  const descLine = item.description ? `\n> ${item.description}\n` : '';
+  return `${fm}
 # ${item.name}
-
+${descLine}
 > Canonical source: [\`${rel}\`](${rel})
-${desc}
-> Generated by kit-mcp at ${new Date().toISOString()}.
 > Edit the source file in the kit, not this stub.
+> Generated by kit-mcp at ${new Date().toISOString()}.
+
+${STUB_MARKER}
 `;
 }