claude-git-hooks 2.67.3 → 2.68.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.68.0] - 2026-06-12
+
+### ✨ Added
+- Silent, throttled pre-command auto-update guard that checks for newer versions before running commands and self-updates automatically (#196)
+- New `autoUpdate` configuration section with `enabled` (default: true) and `intervalHours` (default: 24) settings to control automatic update behavior
+- Centralized `lib/utils/auto-update.js` module providing shared update logic (`getUpdateStatus`, `performUpdate`, `shouldAutoCheck`, `maybeAutoUpdate`) for all update paths
+
+### 🔧 Changed
+- Refactored `update` command into a thin wrapper over the shared auto-update module, eliminating duplicated version-check and npm-install logic
+- Refactored install-time update prompt to use shared `getUpdateStatus()` and `performUpdate()` instead of inline implementation
+- Auto-update is fully fail-open and skipped in `--headless` mode — never blocks the real command on failure
+- Excluded fast/offline commands (`update`, `install`, `uninstall`, `help`, `version`, `migrate-config`) from the pre-command auto-update check to avoid recursion and unnecessary latency
+
+### 🐛 Fixed
+- Fixed install-time update prompt incorrectly offering to "update" dev builds that are ahead of the latest published npm version
+
+### 🗑️ Removed
+- Removed `check-version.sh` template installation from the install command (replaced by the integrated auto-update guard)
+- Removed inline `npm install -g` and `runInstall(['--force'])` calls from `update.js` and `install.js` in favor of centralized `performUpdate()`
+
+
 ## [2.67.3] - 2026-06-12
 
 ### ✨ Added

package/bin/claude-hooks

@@ -131,6 +131,25 @@ async function main() {
         logger.debug('bin - main', 'Authorization guard bypassed (--headless)', { command: entry.name });
     }
 
+    // --- Pre-command auto-update guard (silent, throttled) ---
+    // Single choke-point: every command flows through here, so auto-update is added
+    // once instead of in each command file. Mirrors the authorization guard above.
+    // Fully fail-open — never blocks the real command.
+    if (!isHeadless) {
+        try {
+            const { maybeAutoUpdate } = await import('../lib/utils/auto-update.js');
+            const updated = await maybeAutoUpdate(entry.name);
+            if (updated) {
+                // The running binary was just replaced; user must re-run their command.
+                process.exit(0);
+            }
+        } catch (err) {
+            logger.debug('bin - main', 'Pre-command auto-update skipped (non-fatal)', {
+                error: err.message
+            });
+        }
+    }
+
     // --- Commands with special argument handling ---
 
     // analyze: translate flags to options object

package/lib/commands/install.js

@@ -27,10 +27,9 @@ import {
     getGitHooksPath,
     isWindows,
     getClaudeCommand,
-    getPackageJson,
-    getLatestVersion,
     Entertainment
 } from './helpers.js';
+import { getUpdateStatus, performUpdate } from '../utils/auto-update.js';
 import { runSetupGitHub } from './setup-github.js';
 import { generateCompletionData } from '../cli-metadata.js';
 import { getConfig } from '../config.js';
@@ -41,11 +40,12 @@ import { getConfig } from '../config.js';
  */
 async function checkVersionAndPromptUpdate() {
     try {
-        const currentVersion = getPackageJson().version;
-        const latestVersion = await getLatestVersion('claude-git-hooks');
+        const { currentVersion, latestVersion, isNewer } = await getUpdateStatus();
 
-        if (currentVersion === latestVersion) {
-            return true; // Already updated
+        // isNewer guards against the `===` downgrade bug: a dev build ahead of npm
+        // (current > latest) must NOT prompt to "update" to an older published version.
+        if (!isNewer) {
+            return true; // Already on latest (or a dev build ahead of npm)
         }
 
         console.log('');
@@ -58,13 +58,13 @@ async function checkVersionAndPromptUpdate() {
         });
 
         return new Promise((resolve) => {
-            rl.question('Do you want to update now? (y/n): ', (answer) => {
+            rl.question('Do you want to update now? (y/n): ', async (answer) => {
                 rl.close();
 
                 if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
-                    info('Updating claude-git-hooks...');
                     try {
-                        execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+                        // install is about to run, so skip the hook reinstall here
+                        await performUpdate({ reinstallHooks: false, silent: false });
                         success('Update completed. Please run your command again.');
                         process.exit(0); // Exit so user restarts the process
                     } catch (e) {
@@ -463,16 +463,6 @@ export async function runInstall(args) {
         success(`${hook} installed`);
     });
 
-    // Copy version verification script with LF line endings
-    const checkVersionSource = path.join(templatesPath, 'check-version.sh');
-    const checkVersionDest = path.join(hooksPath, 'check-version.sh');
-
-    if (fs.existsSync(checkVersionSource)) {
-        copyWithLF(checkVersionSource, checkVersionDest);
-        fs.chmodSync(checkVersionDest, '755');
-        success('Version verification script installed');
-    }
-
     // Create .claude directory if it doesn't exist
     const claudeDir = '.claude';
     if (!fs.existsSync(claudeDir)) {

package/lib/commands/update.js

@@ -1,19 +1,13 @@
 /**
  * File: update.js
  * Purpose: Update command - update to the latest version
+ *
+ * Thin wrapper over the shared auto-update logic in lib/utils/auto-update.js.
+ * Runs verbosely (silent: false) — this is a user-initiated update.
  */
 
-import { execSync } from 'child_process';
-import {
-    error,
-    success,
-    info,
-    warning,
-    getPackageJson,
-    getLatestVersion,
-    compareVersions
-} from './helpers.js';
-import { runInstall } from './install.js';
+import { error, success, info, warning } from './helpers.js';
+import { getUpdateStatus, performUpdate } from '../utils/auto-update.js';
 
 /**
  * Update command - update to the latest version
@@ -22,33 +16,26 @@ export async function runUpdate() {
     info('Checking latest available version...');
 
     try {
-        const currentVersion = getPackageJson().version;
-        const latestVersion = await getLatestVersion('claude-git-hooks');
+        const { currentVersion, latestVersion, isNewer, isDev } = await getUpdateStatus();
 
-        const comparison = compareVersions(currentVersion, latestVersion);
-
-        if (comparison === 0) {
-            success(`You already have the latest version installed (${currentVersion})`);
-            return;
-        } else if (comparison > 0) {
+        if (isDev) {
             info(`You are using a development version (${currentVersion})`);
             info(`Latest published version: ${latestVersion}`);
             success(`You already have the latest version installed (${currentVersion})`);
             return;
         }
 
+        if (!isNewer) {
+            success(`You already have the latest version installed (${currentVersion})`);
+            return;
+        }
+
         info(`Current version: ${currentVersion}`);
         info(`Available version: ${latestVersion}`);
 
-        // Update the package
-        info('Updating claude-git-hooks...');
         try {
-            execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+            await performUpdate({ reinstallHooks: true, silent: false });
             success(`Successfully updated to version ${latestVersion}`);
-
-            // Reinstall hooks with the new version
-            info('Reinstalling hooks with the new version...');
-            await runInstall(['--force']);
         } catch (updateError) {
             error('Error updating. Try running: npm install -g claude-git-hooks@latest');
         }
@@ -56,9 +43,8 @@ export async function runUpdate() {
         warning('Could not check the latest available version');
         warning('Trying to update anyway...');
         try {
-            execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+            await performUpdate({ reinstallHooks: true, silent: false });
             success('Update completed');
-            await runInstall(['--force']);
         } catch (updateError) {
             error(`Error updating: ${updateError.message}`);
         }

package/lib/defaults.json

@@ -33,6 +33,10 @@
         "debug": false,
         "wslCheckTimeout": 15000
     },
+    "autoUpdate": {
+        "enabled": true,
+        "intervalHours": 24
+    },
     "git": {
         "diffFilter": "ACM"
     },

package/lib/utils/auto-update.js

@@ -0,0 +1,198 @@
+/**
+ * File: auto-update.js
+ * Purpose: Centralized self-update logic shared by the manual `update` command,
+ *          the install-time prompt, and the pre-command guard in bin/claude-hooks.
+ *
+ * Single source of truth for: resolving current-vs-latest version, performing the
+ * `npm install -g` update + hook reinstall, throttling automatic checks, and the
+ * silent pre-command auto-update guard.
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import {
+    info,
+    warning,
+    success,
+    getPackageJson,
+    getLatestVersion,
+    compareVersions
+} from '../commands/helpers.js';
+import { getRepoRoot } from './git-operations.js';
+import { getConfig } from '../config.js';
+import logger from './logger.js';
+
+const PACKAGE_NAME = 'claude-git-hooks';
+const CHECK_FILE = '.last-update-check';
+const DEFAULT_INTERVAL_HOURS = 24;
+
+// Commands that must NOT trigger the pre-command auto-update guard.
+// Why: avoids recursion (update → install --force), and skips fast/offline
+// commands where a network round-trip would only add latency.
+const EXCLUDED_COMMANDS = new Set([
+    'update',
+    'install',
+    'uninstall',
+    'help',
+    'version',
+    'migrate-config'
+]);
+
+/**
+ * Resolve current vs latest version and derived flags.
+ * @returns {Promise<{currentVersion:string, latestVersion:string, comparison:number, isNewer:boolean, isDev:boolean}>}
+ */
+export async function getUpdateStatus() {
+    const currentVersion = getPackageJson().version;
+    const latestVersion = await getLatestVersion(PACKAGE_NAME);
+    const comparison = compareVersions(currentVersion, latestVersion);
+
+    return {
+        currentVersion,
+        latestVersion,
+        comparison,
+        isNewer: comparison < 0,
+        isDev: comparison > 0
+    };
+}
+
+/**
+ * Update the globally-installed package and (optionally) reinstall hooks in the
+ * current repo. Implements the approved flow:
+ *   npm install -g claude-git-hooks@latest
+ *   → locate repo root; if none, warn and stop; else reinstall hooks (--force)
+ *
+ * @param {Object} [opts]
+ * @param {boolean} [opts.reinstallHooks=true] - reinstall hooks at repo root after update
+ * @param {boolean} [opts.silent=false] - suppress sub-process output and progress chatter
+ * @returns {Promise<{updated:boolean, hooksReinstalled:boolean}>}
+ */
+export async function performUpdate({ reinstallHooks = true, silent = false } = {}) {
+    const stdio = silent ? 'ignore' : 'inherit';
+
+    if (!silent) {
+        info('Updating claude-git-hooks...');
+    }
+    execSync(`npm install -g ${PACKAGE_NAME}@latest`, { stdio });
+
+    if (!reinstallHooks) {
+        return { updated: true, hooksReinstalled: false };
+    }
+
+    // Locate the repo root: this is the "look for root" step. getRepoRoot()
+    // throws (GitError) outside a git repo — treat that as "no root → warn & stop".
+    try {
+        const root = getRepoRoot();
+        logger.debug('auto-update - performUpdate', 'Repo root located for hook reinstall', { root });
+    } catch {
+        warning(
+            'Package updated, but you are not inside a git repository — hooks were not reinstalled.\n' +
+                '   cd into your repo and run: claude-hooks install --force'
+        );
+        return { updated: true, hooksReinstalled: false };
+    }
+
+    if (!silent) {
+        info('Reinstalling hooks with the new version...');
+    }
+    // Dynamic import breaks the static cycle (install.js imports this module).
+    const { runInstall } = await import('../commands/install.js');
+    await runInstall(silent ? ['--force', '--headless'] : ['--force']);
+
+    return { updated: true, hooksReinstalled: true };
+}
+
+/**
+ * Whether enough time has elapsed since the last auto-update check.
+ * Throttle state lives in `<repoRoot>/.claude/.last-update-check` (.claude is gitignored).
+ * Fail-open: any FS/parse error returns true (allow the check).
+ *
+ * @param {number} [intervalHours=24]
+ * @returns {boolean}
+ */
+export function shouldAutoCheck(intervalHours = DEFAULT_INTERVAL_HOURS) {
+    try {
+        const file = path.join(getRepoRoot(), '.claude', CHECK_FILE);
+        if (!fs.existsSync(file)) return true;
+
+        const last = Number(fs.readFileSync(file, 'utf8').trim());
+        if (!Number.isFinite(last)) return true;
+
+        const elapsedHours = (Date.now() - last) / (1000 * 60 * 60);
+        return elapsedHours >= intervalHours;
+    } catch {
+        return true;
+    }
+}
+
+/**
+ * Record the current time as the last auto-update check. Best-effort (fail-open).
+ */
+export function recordCheckTimestamp() {
+    try {
+        const dir = path.join(getRepoRoot(), '.claude');
+        if (!fs.existsSync(dir)) return;
+        fs.writeFileSync(path.join(dir, CHECK_FILE), String(Date.now()), 'utf8');
+    } catch {
+        // best effort — throttling is an optimization, not a correctness requirement
+    }
+}
+
+/**
+ * Pre-command auto-update guard. Runs SILENTLY before a command in bin/claude-hooks.
+ * Returns true when an update was performed (the running binary changed, so the
+ * caller should exit and ask the user to re-run their command).
+ *
+ * Fully fail-open: any error is swallowed (debug-logged) and returns false so the
+ * real command always proceeds.
+ *
+ * @param {string} command - the resolved command name (entry.name)
+ * @returns {Promise<boolean>}
+ */
+export async function maybeAutoUpdate(command) {
+    // Defensive recursion guard (in-process runInstall does not re-enter the router,
+    // but this is cheap insurance against any future re-spawn).
+    if (process.env.CLAUDE_HOOKS_UPDATE_IN_PROGRESS) return false;
+    if (EXCLUDED_COMMANDS.has(command)) return false;
+
+    let autoUpdate = { enabled: true, intervalHours: DEFAULT_INTERVAL_HOURS };
+    try {
+        const config = await getConfig();
+        autoUpdate = { ...autoUpdate, ...(config.autoUpdate || {}) };
+    } catch {
+        // Config load failure → use defaults (enabled)
+    }
+    if (autoUpdate.enabled === false) return false;
+
+    // Must be inside a repo: throttle state + hook reinstall target live there.
+    try {
+        getRepoRoot();
+    } catch {
+        return false;
+    }
+
+    if (!shouldAutoCheck(autoUpdate.intervalHours)) return false;
+    // Throttle the next attempt regardless of network outcome (avoids offline spam).
+    recordCheckTimestamp();
+
+    try {
+        process.env.CLAUDE_HOOKS_UPDATE_IN_PROGRESS = '1';
+
+        const status = await getUpdateStatus();
+        if (!status.isNewer) return false;
+
+        await performUpdate({ reinstallHooks: true, silent: true });
+        success(
+            `⬆️  Updated claude-git-hooks to v${status.latestVersion} — please re-run your command.`
+        );
+        return true;
+    } catch (e) {
+        logger.debug('auto-update - maybeAutoUpdate', 'Auto-update check skipped (non-fatal)', {
+            error: e.message
+        });
+        return false;
+    } finally {
+        delete process.env.CLAUDE_HOOKS_UPDATE_IN_PROGRESS;
+    }
+}

package/package.json

@@ -1,84 +1,84 @@
-{
-    "name": "claude-git-hooks",
-    "version": "2.67.3",
-    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
-    "type": "module",
-    "bin": {
-        "claude-hooks": "./bin/claude-hooks"
-    },
-    "scripts": {
-        "test": "npm run test:all",
-        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
-        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
-        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
-        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
-        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-        "test:e2e": "bash test/manual/sdlc-stability-check.sh",
-        "lint": "eslint lib/ bin/claude-hooks .library/librarian/",
-        "lint:fix": "eslint lib/ bin/claude-hooks .library/librarian/ --fix",
-        "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",
-        "precommit": "npm run lint && npm run test:smoke",
-        "prepublishOnly": "npm run test:all",
-        "library:check": "node .library/bin/library check",
-        "library:regenerate": "node .library/bin/library regenerate",
-        "library:extract": "node .library/bin/library extract",
-        "library:tokens": "node .library/bin/library tokens",
-        "library:graph": "node .library/bin/library graph",
-        "library:inject": "node .library/bin/library inject",
-        "library:validate": "node .library/bin/library validate",
-        "library:report": "node .library/bin/library report"
-    },
-    "keywords": [
-        "git",
-        "hooks",
-        "claude",
-        "ai",
-        "code-review",
-        "commit-messages",
-        "pre-commit",
-        "automation"
-    ],
-    "author": "Pablo Rovito",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/mscope-S-L/git-hooks.git"
-    },
-    "engines": {
-        "node": ">=16.9.0"
-    },
-    "engineStrict": false,
-    "os": [
-        "darwin",
-        "linux",
-        "win32"
-    ],
-    "preferGlobal": true,
-    "files": [
-        "bin/",
-        "lib/",
-        "templates/",
-        "README.md",
-        "CHANGELOG.md",
-        "CLAUDE.md",
-        "LICENSE"
-    ],
-    "dependencies": {
-        "@anthropic-ai/sdk": "^0.91.0",
-        "@octokit/rest": "^21.0.0",
-        "langfuse": "^3.38.20"
-    },
-    "devDependencies": {
-        "@types/jest": "^29.5.0",
-        "eslint": "^8.57.1",
-        "jest": "^29.7.0",
-        "js-tiktoken": "^1.0.18",
-        "madge": "^8.0.0",
-        "prettier": "^3.2.0",
-        "tree-sitter-wasms": "^0.1.13",
-        "web-tree-sitter": "^0.24.7"
-    }
-}
+{
+    "name": "claude-git-hooks",
+    "version": "2.68.0",
+    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
+    "type": "module",
+    "bin": {
+        "claude-hooks": "./bin/claude-hooks"
+    },
+    "scripts": {
+        "test": "npm run test:all",
+        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
+        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
+        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
+        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
+        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "test:e2e": "bash test/manual/sdlc-stability-check.sh",
+        "lint": "eslint lib/ bin/claude-hooks .library/librarian/",
+        "lint:fix": "eslint lib/ bin/claude-hooks .library/librarian/ --fix",
+        "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",
+        "precommit": "npm run lint && npm run test:smoke",
+        "prepublishOnly": "npm run test:all",
+        "library:check": "node .library/bin/library check",
+        "library:regenerate": "node .library/bin/library regenerate",
+        "library:extract": "node .library/bin/library extract",
+        "library:tokens": "node .library/bin/library tokens",
+        "library:graph": "node .library/bin/library graph",
+        "library:inject": "node .library/bin/library inject",
+        "library:validate": "node .library/bin/library validate",
+        "library:report": "node .library/bin/library report"
+    },
+    "keywords": [
+        "git",
+        "hooks",
+        "claude",
+        "ai",
+        "code-review",
+        "commit-messages",
+        "pre-commit",
+        "automation"
+    ],
+    "author": "Pablo Rovito",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mscope-S-L/git-hooks.git"
+    },
+    "engines": {
+        "node": ">=16.9.0"
+    },
+    "engineStrict": false,
+    "os": [
+        "darwin",
+        "linux",
+        "win32"
+    ],
+    "preferGlobal": true,
+    "files": [
+        "bin/",
+        "lib/",
+        "templates/",
+        "README.md",
+        "CHANGELOG.md",
+        "CLAUDE.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@anthropic-ai/sdk": "^0.91.0",
+        "@octokit/rest": "^21.0.0",
+        "langfuse": "^3.38.20"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.0",
+        "eslint": "^8.57.1",
+        "jest": "^29.7.0",
+        "js-tiktoken": "^1.0.18",
+        "madge": "^8.0.0",
+        "prettier": "^3.2.0",
+        "tree-sitter-wasms": "^0.1.13",
+        "web-tree-sitter": "^0.24.7"
+    }
+}

package/templates/config.advanced.example.json

@@ -61,6 +61,11 @@
             "failOnError": true,
             "failOnWarning": false,
             "timeout": 30000
+        },
+
+        "autoUpdate": {
+            "enabled": true,
+            "intervalHours": 24
         }
     },
 
@@ -168,6 +173,18 @@
             "description": "Timeout in milliseconds for each linter execution",
             "default": "30000",
             "use_case": "Increase for large projects where linters take longer"
+        },
+
+        "autoUpdate.enabled": {
+            "description": "Enable the silent, throttled pre-command auto-update check. When a newer published version is detected before running a command, claude-git-hooks updates itself globally, reinstalls hooks (--force), and asks you to re-run your command. Excludes update/install/uninstall/help/version/migrate-config, and is skipped in --headless mode. The manual `claude-hooks update` command runs verbosely regardless of this setting.",
+            "default": "true",
+            "use_case": "Set to false to disable automatic background updates and rely only on `claude-hooks update`"
+        },
+
+        "autoUpdate.intervalHours": {
+            "description": "Minimum hours between pre-command auto-update checks. Throttle state is stored in .claude/.last-update-check (gitignored).",
+            "default": "24",
+            "use_case": "Lower it for faster propagation of releases, or raise it to reduce network checks"
         }
     },