Merge pull request #3 from xtr-dev/feature/version-management-workflow

feat: add automated version management with AI-generated changelogs

.github/workflows/version-and-publish.yml

@@ -0,0 +1,375 @@
+name: Version and Publish
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    types: [closed]
+
+jobs:
+  version-and-publish:
+    if: github.event_name == 'push' || (github.event.pull_request.merged == true && (contains(github.event.pull_request.head.ref, 'version/major') || contains(github.event.pull_request.head.ref, 'version/minor') || contains(github.event.pull_request.head.ref, 'version/patch')))
+    runs-on: ubuntu-latest
+    outputs:
+      new-version: ${{ steps.version-bump.outputs.new-version }}
+      current-version: ${{ steps.version-bump.outputs.current-version }}
+      version-type: ${{ steps.version-type.outputs.type }}
+      package-name: ${{ steps.prerequisites.outputs.package-name }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 8
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Validate prerequisites and setup
+        id: prerequisites
+        run: |
+          # Extract package info
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+
+          echo "package-name=$PACKAGE_NAME" >> $GITHUB_OUTPUT
+          echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+          echo "📦 Package: $PACKAGE_NAME"
+          echo "📌 Current Version: $CURRENT_VERSION"
+
+          # Validate version branches exist
+          echo "🔍 Validating version branches..."
+          MISSING_BRANCHES=""
+
+          for branch in "version/major" "version/minor" "version/patch"; do
+            if ! git ls-remote --heads origin "$branch" | grep -q "$branch"; then
+              MISSING_BRANCHES="$MISSING_BRANCHES $branch"
+            fi
+          done
+
+          if [ -n "$MISSING_BRANCHES" ]; then
+            echo "❌ ERROR: Missing required version branches:$MISSING_BRANCHES"
+            echo "Please create these branches first:"
+            for branch in $MISSING_BRANCHES; do
+              echo "  git checkout -b $branch && git push origin $branch"
+            done
+            exit 1
+          fi
+
+          echo "✅ All version branches exist"
+
+          # Validate Node.js version matches package.json engines
+          NODE_VERSION=$(node --version)
+          echo "🔍 Validating Node.js version: $NODE_VERSION"
+
+          # Basic validation - check if we're on Node 20+
+          if ! echo "$NODE_VERSION" | grep -qE "^v(20|21|22)\."; then
+            echo "⚠️  WARNING: Node.js version $NODE_VERSION may not match package.json engines requirements"
+          fi
+
+          echo "✅ Prerequisites validation complete"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Run build
+        run: pnpm build
+
+      - name: Determine version bump type
+        id: version-type
+        run: |
+          if [[ "${{ github.event.pull_request.head.ref }}" =~ version/major ]]; then
+            echo "type=major" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event.pull_request.head.ref }}" =~ version/minor ]]; then
+            echo "type=minor" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event.pull_request.head.ref }}" =~ version/patch ]]; then
+            echo "type=patch" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event_name }}" == "push" ]]; then
+            # Default to patch for direct pushes to main
+            echo "type=patch" >> $GITHUB_OUTPUT
+          else
+            echo "type=none" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Configure git
+        if: steps.version-type.outputs.type != 'none'
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install Claude Code CLI
+        if: steps.version-type.outputs.type != 'none'
+        run: |
+          curl -fsSL https://claude.ai/cli/install.sh | bash
+          echo "$HOME/.claude/bin" >> $GITHUB_PATH
+
+      - name: Generate changelog with Claude (with fallback)
+        if: steps.version-type.outputs.type != 'none'
+        id: changelog
+        run: |
+          # Get commits since last tag
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          if [ -z "$LAST_TAG" ]; then
+            COMMITS=$(git log --oneline --no-merges --since="1 week ago" || echo "No recent commits")
+          else
+            COMMITS=$(git log --oneline --no-merges ${LAST_TAG}..HEAD || echo "No new commits")
+          fi
+
+
+          # Generate changelog using Claude (fail if it fails)
+          if ! command -v claude-code >/dev/null 2>&1; then
+            echo "❌ ERROR: Claude CLI not found. Please ensure Claude Code is properly installed."
+            exit 1
+          fi
+
+          echo "🤖 Generating changelog with Claude..."
+          CHANGELOG=$(timeout 240s claude-code << 'CLAUDE_EOF'
+Please analyze the following git commits and generate a concise changelog in this exact format:
+
+## Changes
+
+### 🚀 Features
+- Brief description of new features
+
+### 🐛 Bug Fixes
+- Brief description of bug fixes
+
+### 🔧 Improvements
+- Brief description of improvements/refactoring
+
+### 📚 Documentation
+- Brief description of documentation changes
+
+### ⚡ Performance
+- Brief description of performance improvements
+
+Only include sections that have actual changes. Keep each bullet point concise and user-focused.
+
+Git commits to analyze:
+$COMMITS
+CLAUDE_EOF
+          )
+
+          # Check if changelog generation succeeded
+          if [ $? -ne 0 ] || [ -z "$CHANGELOG" ]; then
+            echo "❌ ERROR: Failed to generate changelog with Claude. Workflow cannot continue."
+            echo "Debug info - Commits to analyze:"
+            echo "$COMMITS"
+            exit 1
+          fi
+
+          echo "✅ Successfully generated changelog with Claude"
+
+          # Save changelog to output
+          echo "changelog<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create version bump script
+        if: steps.version-type.outputs.type != 'none'
+        run: |
+          # Create Node.js script to safely bump version
+          cat > bump-version.js << 'VERSION_SCRIPT_EOF'
+          const fs = require('fs');
+          const path = require('path');
+
+          const versionType = process.argv[2];
+          const packagePath = path.join(process.cwd(), 'package.json');
+
+          try {
+            const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+            const currentVersion = packageJson.version;
+            const [major, minor, patch] = currentVersion.split('.').map(Number);
+
+            let newVersion;
+            switch (versionType) {
+              case 'major':
+                newVersion = `${major + 1}.0.0`;
+                break;
+              case 'minor':
+                newVersion = `${major}.${minor + 1}.0`;
+                break;
+              case 'patch':
+                newVersion = `${major}.${minor}.${patch + 1}`;
+                break;
+              default:
+                throw new Error(`Invalid version type: ${versionType}`);
+            }
+
+            packageJson.version = newVersion;
+            fs.writeFileSync(packagePath, JSON.stringify(packageJson, null, 2) + '\n');
+
+            console.log(`${currentVersion}:${newVersion}`);
+          } catch (error) {
+            console.error('Error bumping version:', error.message);
+            process.exit(1);
+          }
+          VERSION_SCRIPT_EOF
+
+      - name: Create single atomic commit with all changes
+        if: steps.version-type.outputs.type != 'none'
+        id: version-bump
+        run: |
+          # Extract version type for commit title
+          VERSION_TYPE="${{ steps.version-type.outputs.type }}"
+
+          # Create clean commit message title
+          if [ "$VERSION_TYPE" = "major" ]; then
+            COMMIT_TITLE="🚀 Major Release"
+          elif [ "$VERSION_TYPE" = "minor" ]; then
+            COMMIT_TITLE="✨ Minor Release"
+          else
+            COMMIT_TITLE="🐛 Patch Release"
+          fi
+
+          # Get the safe base commit (last release tag or fallback)
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          if [ -n "$LAST_TAG" ]; then
+            BASE_COMMIT=$(git rev-list -n 1 $LAST_TAG)
+          else
+            # Fallback: get commit from 1 week ago or first commit
+            BASE_COMMIT=$(git rev-list --since="1 week ago" --reverse HEAD | head -1 || git rev-list --max-parents=0 HEAD)
+          fi
+
+          echo "Base commit for squash: $BASE_COMMIT"
+
+          # Safely reset to base (soft reset preserves working directory)
+          git reset --soft $BASE_COMMIT
+
+          # Bump version using our safe Node.js script
+          VERSION_OUTPUT=$(node bump-version.js $VERSION_TYPE)
+          CURRENT_VERSION=$(echo $VERSION_OUTPUT | cut -d: -f1)
+          NEW_VERSION=$(echo $VERSION_OUTPUT | cut -d: -f2)
+
+          echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          echo "new-version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+          # Synchronize pnpm lockfile if it exists
+          if [ -f pnpm-lock.yaml ]; then
+            echo "Synchronizing pnpm lockfile..."
+            pnpm install --frozen-lockfile --ignore-scripts || echo "Lockfile sync completed with warnings"
+          fi
+
+          # Create single atomic commit with everything
+          git add -A
+          COMMIT_MSG="$COMMIT_TITLE
+
+          ${{ steps.changelog.outputs.changelog }}"
+
+          git commit -m "$COMMIT_MSG" || {
+            echo "Commit failed, checking git status:"
+            git status
+            git diff --cached
+            exit 1
+          }
+
+          # Create git tag
+          git tag -a "v$NEW_VERSION" -m "Version $NEW_VERSION
+
+          ${{ steps.changelog.outputs.changelog }}"
+
+          echo "Created single atomic commit with version $CURRENT_VERSION → $NEW_VERSION"
+
+          # Clean up temporary files
+          rm -f bump-version.js
+
+      - name: Push version changes safely
+        if: steps.version-type.outputs.type != 'none'
+        run: |
+          # Check if we need to force push (if git history was rewritten)
+          CURRENT_REMOTE_HEAD=$(git ls-remote origin main | cut -f1)
+          LOCAL_REMOTE_HEAD=$(git rev-parse origin/main)
+
+          if [ "$CURRENT_REMOTE_HEAD" != "$LOCAL_REMOTE_HEAD" ]; then
+            echo "⚠️  Remote main has been updated by another process"
+            echo "Current remote HEAD: $CURRENT_REMOTE_HEAD"
+            echo "Local remote HEAD: $LOCAL_REMOTE_HEAD"
+            echo "❌ ABORTING: Cannot safely force push. Another workflow may be running."
+            exit 1
+          fi
+
+          # Safe force push with lease (only if remote hasn't changed)
+          echo "🚀 Pushing squashed commit to main..."
+          git push --force-with-lease origin main || {
+            echo "❌ ERROR: Force push failed. This likely means:"
+            echo "1. Another workflow pushed to main after this one started"
+            echo "2. Branch protection rules are preventing the push"
+            echo "3. Insufficient permissions"
+            exit 1
+          }
+
+          echo "🏷️  Pushing tags..."
+          git push origin --tags
+
+      - name: Publish to NPM
+        if: steps.version-type.outputs.type != 'none'
+        run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        if: steps.version-type.outputs.type != 'none'
+        run: |
+          gh release create "v${{ steps.version-bump.outputs.new-version }}" \
+            --title "Release v${{ steps.version-bump.outputs.new-version }}" \
+            --notes "# Release v${{ steps.version-bump.outputs.new-version }}
+
+          ${{ steps.changelog.outputs.changelog }}
+
+          ---
+
+          **Version Info**: ${{ steps.version-type.outputs.type }} release (v${{ steps.version-bump.outputs.current-version }} → v${{ steps.version-bump.outputs.new-version }})
+
+          ### Installation
+
+          \`\`\`bash
+          npm install ${{ steps.prerequisites.outputs.package-name }}@${{ steps.version-bump.outputs.new-version }}
+          \`\`\`
+
+          ### Documentation
+
+          See the [README](https://github.com/${{ github.repository }}#readme) for usage instructions and full documentation."
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  notify-success:
+    if: github.event_name == 'push' || (github.event.pull_request.merged == true && (contains(github.event.pull_request.head.ref, 'version/major') || contains(github.event.pull_request.head.ref, 'version/minor') || contains(github.event.pull_request.head.ref, 'version/patch')))
+    needs: version-and-publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Success notification
+        if: needs.version-and-publish.outputs.new-version != ''
+        run: |
+          echo "🎉 Successfully published version ${{ needs.version-and-publish.outputs.new-version }} to NPM!"
+          echo "📦 Package: https://www.npmjs.com/package/${{ needs.version-and-publish.outputs.package-name }}"
+          echo "🏷️  GitHub Release: https://github.com/${{ github.repository }}/releases/tag/v${{ needs.version-and-publish.outputs.new-version }}"
+          echo "🔄 Version Type: ${{ needs.version-and-publish.outputs.version-type }}"
+          echo "📈 Version Change: v${{ needs.version-and-publish.outputs.current-version }} → v${{ needs.version-and-publish.outputs.new-version }}"

VERSION_WORKFLOW.md

@@ -0,0 +1,155 @@
+# Version Management Workflow
+
+This repository uses automated version management with GitHub Actions. Version bumps are triggered based on which branch changes are merged to `main`.
+
+## Available Branches
+
+- `version/major` - For breaking changes (e.g., 1.0.0 → 2.0.0)
+- `version/minor` - For new features (e.g., 1.0.0 → 1.1.0)
+- `version/patch` - For bug fixes (e.g., 1.0.0 → 1.0.1)
+
+## How to Use
+
+### For Patch Releases (Bug Fixes)
+1. Create a branch from `version/patch`:
+   ```bash
+   git checkout version/patch
+   git pull origin version/patch
+   git checkout -b fix/your-bug-fix
+   # Make your changes
+   git commit -m "fix: your bug fix description"
+   git push origin fix/your-bug-fix
+   ```
+
+2. Create a PR targeting `version/patch`
+3. Once approved, merge the PR to `version/patch`
+4. Create a PR from `version/patch` to `main`
+5. When merged to `main`, the workflow will:
+   - Bump patch version (e.g., 1.0.0 → 1.0.1)
+   - Run tests and build
+   - Publish to NPM
+   - Create a GitHub release
+
+### For Minor Releases (New Features)
+1. Create a branch from `version/minor`:
+   ```bash
+   git checkout version/minor
+   git pull origin version/minor
+   git checkout -b feature/your-feature
+   # Make your changes
+   git commit -m "feat: your feature description"
+   git push origin feature/your-feature
+   ```
+
+2. Create a PR targeting `version/minor`
+3. Once approved, merge the PR to `version/minor`
+4. Create a PR from `version/minor` to `main`
+5. When merged to `main`, the workflow will:
+   - Bump minor version (e.g., 1.0.0 → 1.1.0)
+   - Run tests and build
+   - Publish to NPM
+   - Create a GitHub release
+
+### For Major Releases (Breaking Changes)
+1. Create a branch from `version/major`:
+   ```bash
+   git checkout version/major
+   git pull origin version/major
+   git checkout -b breaking/your-breaking-change
+   # Make your changes
+   git commit -m "feat!: your breaking change description"
+   git push origin breaking/your-breaking-change
+   ```
+
+2. Create a PR targeting `version/major`
+3. Once approved, merge the PR to `version/major`
+4. Create a PR from `version/major` to `main`
+5. When merged to `main`, the workflow will:
+   - Bump major version (e.g., 1.0.0 → 2.0.0)
+   - Run tests and build
+   - Publish to NPM
+   - Create a GitHub release
+
+## Direct Push to Main
+Direct pushes to `main` will trigger a patch version bump by default.
+
+## Required Secrets
+
+Make sure these secrets are configured in your GitHub repository:
+
+- `NPM_TOKEN` - Your NPM authentication token for publishing
+- `GITHUB_TOKEN` - Automatically provided by GitHub Actions
+
+## Workflow Features
+
+- ✅ Automatic version bumping based on branch
+- ✅ AI-generated changelog using Claude Code CLI
+- ✅ Squashes all PR commits into single clean commit
+- ✅ Runs tests before publishing
+- ✅ Builds the package before publishing
+- ✅ Creates git tags with changelog in tag message
+- ✅ Publishes to NPM with public access
+- ✅ Creates GitHub releases with formatted changelog
+- ✅ Prevents publishing if tests fail
+
+## Changelog Generation
+
+The workflow automatically generates a standardized changelog for each release using Claude Code CLI. The changelog analyzes git commits since the last release and categorizes them into:
+
+- 🚀 **Features** - New functionality
+- 🐛 **Bug Fixes** - Bug fixes and corrections
+- 🔧 **Improvements** - Code improvements and refactoring
+- 📚 **Documentation** - Documentation updates
+- ⚡ **Performance** - Performance optimizations
+
+The generated changelog is included in:
+- The single squashed release commit message
+- The git tag message
+- The GitHub release notes
+
+## Git History Structure
+
+The workflow creates an ultra-clean git history by squashing all commits from the PR into a single release commit:
+
+**Before Squashing:**
+```
+abc123 feat: add email scheduling
+def456 fix: validation bug
+ghi789 docs: update readme
+jkl012 test: add unit tests
+```
+
+**After Squashing:**
+```
+abc123 ✨ Minor Release
+
+## Changes
+### 🚀 Features
+- Add email scheduling feature
+### 🐛 Bug Fixes
+- Fix validation error handling
+### 📚 Documentation
+- Update readme with new examples
+```
+
+This results in one meaningful commit per release with all changes summarized in the AI-generated changelog.
+
+## Version Branch Maintenance
+
+Keep version branches up to date by periodically merging from main:
+
+```bash
+git checkout version/patch
+git merge main
+git push origin version/patch
+
+git checkout version/minor
+git merge main
+git push origin version/minor
+
+git checkout version/major
+git merge main
+git push origin version/major
+```
+
+This ensures that all version branches have the latest changes from main before creating new features or fixes.