claude-devkit-cli 1.4.1 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-devkit-cli",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "CLI toolkit for spec-first development with Claude Code — hooks, commands, guards, and test runners",
   "bin": {
     "claude-devkit": "./bin/devkit.js",

package/src/commands/init.js

@@ -37,15 +37,20 @@ export async function initGlobal({ force = false, hooks = false } = {}) {
   const globalSkillsDir = getGlobalSkillsDir();
   await mkdir(globalSkillsDir, { recursive: true });
 
+  const existing = await readGlobalManifest() || {};
+  const globalFiles = existing.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Installing global skills ---');
 
   let copied = 0; let skipped = 0; let identical = 0;
   for (const relPath of COMPONENTS.skills) {
-    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   const parts = [`${copied} copied`];
@@ -55,32 +60,36 @@ export async function initGlobal({ force = false, hooks = false } = {}) {
   log.info('Skills available in all projects via ~/.claude/skills/');
 
   if (hooks) {
-    await initGlobalHooks({ force });
+    await initGlobalHooks({ force, _globalFiles: updatedFiles, _skipManifestWrite: true });
   }
 
-  // Write global manifest
-  const existing = await readGlobalManifest() || {};
   await writeGlobalManifest({
     ...existing,
     globalInstalled: true,
     globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    files: updatedFiles,
     updatedAt: new Date().toISOString(),
   });
 }
 
-export async function initGlobalHooks({ force = false } = {}) {
+export async function initGlobalHooks({ force = false, _globalFiles, _skipManifestWrite = false } = {}) {
   const globalHooksDir = getGlobalHooksDir();
   await mkdir(globalHooksDir, { recursive: true });
 
+  const existing = _skipManifestWrite ? null : (await readGlobalManifest() || {});
+  const globalFiles = _globalFiles || existing?.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Installing global hooks ---');
 
   let copied = 0; let skipped = 0; let identical = 0;
   for (const relPath of COMPONENTS.hooks) {
-    const result = await installHookGlobal(relPath, globalHooksDir, { force });
+    const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   await mergeGlobalSettings(globalHooksDir);
@@ -90,6 +99,15 @@ export async function initGlobalHooks({ force = false } = {}) {
   if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
   log.pass(`Global hooks: ${parts.join(', ')}`);
   log.info('Hooks registered in ~/.claude/settings.json — active in all projects');
+
+  if (!_skipManifestWrite) {
+    await writeGlobalManifest({
+      ...existing,
+      globalHooksInstalled: true,
+      files: updatedFiles,
+      updatedAt: new Date().toISOString(),
+    });
+  }
 }
 
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/commands/upgrade.js

@@ -23,23 +23,26 @@ export async function upgradeGlobal({ force = false } = {}) {
   const globalSkillsDir = getGlobalSkillsDir();
   await mkdir(globalSkillsDir, { recursive: true });
 
+  const meta = await readGlobalManifest() || {};
+  const globalFiles = meta.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Upgrading global skills ---');
   let updated = 0; let skipped = 0; let identical = 0;
 
   for (const relPath of COMPONENTS.skills) {
-    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
     if (result === 'copied') updated++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   let skillParts = [`${updated} updated`, `${identical} unchanged`];
   if (skipped > 0) skillParts.push(`${skipped} customized (use --force to overwrite)`);
   log.pass(`Global skills: ${skillParts.join(', ')}`);
 
-  const meta = await readGlobalManifest() || {};
-
   // Upgrade hooks if previously installed globally
   if (meta.globalHooksInstalled) {
     const globalHooksDir = getGlobalHooksDir();
@@ -50,10 +53,11 @@ export async function upgradeGlobal({ force = false } = {}) {
     let hUpdated = 0; let hSkipped = 0; let hIdentical = 0;
 
     for (const relPath of COMPONENTS.hooks) {
-      const result = await installHookGlobal(relPath, globalHooksDir, { force });
+      const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
       if (result === 'copied') hUpdated++;
       else if (result === 'identical') hIdentical++;
       else hSkipped++;
+      if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
     }
 
     await mergeGlobalSettings(globalHooksDir);
@@ -63,7 +67,7 @@ export async function upgradeGlobal({ force = false } = {}) {
     log.pass(`Global hooks: ${hookParts.join(', ')}`);
   }
 
-  await writeGlobalManifest({ ...meta, globalInstalled: true, updatedAt: new Date().toISOString() });
+  await writeGlobalManifest({ ...meta, globalInstalled: true, files: updatedFiles, updatedAt: new Date().toISOString() });
 
   // Warn about per-project skills that shadow global
   const projects = meta.projects || [];

package/src/lib/installer.js

@@ -203,24 +203,31 @@ export function getGlobalHooksDir() {
  * Copy a hook to the global ~/.claude/hooks/ directory.
  * Strips the '.claude/hooks/' prefix so path-guard.sh lands at
  * ~/.claude/hooks/path-guard.sh.
- * @returns {string} 'copied' | 'skipped' | 'identical'
+ * @param {object} [opts.globalFiles] - files section from global manifest, used to detect true customization
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false } = {}) {
+export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false, globalFiles = {} } = {}) {
   const stripped = hookRelPath.replace(/^\.claude\/hooks\//, '');
   const src = join(getTemplateDir(), hookRelPath);
   const dst = join(globalHooksDir, stripped);
 
+  const { hashFile } = await import('./hasher.js');
+  const srcHash = await hashFile(src);
+
   if (existsSync(dst) && !force) {
     try {
-      const { hashFile } = await import('./hasher.js');
-      const srcHash = await hashFile(src);
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
         log.same(`~/.claude/hooks/${stripped} (identical)`);
-        return 'identical';
+        return { result: 'identical', kitHash: srcHash };
+      }
+      const savedKitHash = globalFiles[hookRelPath]?.kitHash;
+      if (savedKitHash && dstHash === savedKitHash) {
+        // fall through to copy
+      } else {
+        log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash };
       }
-      log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
-      return 'skipped';
     } catch { /* hash failed */ }
   }
 
@@ -228,7 +235,7 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
   await fsCopyFile(src, dst);
   await chmod(dst, 0o755);
   log.copy(`~/.claude/hooks/${stripped}`);
-  return 'copied';
+  return { result: 'copied', kitHash: srcHash };
 }
 
 /**
@@ -331,29 +338,38 @@ export async function removeGlobalHooksFromSettings() {
  * Copy a skill to the global ~/.claude/skills/ directory.
  * Strips the '.claude/skills/' prefix so mf-plan/SKILL.md lands at
  * ~/.claude/skills/mf-plan/SKILL.md.
- * @returns {string} 'copied' | 'skipped' | 'identical'
+ * @param {object} [opts.globalFiles] - files section from global manifest, used to detect true customization
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false } = {}) {
+export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false, globalFiles = {} } = {}) {
   const stripped = skillRelPath.replace(/^\.claude\/skills\//, '');
   const src = join(getTemplateDir(), skillRelPath);
   const dst = join(globalSkillsDir, stripped);
 
+  const { hashFile } = await import('./hasher.js');
+  const srcHash = await hashFile(src);
+
   if (existsSync(dst) && !force) {
     try {
-      const { hashFile } = await import('./hasher.js');
-      const srcHash = await hashFile(src);
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
         log.same(`~/.claude/skills/${stripped} (identical)`);
-        return 'identical';
+        return { result: 'identical', kitHash: srcHash };
+      }
+      // If the installed file still matches the kitHash we saved at last install,
+      // the user hasn't touched it — the kit just changed. Safe to update.
+      const savedKitHash = globalFiles[skillRelPath]?.kitHash;
+      if (savedKitHash && dstHash === savedKitHash) {
+        // fall through to copy
+      } else {
+        log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash };
       }
-      log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
-      return 'skipped';
     } catch { /* hash failed, treat as conflict */ }
   }
 
   await mkdir(dirname(dst), { recursive: true });
   await fsCopyFile(src, dst);
   log.copy(`~/.claude/skills/${stripped}`);
-  return 'copied';
+  return { result: 'copied', kitHash: srcHash };
 }