bump

Bump the project version, update documentation, create a git tag, and publish a GitHub release.

• Version argument is REQUIRED (e.g., $bump 0.4.0)
• Should be on main branch (warn if not, but proceed)
• gh CLI must be authenticated
• Dirty working tree is allowed — uncommitted changes will be included in the release commit

Phase 1: Validate

1. Check version argument:

   • If no version provided, STOP and ask: "Please provide a version (e.g., $bump 0.4.0)"
   • Version must be valid semver (e.g., 0.4.0, 1.0.0-beta.1)

2. Check git status:

   git status --porcelain
   

   • If there are uncommitted changes, WARN the user but proceed anyway — these changes will be staged and included in the release commit.

3. Check current branch:

   git branch --show-current
   

   • Warn if not on main branch (but allow to proceed)

4. Get current version:

   node -p "require('./package.json').version"
   

Phase 2: Extract Changelog from Git Commits

CRITICAL: Do NOT use placeholder text like "Version bump". Extract real changes from git commits.

1. Get commits since last version tag:

   git log v<previous_version>..HEAD --oneline --no-merges
   

2. For each meaningful commit, examine changes:

   git show --stat <commit_hash>
   git diff v<previous_version>..HEAD -- <key_files>
   

3. Categorize changes into Keep a Changelog format:

   • Added: New features, capabilities, or files
   • Changed: Modifications to existing behavior, enhancements, updated defaults
   • Fixed: Bug fixes, error corrections
   • Removed: Removed features or code
   • Deprecated: Features marked for future removal
   • Security: Security-related changes

4. Write specific, detailed changelog entries:

   • Describe WHAT changed and WHY (from user perspective)
   • Include concrete details (e.g., "timeout increased from 120s to 300s")
   • Reference specific configuration changes, default values, etc.
   • ONLY use "Version bump" if literally nothing changed (empty git diff)