claude-git-hooks 2.66.1 → 2.68.0

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/lib/utils/config-registry.js

@@ -70,6 +70,7 @@ const SECTION_REMOTE_MAP = {
     analysis: _settingsEntry('analysis'),
     commitMessage: _settingsEntry('commitMessage'),
     judge: _settingsEntry('judge'),
+    skillRegistry: _settingsEntry('skillRegistry'),
     orchestrator: _settingsEntry('orchestrator'),
     prMetadata: _settingsEntry('prMetadata'),
     linting: _settingsEntry('linting')

package/lib/utils/library-resolver.js

@@ -0,0 +1,50 @@
+/**
+ * File: library-resolver.js
+ * Purpose: Resolve the Library (`.library/`) of the repository that claude-hooks
+ *          is currently running in — never the bundled tool's own copy.
+ *
+ * Why: claude-git-hooks is a tool. When installed (globally or as a dependency)
+ * it intentionally ships WITHOUT a `.library/` (see package.json `files`). The
+ * Library that the pipeline maintains always belongs to the repo under work —
+ * e.g. running `create-pr` inside `mscope-transactions` maintains that repo's
+ * docs. The only time it touches git-hooks' own Library is when dog-fooding
+ * (editing git-hooks itself), in which case the working repo IS git-hooks.
+ *
+ * Consumers must therefore resolve `.library/` from the working repo root, not
+ * relative to their own (package) location. This module centralizes that.
+ *
+ * Cross-platform: getRepoRoot() returns a git path (`/mnt/c/...` under WSL/Linux,
+ * `C:/...` under native Windows). `path.join` + `pathToFileURL` produce a valid
+ * `file://` URL for the current runtime, so `import()` of an absolute path works
+ * everywhere (a bare `import('C:\\...')` is invalid on Windows).
+ *
+ * Dependencies:
+ * - git-operations: getRepoRoot() — the single source of truth for the repo root
+ */
+
+import { existsSync } from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Build a file:// URL for a module inside the current repo's `.library/`,
+ * suitable for dynamic `import()`.
+ *
+ * @param {string} subpath - Path inside `.library/` (e.g. 'librarian/index.js')
+ * @returns {string} A `file://` URL string
+ */
+export function libraryModuleUrl(subpath) {
+    return pathToFileURL(path.join(getRepoRoot(), '.library', subpath)).href;
+}
+
+/**
+ * Whether the current repo has its own Library to maintain.
+ * Cheap pre-check so consumers can skip the pipeline cleanly (no scary warning)
+ * in repos that simply have no `.library/`.
+ *
+ * @returns {boolean} True when `.library/resolver.yaml` exists in the repo root
+ */
+export function hasLibrary() {
+    return existsSync(path.join(getRepoRoot(), '.library', 'resolver.yaml'));
+}

package/lib/utils/prompt-builder.js

@@ -194,6 +194,8 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * @param {Object} options.metadata - Additional metadata (repo name, branch, etc.)
  * @param {string|null} options.commonContext - Shared commit overview injected before file diffs (optional)
  * @param {string|null} options.batchRationale - Orchestrator's rationale for this batch (optional)
+ * @param {string|null} options.catalogueSection - Rendered platform antipattern catalogue (optional;
+ *                      callers obtain it via skill-registry getCatalogueSection())
  * @returns {Promise<string>} Complete analysis prompt
  *
  * File data object structure:
@@ -211,6 +213,7 @@ const buildAnalysisPrompt = async ({
     metadata = {},
     commonContext = null,
     batchRationale = null,
+    catalogueSection = null,
     baseDir = '.claude/prompts'
 } = {}) => {
     logger.debug('prompt-builder - buildAnalysisPrompt', 'Building analysis prompt', {
@@ -219,6 +222,7 @@ const buildAnalysisPrompt = async ({
         fileCount: files.length,
         hasCommonContext: !!commonContext,
         hasBatchRationale: !!batchRationale,
+        hasCatalogueSection: !!catalogueSection,
         baseDir
     });
 
@@ -247,6 +251,17 @@ const buildAnalysisPrompt = async ({
         prompt += '\n\n=== EVALUATION GUIDELINES ===\n';
         prompt += guidelines;
 
+        // Add the mscope platform antipattern catalogue if the caller supplied
+        // one (rendered via skill-registry getCatalogueSection()). The catalogue
+        // lists every JBE-NNN / UIK-NNN / etc. rule with severity; Claude is
+        // instructed to populate details[].rule with the catalogue ID when a
+        // finding matches. Unmatched findings (rule unset) become skill-gap
+        // candidates downstream.
+        if (catalogueSection) {
+            prompt += '\n\n=== PLATFORM ANTIPATTERN CATALOGUE ===\n';
+            prompt += catalogueSection;
+        }
+
         // Add changes section
         prompt += '\n\n=== CHANGES TO REVIEW ===\n';
 

package/lib/utils/skill-registry/catalogue.js

@@ -0,0 +1,74 @@
+/**
+ * File: skill-registry/catalogue.js
+ * Purpose: Render the parsed JBE/UIK rule index as a compact catalogue
+ *          string suitable for injection into Claude's analysis prompt.
+ *
+ * Why this exists (Option E2): when Claude analyses code, we want it to
+ * label findings with the canonical rule ID (e.g. `JBE-001`) directly,
+ * rather than relying on fuzzy post-processing to guess. We do this by
+ * injecting a compact catalogue into the analysis prompt — one line per
+ * rule, grouped by scope, ~80 chars per line. The prompt's existing
+ * `details[].rule` field (already declared "optional" in the schema)
+ * becomes load-bearing: populated = covered; empty = skill-gap candidate.
+ *
+ * Token budget: ~95 rules × ~80 chars = ~7.6 KB → ~1,900 tokens added to
+ * each analysis prompt. Negligible against the 200k context window.
+ *
+ * Why a separate module: keeps catalogue formatting decisions (one-line
+ * vs full, severity tags, scope grouping) in one place where they can be
+ * tuned without touching prompt-builder or pre-commit.
+ */
+
+/**
+ * Render the rule catalogue as a compact string for prompt injection.
+ * @param {Array<object>} rules - From parser.loadRegistry().rules
+ * @returns {string} catalogue text (empty string if no rules)
+ */
+export function renderCatalogue(rules) {
+    if (!rules || rules.length === 0) return '';
+
+    const byScope = {};
+    for (const r of rules) {
+        (byScope[r.scope] ||= []).push(r);
+    }
+
+    const lines = [];
+    lines.push('Each finding MUST be classified against the platform antipattern catalogue below.');
+    lines.push('When a finding matches a catalogue entry, populate `details[].rule` with the rule ID');
+    lines.push('(e.g. "JBE-001"). Findings that don\'t match any entry leave `rule` empty — those');
+    lines.push('are candidate skill-gaps the team will review separately.');
+    lines.push('');
+
+    const SCOPE_LABELS = {
+        backend: 'BACKEND (Java / Spring Boot / JPA / SQL Server) — applies to .java and .sql files',
+        frontend: 'FRONTEND (React / @mscope/uikit / RHF / TanStack Query) — applies to .jsx/.tsx/.js/.css',
+    };
+
+    for (const scope of ['backend', 'frontend']) {
+        const list = byScope[scope];
+        if (!list || list.length === 0) continue;
+        lines.push(SCOPE_LABELS[scope] || scope.toUpperCase());
+
+        // Sort: id ascending (group prefix together: JBE-001..JBE-NNN, UIK-001..)
+        list.sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+
+        for (const r of list) {
+            const sevTag = (`[${  r.severity || 'unknown'  }]`).padEnd(11);
+            const title = (r.title || '').replace(/`/g, '').slice(0, 110);
+            lines.push(`  ${r.id.padEnd(9)} ${sevTag} ${title}`);
+        }
+        lines.push('');
+    }
+
+    lines.push('SEVERITY → JSON mapping:');
+    lines.push('  critical → BLOCKER  (commit blocked)');
+    lines.push('  high     → CRITICAL (commit blocked)');
+    lines.push('  medium   → MAJOR    (warn)');
+    lines.push('  low      → MINOR    (warn)');
+    lines.push('');
+    lines.push('When you flag a finding, the catalogue entry\'s severity tells you the MIN severity');
+    lines.push('to assign — don\'t downgrade. You may upgrade if context warrants (e.g. a JBE-001');
+    lines.push('printStackTrace inside a financial calculation path is BLOCKER, not CRITICAL).');
+
+    return lines.join('\n');
+}

package/lib/utils/skill-registry/feedback-writer.js

@@ -0,0 +1,196 @@
+/**
+ * File: skill-registry/feedback-writer.js
+ * Purpose: Option E (bidirectional feedback loop) — take the AI analysis
+ *          findings AFTER Claude returns them and, for each finding the
+ *          AI couldn't classify against the catalogue, append a candidate
+ *          [skill-gap] entry to the appropriate skill's skill-feedback.md.
+ *
+ * How it works (depends on Option E2's catalogue injection in prompt-builder):
+ *   - Claude's analysis prompt now contains the rule catalogue.
+ *   - For each finding, Claude populates `details[].rule` with the matching
+ *     JBE-NNN / UIK-NNN ID — or leaves it empty if nothing matched.
+ *   - We treat empty `rule` as "AI saw something real but couldn't tag it"
+ *     — i.e. the registry has a gap. Those are valuable signal for the
+ *     `automation-skills retro` loop.
+ *
+ * Per the maintainer's `feedback_skill_improvements_user_approval` rule,
+ * we never auto-merge into improvement-registry.md or promote candidates
+ * to rules. We write them to skill-feedback.md as candidates only; the
+ * user reviews and approves via `automation-skills retro` later.
+ *
+ * Dedup: we skip writing if an entry with the same (scope, file, message-hash)
+ * already exists in skill-feedback.md. Prevents the same recurring AI
+ * finding from spamming the doc on every commit.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, extname } from 'path';
+import { createHash } from 'crypto';
+import { SCOPE_BY_EXT } from './parser.js';
+
+const SKILL_PATHS = {
+    backend: 'skills/backend/automation-standards-backend/docs/skill-feedback.md',
+    frontend: 'skills/frontend/automation-standards/docs/skill-feedback.md',
+};
+
+/**
+ * Process the AI's analysis details, write skill-gap candidates as needed.
+ *
+ * @param {object} aiResult - The `result` returned by analysis-engine.runAnalysis
+ *                            (shape: { issues, details: [{file, line, message, severity, rule, type}], ... })
+ * @param {object} context - { skillRoot, branch, repoName }
+ * @returns {{ written: number, skippedDuplicate: number, skippedClassified: number,
+ *             candidatesByScope: { backend?: Array, frontend?: Array } }}
+ */
+export function writeSkillGapCandidates(aiResult, context) {
+    const { skillRoot, branch, repoName } = context;
+    if (!skillRoot) return emptyResult();
+    if (!aiResult || !Array.isArray(aiResult.details)) return emptyResult();
+
+    // Bucket unclassified details by scope.
+    const byScope = { backend: [], frontend: [] };
+    for (const d of aiResult.details) {
+        if (d.rule && /^[A-Z]+-\d{3}$/.test(d.rule)) continue; // already classified
+        if (!d.file || !d.message) continue;                   // can't dedup without these
+        const ext = extname(String(d.file)).toLowerCase();
+        const scope = SCOPE_BY_EXT[ext];
+        if (!scope) continue;                                  // unknown scope, ignore
+        byScope[scope].push(d);
+    }
+
+    const date = today();
+    let written = 0;
+    let skippedDuplicate = 0;
+    let skippedClassified = 0;
+    const candidatesByScope = {};
+
+    // Count classified for the stats output.
+    for (const d of aiResult.details) {
+        if (d.rule && /^[A-Z]+-\d{3}$/.test(d.rule)) skippedClassified++;
+    }
+
+    for (const scope of ['backend', 'frontend']) {
+        const candidates = byScope[scope];
+        if (candidates.length === 0) continue;
+
+        const filePath = join(skillRoot, SKILL_PATHS[scope]);
+        if (!existsSync(filePath)) continue;
+
+        const existing = readFileSync(filePath, 'utf8');
+        const existingHashes = extractExistingHashes(existing);
+
+        const toWrite = [];
+        for (const detail of candidates) {
+            const fp = fingerprint(scope, detail);
+            if (existingHashes.has(fp)) {
+                skippedDuplicate++;
+                continue;
+            }
+            toWrite.push({ detail, fingerprint: fp });
+        }
+
+        if (toWrite.length === 0) continue;
+
+        const entry = composeEntry({
+            date, scope, repoName, branch, candidates: toWrite,
+        });
+
+        appendToFeedback(filePath, entry);
+        written += toWrite.length;
+        candidatesByScope[scope] = toWrite.map((x) => x.detail);
+    }
+
+    return { written, skippedDuplicate, skippedClassified, candidatesByScope };
+}
+
+/**
+ * Fingerprint a detail so repeat reports on the same file/message don't
+ * pile up entries across commits. (scope, file, hash(message-normalised))
+ */
+function fingerprint(scope, detail) {
+    const msg = String(detail.message || '').toLowerCase().replace(/\s+/g, ' ').trim();
+    const file = String(detail.file || '').replace(/\\/g, '/');
+    const hash = createHash('sha1').update(msg).digest('hex').slice(0, 12);
+    return `${scope}::${file}::${hash}`;
+}
+
+/**
+ * Walk the existing skill-feedback.md and collect fingerprints of entries
+ * already present (we embed the fingerprint as an HTML comment so the
+ * dedup is durable even after the file is hand-edited).
+ */
+function extractExistingHashes(content) {
+    const set = new Set();
+    const re = /<!--\s*skill-gap-fp:\s*([^\s>]+)\s*-->/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        set.add(m[1]);
+    }
+    return set;
+}
+
+/**
+ * Compose a single dated entry covering N candidates from the same scope
+ * + branch + commit. Each candidate becomes one bullet.
+ */
+function composeEntry({ date, scope, repoName, branch, candidates }) {
+    const title = '[skill-gap candidates from claude-git-hooks AI analysis]';
+    const ctx = [
+        repoName ? `**Repo:** ${repoName}` : null,
+        branch ? `**Branch:** ${branch}` : null,
+    ].filter(Boolean).join('\n');
+
+    const bullets = candidates.map(({ detail, fingerprint: fp }) => {
+        const file = String(detail.file).replace(/\\/g, '/');
+        const line = detail.line ? `:${detail.line}` : '';
+        const sev = detail.severity ? ` (${detail.severity})` : '';
+        const type = detail.type ? ` [${detail.type}]` : '';
+        const msg = String(detail.message).replace(/\n/g, ' ').slice(0, 300);
+        return `- **[skill-gap]** ${file}${line}${type}${sev} — ${msg} <!-- skill-gap-fp: ${fp} -->`;
+    }).join('\n');
+
+    return `### ${date} — ${title} (${scope})
+
+${ctx}
+
+**Source:** Claude AI analysis flagged these findings, but none matched a JBE/UIK rule in the catalogue. They're recorded here for review during the next \`automation-skills retro\`. If a recurring pattern emerges, file a new registry entry.
+
+**Candidates:**
+
+${bullets}
+
+`;
+}
+
+/**
+ * Append the entry to skill-feedback.md, after the "How to recognize a
+ * skill-caused issue" section and any existing dated entries, but before
+ * "How this compounds" (the footer).
+ */
+function appendToFeedback(filePath, entry) {
+    let content = readFileSync(filePath, 'utf8');
+
+    // Replace the placeholder "(none yet — …)" line if present; otherwise
+    // insert before "## How this compounds".
+    const placeholder = /_\(none yet — the first entry will be appended below\.\)_\n/;
+    if (placeholder.test(content)) {
+        content = content.replace(placeholder, `${entry.trimEnd()  }\n`);
+    } else {
+        const footer = '## How this compounds';
+        const idx = content.indexOf(footer);
+        if (idx === -1) {
+            content = `${content.trimEnd()  }\n\n${  entry}`;
+        } else {
+            content = `${content.slice(0, idx).trimEnd()  }\n\n${  entry  }---\n\n${  content.slice(idx)}`;
+        }
+    }
+    writeFileSync(filePath, content, 'utf8');
+}
+
+function emptyResult() {
+    return { written: 0, skippedDuplicate: 0, skippedClassified: 0, candidatesByScope: {} };
+}
+
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}