specpipe 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpipe",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Spec-first development toolkit for agentic AI coding agents — installs skills + guardrails for Claude Code, Codex, Cursor, Antigravity, and more.",
   "bin": {
     "specpipe": "./bin/devkit.js",

package/src/commands/init-agents.js

@@ -9,7 +9,7 @@ import { hashContent } from '../lib/hasher.js';
 import {
   COMPONENTS,
   fillTemplate, installAgentSkills, installAgentRules, installAgentHooks,
-  resolveSkills,
+  resolveSkills, pruneOrphans,
 } from '../lib/installer.js';
 import { resolveAgents, AGENTS, agentHasHooks } from '../lib/agents.js';
 import { resolveHooks } from '../lib/hooks.js';
@@ -102,6 +102,14 @@ export async function initMultiAgent(targetDir, opts, warnings = 0) {
     setFileEntry(manifest, relPath, d.kitHash, installedHash, { agent: d.agent, templateRel: d.templateRel });
   }
 
+  // Migration: prune predecessor files (mf-* / ap-*, renamed hooks) a prior manifest
+  // tracked but this install no longer wants — only manifest-tracked paths, so a
+  // user's own files are never touched.
+  if (existing?.files) {
+    const n = await pruneOrphans(targetDir, existing.files, new Set(Object.keys(manifest.files)));
+    if (n) log.info(`Migrated: removed ${n} superseded file(s) from a previous version.`);
+  }
+
   await writeManifest(targetDir, manifest);
 
   // Summary

package/src/commands/init-global.js

@@ -15,6 +15,14 @@ import { hookScriptsFor } from '../lib/hooks.js';
 
 const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
 
+/** Which agent a home-relative global key belongs to, by its skill-root prefix. */
+function ownerFromGlobalKey(key) {
+  for (const [id, a] of Object.entries(AGENTS)) {
+    if (a.globalSkillRoot && key.startsWith(a.globalSkillRoot + '/')) return id;
+  }
+  return null;
+}
+
 export async function readGlobalManifest() {
   try {
     return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8'));
@@ -68,8 +76,9 @@ export async function initGlobal({ agents = ['claude'], skills = null, hookSelec
   // Global hooks are Claude-only (its native enforcement engine).
   const wantHooks = hooks && agents.includes('claude');
   if (wantHooks) {
-    const hookKeys = await initGlobalHooks({ force, hooks: hookSelection, _globalFiles: updatedFiles, _skipManifestWrite: true });
+    const { keys: hookKeys, entries: hookEntries } = await initGlobalHooks({ force, hooks: hookSelection, _globalFiles: updatedFiles, _skipManifestWrite: true });
     for (const k of hookKeys) installedKeys.add(k);
+    Object.assign(updatedFiles, hookEntries); // persist hook kitHashes in the global manifest
   }
 
   // Prune orphans: files from a previous global install that are no longer desired
@@ -80,7 +89,10 @@ export async function initGlobal({ agents = ['claude'], skills = null, hookSelec
   for (const [key, entry] of Object.entries(globalFiles)) {
     if (installedKeys.has(key)) continue;
     const isHook = key.startsWith('.claude/hooks/');
-    const owner = entry.agent || (isHook ? 'claude' : null);
+    // Legacy claude-devkit / agentpipe manifests recorded skills with NO `agent` field;
+    // derive the owner from the key's global-skill-root prefix (e.g. .claude/skills/ →
+    // claude) so those predecessor mf-*/ap-* skills get pruned, not silently skipped.
+    const owner = entry.agent || (isHook ? 'claude' : ownerFromGlobalKey(key));
     const inScope = isHook ? wantHooks : (owner && agents.includes(owner));
     if (!inScope) continue;
     const abs = join(homedir(), ...key.split('/'));
@@ -101,6 +113,18 @@ export async function initGlobal({ agents = ['claude'], skills = null, hookSelec
   }
   if (pruned) log.info(`Pruned ${pruned} stale global file(s).`);
 
+  // Legacy migration: older claude-devkit installs left ~/.claude/scripts/build-test.sh
+  // (no longer in the kit, untracked by the manifest). Sweep it up on install too —
+  // not just on remove — so upgrading from the old tool leaves nothing behind.
+  if (wantHooks) {
+    const legacyScript = join(homedir(), '.claude', 'scripts', 'build-test.sh');
+    try {
+      await unlink(legacyScript);
+      log.del('~/.claude/scripts/build-test.sh (legacy)');
+      try { await rmdir(join(homedir(), '.claude', 'scripts')); } catch { /* keep if other scripts */ }
+    } catch { /* not present — fine */ }
+  }
+
   await writeGlobalManifest({
     ...existing,
     globalInstalled: installedAgents.has('claude') || existing.globalInstalled || false,
@@ -121,6 +145,9 @@ export async function initGlobalHooks({ force = false, hooks = null, _globalFile
   const globalFiles = _globalFiles || existing?.files || {};
   const updatedFiles = { ...globalFiles };
   const keys = []; // home-relative keys installed this run (for the caller's orphan-prune)
+  const entries = {}; // kitHash entries written this run — the caller persists these so
+                      // hooks are TRACKED (else savedKitHash is always undefined → every
+                      // version bump looks "customized" and stale hooks never auto-update)
 
   log.blank();
   console.log('--- Installing global hooks ---');
@@ -133,7 +160,7 @@ export async function initGlobalHooks({ force = false, hooks = null, _globalFile
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
-    if (result !== 'skipped') updatedFiles[key] = { kitHash };
+    if (result !== 'skipped') { updatedFiles[key] = { kitHash }; entries[key] = { kitHash }; }
     keys.push(key);
   }
 
@@ -153,5 +180,5 @@ export async function initGlobalHooks({ force = false, hooks = null, _globalFile
       updatedAt: new Date().toISOString(),
     });
   }
-  return keys;
+  return { keys, entries };
 }

package/src/commands/init.js

@@ -14,6 +14,7 @@ import {
   setPermissions, fillTemplate,
   verifySettingsJson, COMPONENTS,
   getTemplateDir, installSkillForAgent, installAgentHooks, installAgentRules, resolveSkills, skillAllowed,
+  pruneOrphans,
 } from '../lib/installer.js';
 import { resolveHooks } from '../lib/hooks.js';
 import { AGENTS, parseSkillPath, resolveAgents } from '../lib/agents.js';
@@ -190,6 +191,14 @@ export async function initCommand(path, opts) {
     } catch { /* prior agent's file not on disk — don't record a phantom */ }
   }
 
+  // Migration: drop predecessor files a prior manifest tracked but we no longer
+  // install (mf-* / ap-* skills, renamed hooks) so an install over an old version
+  // doesn't leave orphaned /mf-* commands beside the new /sp-* ones.
+  if (prior?.files) {
+    const n = await pruneOrphans(targetDir, prior.files, new Set(Object.keys(manifest.files)));
+    if (n) log.info(`Migrated: removed ${n} superseded file(s) from a previous version.`);
+  }
+
   // --- Permissions ---
   await setPermissions(targetDir);
 

package/src/lib/claude-global.js

@@ -36,6 +36,9 @@ export async function installHookGlobal(srcRel, globalHooksDir, { force = false,
         log.same(`~/.claude/hooks/${base} (identical)`);
         return { result: 'identical', kitHash: srcHash };
       }
+      // Overwrite only when the on-disk file is one WE wrote (matches the kit hash
+      // recorded in the manifest) — i.e. a stale specpipe version, safe to update.
+      // Otherwise the user changed it (or we never tracked it) → preserve.
       const savedKitHash = globalFiles[key]?.kitHash;
       if (!(savedKitHash && dstHash === savedKitHash)) {
         log.skip(`~/.claude/hooks/${base} (customized — use --force to overwrite)`);
@@ -141,6 +144,8 @@ export async function installSkillGlobalForAgent(agentId, skillRelPath, { force
         log.same(`${display} (identical)`);
         return { result: 'identical', kitHash: srcHash, key };
       }
+      // Overwrite only a stale version we wrote (disk matches the recorded kit hash);
+      // otherwise the user customized it (or it's untracked) → preserve.
       const savedKitHash = globalFiles[key]?.kitHash;
       if (!(savedKitHash && dstHash === savedKitHash)) {
         log.skip(`${display} (customized — use --force to overwrite)`);

package/src/lib/installer.js

@@ -1,4 +1,4 @@
-import { copyFile as fsCopyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { copyFile as fsCopyFile, mkdir, readFile, writeFile, unlink, rmdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -150,6 +150,36 @@ export async function installFile(relativePath, targetDir, { force = false } = {
   return 'copied';
 }
 
+/**
+ * Migration prune: delete files a PRIOR manifest tracked that the new install no
+ * longer wants — e.g. the predecessor `mf-*` (claude-devkit) / `ap-*` (agentpipe)
+ * skills, or renamed/removed hooks. Safe because it only touches paths the kit
+ * itself recorded as installed; a user's own files (e.g. a personal `mf-commit`
+ * skill that was never in our manifest) are never in `priorFiles`, so untouched.
+ * Skips preserved paths and the user's docs/. Cleans up emptied dirs.
+ * @returns {Promise<number>} count pruned
+ */
+export async function pruneOrphans(targetDir, priorFiles, keepSet, { preserve = ['.claude/CLAUDE.md'] } = {}) {
+  let pruned = 0;
+  const dirs = new Set();
+  for (const rel of Object.keys(priorFiles || {})) {
+    if (keepSet.has(rel) || preserve.includes(rel) || rel.startsWith('docs/')) continue;
+    const p = join(targetDir, rel);
+    if (!existsSync(p)) continue;
+    try {
+      await unlink(p);
+      log.del(`${rel} (legacy — superseded, removed)`);
+      pruned++;
+      let d = dirname(rel);
+      while (d && d !== '.' && d !== '/') { dirs.add(d); d = dirname(d); }
+    } catch { /* ignore */ }
+  }
+  for (const d of [...dirs].sort((a, b) => b.split('/').length - a.split('/').length)) {
+    try { await rmdir(join(targetDir, d)); } catch { /* not empty / missing */ }
+  }
+  return pruned;
+}
+
 // Per-agent install (emit skills + guardrails) lives in agent-install.js;
 // re-exported here so callers keep importing from installer.js.
 export {