claude-git-hooks 2.51.2 → 2.66.1

package/lib/commands/create-release.js

@@ -4,18 +4,21 @@
  *
  * Workflow:
  * 1. Validate preconditions (clean tree, on develop, up-to-date, no existing RC)
- * 2. Discover version files — abort on mismatch
- * 3. Calculate next version
- * 4. [dry-run] Preview + return
- * 5. Confirm with user
- * 6. Create RC branch from develop
- * 7. Bump version files + commit (--no-verify)
- * 8. [optional] Generate CHANGELOG
- * 9. Create Git tag (skip if already exists)
- * 10. Push RC branch (unless --skip-push)
- * 11. Deploy to shadow (unless --no-shadow or --skip-push)
- * 12. Return to RC branch
- * 13. Display summary
+ * 2. Library verification gate (non-blocking)
+ * 3. Discover version files — abort on mismatch
+ * 4. Calculate next version
+ * 5. [dry-run] Preview + return
+ * 6. Confirm with user
+ * 7. Create RC branch from develop
+ * 8. Bump version files
+ * 9. [if stale] Library regeneration (keeps tag accurate)
+ * 10. [optional] Generate CHANGELOG
+ * 11. Stage all + commit (--no-verify)
+ * 12. Create Git tag (skip if already exists)
+ * 13. Push RC branch (unless --skip-push)
+ * 14. Create release PR (unless --skip-push or push failed)
+ * 15. Deploy to shadow (unless --no-shadow or --skip-push)
+ * 16. Return to RC branch + display summary
  */
 
 import { execSync } from 'child_process';
@@ -57,6 +60,12 @@ import {
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { colors, error, checkGitRepo } from './helpers.js';
+import {
+    CONSOLE_WARNING_TEMPLATE,
+    PR_BODY_SECTION_TEMPLATE,
+    PR_TAG_VALUE,
+    LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE
+} from '../messages/library-warnings.js';
 
 /** Source branch for RC creation */
 const SOURCE_BRANCH = 'develop';
@@ -264,6 +273,51 @@ function restoreSnapshot(snapshot) {
     });
 }
 
+/**
+ * Emit a loud Library staleness warning to stderr.
+ * Content comes from the canonical template + verify result data.
+ * Formatting uses ANSI codes for visual emphasis on TTY stderr.
+ *
+ * @param {import('../../.library/librarian/index.js').VerifyResult} result
+ * @private
+ */
+function _emitLibraryWarning(result) {
+    const y = colors.yellow;
+    const r = colors.reset;
+    const bar = `${y}${'='.repeat(63)}${r}`;
+    const content = CONSOLE_WARNING_TEMPLATE(result, { autoRegen: 'will-run' });
+
+    const lines = ['', bar, '', `${y}${content}${r}`, '', bar, ''];
+
+    process.stderr.write(lines.join('\n'));
+}
+
+/** Marker comment pair wrapping the staleness section in PR bodies */
+const STALENESS_MARKER_OPEN = '<!-- LIBRARY_STALENESS_SECTION -->';
+const STALENESS_MARKER_CLOSE = '<!-- /LIBRARY_STALENESS_SECTION -->';
+
+/**
+ * Build the release PR body, optionally appending the staleness section.
+ *
+ * @param {string} nextVersion
+ * @param {import('../../.library/librarian/index.js').VerifyResult|null} verifyResult
+ * @param {'completed'|'failed'|null} regenOutcome - result of auto-regeneration
+ * @returns {string}
+ * @private
+ */
+function _buildReleasePrBody(nextVersion, verifyResult, regenOutcome) {
+    let body = `## Release V${nextVersion}\n\nRelease-candidate branch created from \`${SOURCE_BRANCH}\`.`;
+
+    if (verifyResult && !verifyResult.clean) {
+        const section = PR_BODY_SECTION_TEMPLATE(verifyResult, {
+            autoRegen: regenOutcome || 'failed'
+        });
+        body += `\n\n${STALENESS_MARKER_OPEN}\n${section}\n${STALENESS_MARKER_CLOSE}`;
+    }
+
+    return body;
+}
+
 /**
  * create-release command
  * Creates a release-candidate branch from develop, bumps version, and deploys to shadow.
@@ -318,8 +372,25 @@ export async function runCreateRelease(args) {
     showSuccess('Preconditions validated');
     console.log('');
 
-    // Step 2: Discover version files
-    logger.debug('create-release', 'Step 2: Discovering version files');
+    // Step 2: Library verification gate — silent on clean, loud-warn on stale, never blocks
+    let verifyResult = null;
+    logger.debug('create-release', 'Step 2: Running Library verification gate');
+    try {
+        const { verify } = await import('../../.library/librarian/index.js');
+        verifyResult = await verify();
+
+        if (verifyResult.clean) {
+            logger.debug('create-release', 'Library is clean — no warning needed');
+        } else {
+            _emitLibraryWarning(verifyResult);
+        }
+    } catch (verifyErr) {
+        const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE} ${verifyErr.message}${colors.reset}\n\n`;
+        process.stderr.write(msg);
+    }
+
+    // Step 3: Discover version files
+    logger.debug('create-release', 'Step 3: Discovering version files');
     const discovery = discoverVersionFiles();
 
     if (discovery.files.length === 0) {
@@ -356,7 +427,7 @@ export async function runCreateRelease(args) {
         process.exit(1);
     }
 
-    // Step 3: Calculate next version
+    // Step 4: Calculate next version
     const nextVersion = incrementVersion(currentVersion, options.bumpType);
     const rcBranch = `${RC_PREFIX}/V${nextVersion}`;
     const tagName = formatTagName(nextVersion);
@@ -366,13 +437,13 @@ export async function runCreateRelease(args) {
     showInfo(`Branch:          ${rcBranch}`);
     console.log('');
 
-    // Step 4: Dry-run
+    // Step 5: Dry-run
     if (options.dryRun) {
         showDryRunPreview({ bumpType: options.bumpType, currentVersion, nextVersion, rcBranch, options });
         return;
     }
 
-    // Step 5: Confirm with user
+    // Step 6: Confirm with user
     const confirmed = await promptConfirmation(
         `Create ${rcBranch} and bump version to ${nextVersion}?`,
         true
@@ -388,30 +459,8 @@ export async function runCreateRelease(args) {
         const config = await getConfig();
         const selectedFiles = discovery.files.filter((f) => f.selected);
 
-        // Library staleness gate — block release if books are stale
-        try {
-            showInfo('📚 Checking library staleness...');
-            const { runAll, formatHuman } = await import('../../.library/tools/staleness.js');
-            const { getSourceDir, getBooksDir } = await import('../../.library/paths.js');
-            const { getRepoRoot } = await import('../utils/git-operations.js');
-            const stalenessResult = await runAll(getBooksDir(), getSourceDir(), getRepoRoot(), false);
-            const hasDrift = stalenessResult.stale.length > 0 ||
-                stalenessResult.orphan_books.length > 0 ||
-                stalenessResult.unbooked_sources.length > 0;
-            if (hasDrift) {
-                showError('📚 Library staleness detected — cannot create release with stale books');
-                process.stdout.write(formatHuman(stalenessResult));
-                showError('Run: npm run library:regenerate');
-                process.exit(1);
-            }
-            showSuccess('📚 Library books are current');
-        } catch (err) {
-            showWarning('📚 Library staleness check unavailable — .library/ tools not found');
-            logger.debug('create-release', 'Library staleness check skipped', { error: err.message });
-        }
-
-        // Step 6: Create RC branch from develop
-        logger.debug('create-release', 'Step 6: Creating RC branch', { rcBranch });
+        // Step 7: Create RC branch from develop
+        logger.debug('create-release', 'Step 7: Creating RC branch', { rcBranch });
         showInfo(`Creating branch ${rcBranch} from ${SOURCE_BRANCH}...`);
         checkoutBranch(rcBranch, { create: true, startPoint: SOURCE_BRANCH });
         showSuccess(`✓ Branch created: ${rcBranch}`);
@@ -430,8 +479,8 @@ export async function runCreateRelease(args) {
             }
         });
 
-        // Step 7: Bump version files
-        logger.debug('create-release', 'Step 7: Bumping version files');
+        // Step 8: Bump version files
+        logger.debug('create-release', 'Step 8: Bumping version files');
         showInfo('Updating version files...');
         try {
             updateVersionFiles(selectedFiles, nextVersion);
@@ -455,10 +504,41 @@ export async function runCreateRelease(args) {
             process.exit(1);
         }
 
-        // Step 8: Optional CHANGELOG
+        // Step 9: Library regeneration (if stale — keeps tag accurate)
+        let libraryFiles = [];
+        let regenOutcome = null;
+        if (verifyResult && !verifyResult.clean) {
+            logger.debug('create-release', 'Step 9: Running Library regeneration');
+            showInfo('📚 Regenerating stale Library books...');
+            try {
+                const { createPrPipeline } = await import('../../.library/librarian/index.js');
+                const root = getRepoRoot();
+                const pipelineSummary = await createPrPipeline({ repoRoot: root });
+
+                libraryFiles = pipelineSummary.modifiedFiles.map(
+                    (f) => path.join(root, f)
+                );
+
+                regenOutcome = 'completed';
+                if (libraryFiles.length > 0) {
+                    showSuccess(`✓ Library regenerated (${libraryFiles.length} file(s))`);
+                } else {
+                    showInfo('Library pipeline ran — no files changed');
+                }
+            } catch (regenErr) {
+                regenOutcome = 'failed';
+                showWarning(`Library regeneration failed: ${regenErr.message}`);
+                logger.debug('create-release', 'Library regen failed', {
+                    error: regenErr.message
+                });
+            }
+            process.stdout.write('\n');
+        }
+
+        // Step 10: Optional CHANGELOG
         let selectedChangelogPath = null;
         if (options.updateChangelog) {
-            logger.debug('create-release', 'Step 8: Generating CHANGELOG');
+            logger.debug('create-release', 'Step 10: Generating CHANGELOG');
             showInfo('Generating CHANGELOG entry...');
             const changelogResult = await generateChangelogEntry({
                 version: nextVersion,
@@ -484,6 +564,9 @@ export async function runCreateRelease(args) {
         logger.debug('create-release', 'Staging and committing version bump');
         showInfo('Staging and committing...');
         const filesToStage = selectedFiles.map((f) => f.path);
+        if (libraryFiles.length > 0) {
+            filesToStage.push(...libraryFiles);
+        }
         if (options.updateChangelog) {
             const changelogPath =
                 selectedChangelogPath || path.join(getRepoRoot(), 'CHANGELOG.md');
@@ -518,8 +601,8 @@ export async function runCreateRelease(args) {
         showSuccess('✓ Version bump committed');
         console.log('');
 
-        // Step 9: Create Git tag (skip silently if already exists)
-        logger.debug('create-release', 'Step 9: Creating Git tag', { tagName });
+        // Step 11: Create Git tag (skip silently if already exists)
+        logger.debug('create-release', 'Step 11: Creating Git tag', { tagName });
         const tagAlreadyExists = await tagExists(tagName, 'local');
         if (tagAlreadyExists) {
             showWarning(`Tag ${tagName} already exists locally — skipping tag creation`);
@@ -533,7 +616,7 @@ export async function runCreateRelease(args) {
         }
         console.log('');
 
-        // Step 10: Push RC branch (unless --skip-push)
+        // Step 12: Push RC branch (unless --skip-push)
         let pushStatus = 'skipped (--skip-push)';
         if (!options.skipPush) {
             showInfo(`Pushing ${rcBranch} to remote...`);
@@ -551,7 +634,66 @@ export async function runCreateRelease(args) {
             console.log('');
         }
 
-        // Step 11: Deploy to shadow (unless --no-shadow or --skip-push)
+        // Step 13: Create release PR (unless --skip-push or push failed)
+        let prUrl = null;
+        if (!options.skipPush && pushStatus === 'pushed') {
+            logger.debug('create-release', 'Step 13: Creating release PR');
+            try {
+                const { createPullRequest, validateToken, findExistingPR } =
+                    await import('../utils/github-api.js');
+                const { parseGitHubRepo } = await import('../utils/github-client.js');
+
+                const tokenValidation = await validateToken();
+                if (!tokenValidation.valid) {
+                    showWarning(
+                        `GitHub token invalid — release PR not created: ${tokenValidation.error}`
+                    );
+                    console.log('');
+                    console.log('Create the PR manually:');
+                    console.log(`  gh pr create --base main --head ${rcBranch}`);
+                } else {
+                    const repoInfo = parseGitHubRepo();
+
+                    // Idempotency: skip if PR already exists for this head → main
+                    const existingPR = await findExistingPR({
+                        owner: repoInfo.owner,
+                        repo: repoInfo.repo,
+                        head: rcBranch,
+                        base: 'main'
+                    });
+
+                    if (existingPR) {
+                        showInfo(`Release PR already exists: ${existingPR.html_url}`);
+                        prUrl = existingPR.html_url;
+                    } else {
+                        const prBody = _buildReleasePrBody(nextVersion, verifyResult, regenOutcome);
+                        const labels = verifyResult && !verifyResult.clean
+                            ? [PR_TAG_VALUE]
+                            : [];
+
+                        const pr = await createPullRequest({
+                            owner: repoInfo.owner,
+                            repo: repoInfo.repo,
+                            title: `Release V${nextVersion}`,
+                            body: prBody,
+                            head: rcBranch,
+                            base: 'main',
+                            labels
+                        });
+                        prUrl = pr.html_url;
+                        showSuccess(`✓ Release PR created: ${prUrl}`);
+                    }
+                }
+            } catch (prErr) {
+                showWarning(`Release PR creation failed: ${prErr.message}`);
+                console.log('');
+                console.log('Create the PR manually:');
+                console.log(`  gh pr create --base main --head ${rcBranch}`);
+            }
+            console.log('');
+        }
+
+        // Step 14: Deploy to shadow (unless --no-shadow or --skip-push)
         let shadowStatus = 'skipped';
         if (options.noShadow) {
             showInfo('Shadow deployment skipped (--no-shadow)');
@@ -573,7 +715,7 @@ export async function runCreateRelease(args) {
             }
         }
 
-        // Step 12: Ensure we land on RC branch
+        // Step 15: Ensure we land on RC branch
         const currentBranchAfter = getCurrentBranch();
         if (currentBranchAfter !== rcBranch) {
             try {
@@ -583,7 +725,7 @@ export async function runCreateRelease(args) {
             }
         }
 
-        // Step 13: Summary
+        // Step 16: Summary
         console.log('');
         console.log(
             `${colors.green}════════════════════════════════════════════════════${colors.reset}`
@@ -601,13 +743,17 @@ export async function runCreateRelease(args) {
             `${colors.blue}Tag:${colors.reset}     ${tagAlreadyExists ? `${tagName} (pre-existing, skipped)` : tagName}`
         );
         console.log(`${colors.blue}Push:${colors.reset}    ${pushStatus}`);
+        console.log(
+            `${colors.blue}PR:${colors.reset}      ${prUrl || 'skipped'}`
+        );
         console.log(`${colors.blue}Shadow:${colors.reset}  ${shadowStatus}`);
         console.log('');
 
         if (options.skipPush) {
             console.log('Next steps:');
             console.log(`  1. Push when ready: git push -u origin ${rcBranch}`);
-            console.log(`  2. Sync shadow:     claude-hooks shadow sync ${rcBranch}`);
+            console.log(`  2. Create PR:       gh pr create --base main --head ${rcBranch}`);
+            console.log(`  3. Sync shadow:     claude-hooks shadow sync ${rcBranch}`);
         } else {
             console.log('Next steps:');
             console.log('  1. Verify shadow deployment is running');

package/lib/commands/help.js

@@ -18,8 +18,6 @@ import { fetchFileContent, fetchDirectoryListing, createIssue } from '../utils/g
 import { promptMenu, promptEditField, promptConfirmation } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { commands } from '../cli-metadata.js';
-import { fetchLibraryContent as librarianFetch } from '../../.library/librarian/index.js';
-
 /**
  * Get claude-hooks source repo coordinates from package.json
  * Why: AI help must always fetch from the tool's own repo, not the user's current repo
@@ -192,10 +190,22 @@ const _readPackageFile = async (relativePath) => {
  * Why: The catalog provides navigational context for the AI librarian (Pass 1).
  * Delegates to the librarian module for directory discovery and routing.
  *
+ * Uses dynamic import() because .library/ is not shipped in the npm package —
+ * it only exists in the source repo. When running from a global install,
+ * the import fails gracefully and the help command falls back to static help.
+ *
  * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
  */
 const readLibraryCatalog = async () => {
-    // Fetching delegated to the librarian module; see .library/librarian/
+    let librarianFetch;
+    try {
+        const mod = await import('../../.library/librarian/index.js');
+        librarianFetch = mod.fetchLibraryContent;
+    } catch {
+        logger.debug('help - readLibraryCatalog', 'Library not available (expected in global install)');
+        return null;
+    }
+
     try {
         const result = await librarianFetch(null, { repoRoot: _packageRoot, full: true });
         if (result.catalog) {

package/lib/messages/library-warnings.js

@@ -0,0 +1,147 @@
+/**
+ * File: library-warnings.js
+ * Purpose: Staleness-warning wording and rendering for Library verification
+ *          gates in claude-hooks.
+ *
+ * These are consumer rendering functions — they take structured VerifyResult
+ * data from the Library and produce display-ready text (console) or Markdown
+ * (PR body). The Library produces the data; this module formats it.
+ *
+ * Constraints:
+ *   - Pure functions of (VerifyResult, opts) — no I/O, no globals, no environment
+ *   - Do NOT import from .library/ — lib/ must not depend on unshipped paths
+ *
+ * Related tickets:
+ *   AUT-3767 — original placeholder (retired by AUT-3769)
+ *   AUT-3769 — finalized wording + librarian messages module
+ *   AUT-3770 — create-release integration (PR body, label, console)
+ *   AUT-3738 — parent user story
+ */
+
+/**
+ * Render an assertive console warning for Library staleness.
+ *
+ * Returns plain text with a marker and the list of stale books.
+ * The closing section varies by consumer context via `opts.autoRegen`:
+ *   - `'will-run'`  — create-release: regen runs in the same command
+ *   - `'deferred'`  — bump-version: regen runs later via create-pr
+ *
+ * Consumers apply visual formatting (box, color, stderr routing) on top.
+ *
+ * Returns an empty string when the Library is clean.
+ *
+ * @param {Object} verifyResult
+ * @param {boolean}      verifyResult.clean
+ * @param {Array<{ path: string, reasons: string[] }>} verifyResult.staleBooks
+ * @param {string[]}     verifyResult.recommendedScripts
+ * @param {Object}       opts
+ * @param {'will-run'|'deferred'} opts.autoRegen — controls the call-to-action
+ * @returns {string} Plain-text console warning, or empty string if clean
+ */
+export function CONSOLE_WARNING_TEMPLATE(verifyResult, opts = {}) {
+    if (verifyResult.clean) {
+        return '';
+    }
+
+    const lines = [];
+
+    lines.push('⚠️  Library is stale');
+    lines.push('');
+    lines.push('The following books are out of date:');
+    lines.push('');
+
+    for (const book of verifyResult.staleBooks) {
+        lines.push(`  • ${book.path}`);
+        for (const reason of book.reasons) {
+            lines.push(`    - ${reason}`);
+        }
+    }
+
+    lines.push('');
+
+    if (opts.autoRegen === 'will-run') {
+        lines.push('Auto-regeneration will run before the release is tagged.');
+    } else if (opts.autoRegen === 'deferred') {
+        lines.push('Library will be auto-regenerated when you run create-pr.');
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Render a Markdown section for the PR body when Library is stale.
+ *
+ * The section heading is exactly `## ⚠️ Library is stale` — do not
+ * change this; downstream tooling may key on it. Includes stale-books
+ * list with reasons and a remediation section that varies by
+ * `opts.autoRegen`:
+ *   - `'completed'` — auto-regen ran successfully; no scripts listed
+ *   - `'failed'`    — auto-regen failed; scripts listed as fallback
+ *
+ * The acknowledgement line is always present.
+ *
+ * Returns an empty string when the Library is clean.
+ *
+ * @param {Object} verifyResult
+ * @param {boolean}      verifyResult.clean
+ * @param {Array<{ path: string, reasons: string[] }>} verifyResult.staleBooks
+ * @param {string[]}     verifyResult.recommendedScripts
+ * @param {Object}       opts
+ * @param {'completed'|'failed'} opts.autoRegen — controls the remediation section
+ * @returns {string} Markdown section, or empty string if clean
+ */
+export function PR_BODY_SECTION_TEMPLATE(verifyResult, opts = {}) {
+    if (verifyResult.clean) {
+        return '';
+    }
+
+    const lines = [];
+
+    lines.push('## ⚠️ Library is stale');
+    lines.push('');
+    lines.push('The following Library books are out of date:');
+    lines.push('');
+
+    for (const book of verifyResult.staleBooks) {
+        const reasonText = book.reasons.join('; ');
+        lines.push(`- \`${book.path}\` — ${reasonText}`);
+    }
+
+    lines.push('');
+
+    if (opts.autoRegen === 'completed') {
+        lines.push('**Auto-regeneration was performed.** The books listed above were regenerated in the release commit.');
+    } else if (opts.autoRegen === 'failed') {
+        lines.push('**Recommended remediation scripts:**');
+        lines.push('');
+        for (const script of verifyResult.recommendedScripts) {
+            lines.push(`- \`${script}\``);
+        }
+        lines.push('');
+        lines.push('_Auto-regeneration was attempted but failed. Run the scripts manually._');
+    }
+
+    lines.push('');
+    lines.push(
+        '_This release was tagged via claude-hooks. The Library lifecycle pipeline is integrated with `create-pr` and `back-merge` — staleness at release time indicates a path that bypassed the pipeline._'
+    );
+
+    return lines.join('\n');
+}
+
+/**
+ * Tag value used to mark a PR or Linear issue as library-stale.
+ *
+ * Applied as a Linear label slug or a PR-title prefix by consumers.
+ *
+ * @type {string}
+ */
+export const PR_TAG_VALUE = 'library-stale';
+
+export const LIBRARY_VERIFY_SKIPPED_WARNING =
+    'Library verification skipped due to an unexpected error. ' +
+    'The version bump will proceed normally.';
+
+export const LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE =
+    'Library verification skipped due to an unexpected error. ' +
+    'The release will proceed normally.';

package/lib/utils/claude-client.js

@@ -502,10 +502,11 @@ async function verifySDKConnection() {
  * @param {number} options.timeout - Timeout in milliseconds (default: 120000 = 2 minutes)
  * @param {string} options.model - Claude model override (e.g., 'haiku', 'sonnet', 'opus')
  * @param {boolean} options.headless - Use SDK instead of CLI (default: false)
+ * @param {boolean} options.print - Use CLI print mode (-p): text-only output, no tool use (default: false)
  * @returns {Promise<string>} Claude's response
  * @throws {ClaudeClientError} If execution fails or times out
  */
-const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null, headless = false, maxTokens = null, costTracker = null } = {}) => {
+const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null, headless = false, maxTokens = null, costTracker = null, print = false } = {}) => {
     // Headless mode: use Anthropic SDK directly (GH#133)
     // Branch here (not in executeClaudeWithRetry) because analyzeCode calls
     // executeClaude directly via withRetry — branching here covers all paths.
@@ -548,10 +549,14 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = nu
             // executed inside bash --login so that .profile/.bashrc set up the correct PATH.
             // All CLI flags are embedded in the bash -c command string (no spaces in flag values).
             const claudeParts = [loginShell.path];
+            if (print) claudeParts.push('-p');
             if (allowedTools.length > 0) claudeParts.push(`--allowedTools ${allowedTools.join(',')}`);
             if (model) claudeParts.push(`--model ${model}`);
             finalArgs.push('bash', '-lc', claudeParts.join(' '));
         } else {
+            if (print) {
+                finalArgs.push('-p');
+            }
             if (allowedTools.length > 0) {
                 // Format: --allowedTools "mcp__github__create_pull_request,mcp__github__get_file_contents"
                 finalArgs.push('--allowedTools', allowedTools.join(','));