claude-git-hooks 2.11.0 → 2.12.0

package/lib/utils/git-tag-manager.js

@@ -0,0 +1,516 @@
+/**
+ * File: git-tag-manager.js
+ * Purpose: Manage Git tag operations for version management
+ *
+ * Handles:
+ * - Creating annotated tags
+ * - Listing local and remote tags
+ * - Comparing tag versions
+ * - Pushing tags to remote
+ */
+
+import { execSync } from 'child_process';
+import logger from './logger.js';
+import { getRemoteName } from './git-operations.js';
+import { compareVersions } from './version-manager.js';
+
+/**
+ * Custom error for git tag operation failures
+ */
+class GitTagError extends Error {
+    constructor(message, { command, cause, output } = {}) {
+        super(message);
+        this.name = 'GitTagError';
+        this.command = command;
+        this.cause = cause;
+        this.output = output;
+    }
+}
+
+/**
+ * Executes a git command for tag operations
+ * Why: Consistent error handling for tag-specific operations
+ *
+ * @param {string} command - Git command to execute
+ * @returns {string} Command output
+ * @throws {GitTagError} If command fails
+ */
+function execGitTagCommand(command) {
+    logger.debug('git-tag-manager - execGitTagCommand', 'Executing command', { command });
+
+    try {
+        const output = execSync(command, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        logger.debug('git-tag-manager - execGitTagCommand', 'Command successful', {
+            command,
+            outputLength: output.length
+        });
+
+        return output.trim();
+
+    } catch (error) {
+        logger.error('git-tag-manager - execGitTagCommand', 'Command failed', {
+            command,
+            error: error.message
+        });
+
+        throw new GitTagError('Git tag command failed', {
+            command,
+            cause: error,
+            output: error.stderr || error.stdout
+        });
+    }
+}
+
+/**
+ * Parses tag name to extract version
+ * Why: Tags have 'v' prefix (v2.7.0), need clean version
+ *
+ * @param {string} tagName - Tag name (e.g., "v2.7.0-SNAPSHOT")
+ * @returns {string} Version without 'v' prefix
+ */
+export function parseTagVersion(tagName) {
+    logger.debug('git-tag-manager - parseTagVersion', 'Parsing tag version', { tagName });
+
+    // Remove 'v' prefix if present
+    const version = tagName.replace(/^v/, '');
+
+    logger.debug('git-tag-manager - parseTagVersion', 'Version parsed', { tagName, version });
+
+    return version;
+}
+
+/**
+ * Formats version as tag name
+ * Why: Adds 'v' prefix consistently
+ *
+ * @param {string} version - Version string (e.g., "2.7.0")
+ * @returns {string} Tag name (e.g., "v2.7.0")
+ */
+export function formatTagName(version) {
+    logger.debug('git-tag-manager - formatTagName', 'Formatting tag name', { version });
+
+    // Add 'v' prefix if not present
+    const tagName = version.startsWith('v') ? version : `v${version}`;
+
+    logger.debug('git-tag-manager - formatTagName', 'Tag name formatted', { version, tagName });
+
+    return tagName;
+}
+
+/**
+ * Gets all local tags
+ * Why: Lists tags for comparison and validation
+ *
+ * @returns {Array<string>} Array of tag names
+ */
+export function getLocalTags() {
+    logger.debug('git-tag-manager - getLocalTags', 'Getting local tags');
+
+    try {
+        const output = execGitTagCommand('git tag --list');
+
+        if (!output) {
+            logger.debug('git-tag-manager - getLocalTags', 'No local tags found');
+            return [];
+        }
+
+        const tags = output.split(/\r?\n/).filter(t => t.length > 0);
+
+        logger.debug('git-tag-manager - getLocalTags', 'Local tags retrieved', {
+            count: tags.length
+        });
+
+        return tags;
+
+    } catch (error) {
+        logger.error('git-tag-manager - getLocalTags', 'Failed to get local tags', error);
+        return [];
+    }
+}
+
+/**
+ * Gets latest local tag (by version order)
+ * Why: Determines current version for alignment checks
+ *
+ * @returns {string|null} Latest tag name or null if no tags
+ */
+export function getLatestLocalTag() {
+    logger.debug('git-tag-manager - getLatestLocalTag', 'Getting latest local tag');
+
+    try {
+        // Get tags sorted by version (descending)
+        const output = execGitTagCommand('git tag --list --sort=-v:refname');
+
+        if (!output) {
+            logger.debug('git-tag-manager - getLatestLocalTag', 'No tags found');
+            return null;
+        }
+
+        const tags = output.split(/\r?\n/).filter(t => t.length > 0);
+        const latestTag = tags[0] || null;
+
+        logger.debug('git-tag-manager - getLatestLocalTag', 'Latest tag found', { latestTag });
+
+        return latestTag;
+
+    } catch (error) {
+        logger.error('git-tag-manager - getLatestLocalTag', 'Failed to get latest tag', error);
+        return null;
+    }
+}
+
+/**
+ * Gets all remote tags
+ * Why: Compare local tags with remote for push status
+ *
+ * @param {string} remoteName - Remote name (default: 'origin')
+ * @returns {Promise<Array<string>>} Array of tag names
+ */
+export async function getRemoteTags(remoteName = null) {
+    logger.debug('git-tag-manager - getRemoteTags', 'Getting remote tags', { remoteName });
+
+    try {
+        const remote = remoteName || getRemoteName();
+        const output = execGitTagCommand(`git ls-remote --tags ${remote}`);
+
+        if (!output) {
+            logger.debug('git-tag-manager - getRemoteTags', 'No remote tags found');
+            return [];
+        }
+
+        // Parse output: "hash refs/tags/tagname"
+        const tags = output
+            .split(/\r?\n/)
+            .filter(line => line.length > 0)
+            .map(line => {
+                const parts = line.split('\t');
+                if (parts.length < 2) return null;
+                const ref = parts[1];
+                // Extract tag name from refs/tags/v2.7.0
+                const match = ref.match(/refs\/tags\/(.+?)(\^\{\})?$/);
+                return match ? match[1] : null;
+            })
+            .filter(tag => tag !== null);
+
+        logger.debug('git-tag-manager - getRemoteTags', 'Remote tags retrieved', {
+            remote,
+            count: tags.length
+        });
+
+        return tags;
+
+    } catch (error) {
+        logger.error('git-tag-manager - getRemoteTags', 'Failed to get remote tags', error);
+        return [];
+    }
+}
+
+/**
+ * Gets latest remote tag (by version order)
+ * Why: Compare local version with deployed version
+ *
+ * @param {string} remoteName - Remote name (default: 'origin')
+ * @returns {Promise<string|null>} Latest tag name or null
+ */
+export async function getLatestRemoteTag(remoteName = null) {
+    logger.debug('git-tag-manager - getLatestRemoteTag', 'Getting latest remote tag');
+
+    try {
+        const tags = await getRemoteTags(remoteName);
+
+        if (tags.length === 0) {
+            logger.debug('git-tag-manager - getLatestRemoteTag', 'No remote tags found');
+            return null;
+        }
+
+        // Sort tags by version (descending)
+        // Why: Reuse compareVersions for consistency and maintainability
+        const sortedTags = tags.sort((a, b) => {
+            const versionA = parseTagVersion(a);
+            const versionB = parseTagVersion(b);
+
+            try {
+                // compareVersions returns: 1 if a > b, -1 if a < b, 0 if equal
+                // For descending sort, we need to reverse the comparison
+                return -compareVersions(versionA, versionB);
+            } catch (error) {
+                // Fallback: keep original order if comparison fails
+                logger.debug('git-tag-manager - getLatestRemoteTag', 'Version comparison failed', {
+                    versionA,
+                    versionB,
+                    error: error.message
+                });
+                return 0;
+            }
+        });
+
+        const latestTag = sortedTags[0];
+
+        logger.debug('git-tag-manager - getLatestRemoteTag', 'Latest remote tag found', { latestTag });
+
+        return latestTag;
+
+    } catch (error) {
+        logger.error('git-tag-manager - getLatestRemoteTag', 'Failed to get latest remote tag', error);
+        return null;
+    }
+}
+
+/**
+ * Checks if tag exists
+ * Why: Prevents duplicate tag creation
+ *
+ * @param {string} tagName - Tag name to check
+ * @param {string} location - Where to check: 'local' | 'remote' | 'both'
+ * @returns {Promise<boolean>} True if tag exists
+ */
+export async function tagExists(tagName, location = 'local') {
+    logger.debug('git-tag-manager - tagExists', 'Checking tag existence', { tagName, location });
+
+    try {
+        if (location === 'local' || location === 'both') {
+            const localTags = getLocalTags();
+            if (localTags.includes(tagName)) {
+                logger.debug('git-tag-manager - tagExists', 'Tag exists locally', { tagName });
+                return true;
+            }
+        }
+
+        if (location === 'remote' || location === 'both') {
+            const remoteTags = await getRemoteTags();
+            if (remoteTags.includes(tagName)) {
+                logger.debug('git-tag-manager - tagExists', 'Tag exists on remote', { tagName });
+                return true;
+            }
+        }
+
+        logger.debug('git-tag-manager - tagExists', 'Tag does not exist', { tagName, location });
+        return false;
+
+    } catch (error) {
+        logger.error('git-tag-manager - tagExists', 'Failed to check tag existence', error);
+        return false;
+    }
+}
+
+/**
+ * Creates annotated Git tag
+ * Why: Tags mark version releases with metadata
+ *
+ * @param {string} version - Version string (e.g., "2.7.0")
+ * @param {string} message - Tag annotation message
+ * @param {Object} options - Tag options
+ * @param {boolean} options.force - Force tag creation (overwrite existing)
+ * @returns {Object} Result: { success, tagName, error }
+ */
+export function createTag(version, message, { force = false } = {}) {
+    logger.debug('git-tag-manager - createTag', 'Creating tag', { version, message, force });
+
+    const tagName = formatTagName(version);
+
+    try {
+        // Check if tag already exists (unless force)
+        if (!force) {
+            const localTags = getLocalTags();
+            if (localTags.includes(tagName)) {
+                logger.warning('git-tag-manager - createTag', 'Tag already exists', { tagName });
+                return {
+                    success: false,
+                    tagName,
+                    error: `Tag ${tagName} already exists. Use --force to overwrite.`
+                };
+            }
+        }
+
+        // Create annotated tag
+        // Why: Escape message to prevent shell injection and handle special characters
+        const escapedMessage = message.replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const forceFlag = force ? '-f' : '';
+        const command = `git tag ${forceFlag} -a ${tagName} -m "${escapedMessage}"`;
+        execGitTagCommand(command);
+
+        logger.debug('git-tag-manager - createTag', 'Tag created successfully', { tagName });
+
+        return {
+            success: true,
+            tagName,
+            error: null
+        };
+
+    } catch (error) {
+        logger.error('git-tag-manager - createTag', 'Failed to create tag', error);
+
+        return {
+            success: false,
+            tagName,
+            error: error.message
+        };
+    }
+}
+
+/**
+ * Pushes tag(s) to remote
+ * Why: Publishes version tags to remote repository
+ *
+ * @param {string} remoteName - Remote name (default: from config)
+ * @param {string|Array<string>} tags - Tag name(s) to push, or 'all' for all tags
+ * @returns {Object} Result: { success, pushed, failed, error }
+ */
+export function pushTags(remoteName = null, tags = 'all') {
+    logger.debug('git-tag-manager - pushTags', 'Pushing tags', { remoteName, tags });
+
+    const remote = remoteName || getRemoteName();
+
+    try {
+        if (tags === 'all') {
+            // Push all tags
+            execGitTagCommand(`git push ${remote} --tags`);
+
+            logger.debug('git-tag-manager - pushTags', 'All tags pushed successfully');
+
+            return {
+                success: true,
+                pushed: 'all',
+                failed: [],
+                error: null
+            };
+
+        } else {
+            // Push specific tag(s)
+            const tagList = Array.isArray(tags) ? tags : [tags];
+            const pushed = [];
+            const failed = [];
+
+            for (const tag of tagList) {
+                try {
+                    execGitTagCommand(`git push ${remote} ${tag}`);
+                    pushed.push(tag);
+                    logger.debug('git-tag-manager - pushTags', 'Tag pushed', { tag });
+                } catch (error) {
+                    failed.push({ tag, error: error.message });
+                    logger.error('git-tag-manager - pushTags', 'Failed to push tag', { tag, error });
+                }
+            }
+
+            const success = failed.length === 0;
+
+            logger.debug('git-tag-manager - pushTags', 'Tag push complete', {
+                pushed: pushed.length,
+                failed: failed.length
+            });
+
+            return {
+                success,
+                pushed,
+                failed,
+                error: failed.length > 0 ? `Failed to push ${failed.length} tag(s)` : null
+            };
+        }
+
+    } catch (error) {
+        logger.error('git-tag-manager - pushTags', 'Failed to push tags', error);
+
+        return {
+            success: false,
+            pushed: [],
+            failed: [],
+            error: error.message
+        };
+    }
+}
+
+/**
+ * Compares local and remote tags
+ * Why: Identifies unpushed tags for create-pr validation
+ *
+ * @returns {Promise<Object>} Comparison result: { localNewer, remoteNewer, common }
+ */
+export async function compareLocalAndRemoteTags() {
+    logger.debug('git-tag-manager - compareLocalAndRemoteTags', 'Comparing tags');
+
+    try {
+        const localTags = getLocalTags();
+        const remoteTags = await getRemoteTags();
+
+        const localSet = new Set(localTags);
+        const remoteSet = new Set(remoteTags);
+
+        // Tags only in local (not pushed)
+        const localNewer = localTags.filter(tag => !remoteSet.has(tag));
+
+        // Tags only in remote (local behind)
+        const remoteNewer = remoteTags.filter(tag => !localSet.has(tag));
+
+        // Tags in both
+        const common = localTags.filter(tag => remoteSet.has(tag));
+
+        const result = {
+            localNewer,
+            remoteNewer,
+            common
+        };
+
+        logger.debug('git-tag-manager - compareLocalAndRemoteTags', 'Comparison complete', {
+            localNewer: localNewer.length,
+            remoteNewer: remoteNewer.length,
+            common: common.length
+        });
+
+        return result;
+
+    } catch (error) {
+        logger.error('git-tag-manager - compareLocalAndRemoteTags', 'Comparison failed', error);
+
+        return {
+            localNewer: [],
+            remoteNewer: [],
+            common: []
+        };
+    }
+}
+
+/**
+ * Deletes a tag
+ * Why: Remove incorrect or test tags
+ *
+ * @param {string} tagName - Tag name to delete
+ * @param {Object} options - Delete options
+ * @param {boolean} options.remote - Also delete from remote
+ * @returns {Object} Result: { success, error }
+ */
+export function deleteTag(tagName, { remote = false } = {}) {
+    logger.debug('git-tag-manager - deleteTag', 'Deleting tag', { tagName, remote });
+
+    try {
+        // Delete local tag
+        execGitTagCommand(`git tag -d ${tagName}`);
+
+        logger.debug('git-tag-manager - deleteTag', 'Local tag deleted', { tagName });
+
+        // Delete remote tag if requested
+        if (remote) {
+            const remoteName = getRemoteName();
+            execGitTagCommand(`git push ${remoteName} --delete ${tagName}`);
+            logger.debug('git-tag-manager - deleteTag', 'Remote tag deleted', { tagName });
+        }
+
+        return {
+            success: true,
+            error: null
+        };
+
+    } catch (error) {
+        logger.error('git-tag-manager - deleteTag', 'Failed to delete tag', error);
+
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+export { GitTagError };