gemfile-upgrade

name	gemfile-upgrade
description	Safely upgrade a Ruby gem with changelog review, breaking changes analysis, bundle update, test run, and commit. Use when the user asks to upgrade, bump, or update a gem, or to review outdated gems.
allowed-tools	Bash Read Edit WebFetch AskUserQuestion

Gemfile Upgrade

Input

• ARG = gem_name (single gem) | --outdated (batch mode)

Workflow (single gem)

1. Check status:

   bundle outdated GEM --strict
   

   Parse: current, latest, jump type (patch/minor/major)

2. Locate repo:

   bundle info GEM --path   # check gemspec for homepage / source_code_uri
   

3. Fetch changelog via WebFetch (try in order, stop on first hit):

   • https://github.com/OWNER/REPO/releases
   • https://github.com/OWNER/REPO/blob/main/CHANGELOG.md
   • https://github.com/OWNER/REPO/blob/main/HISTORY.md
   • https://github.com/OWNER/REPO/blob/main/NEWS.md

4. Extract changes between current → target. Flag:

   • Major bumps (X.x → Y.x)
   • Keywords: BREAKING, removed, renamed, changed behavior
   • Migration guides
   • Ruby/Rails version requirements
   • Deprecations

5. Present analysis:

   ## Upgrade Analysis: GEM CURRENT → TARGET
   
   ### Version Jump: PATCH | MINOR | MAJOR
   ### Breaking Changes: [list]
   ### Migration Required: [steps]
   ### Deprecations: [list]
   ### New Features: [list]
   ### Compatibility: [Ruby/Rails reqs]
   

6. AskUserQuestion → options:

   • Upgrade to latest minor (recommended) — safer, bug fixes
   • Upgrade to latest (TARGET) — review breaking changes
   • Upgrade to specific version — prompt for version
   • Skip

7. Update Gemfile (Edit):

   # latest
   gem 'GEM', '~> MAJOR.MINOR'
   # minor only
   gem 'GEM', '~> CURRENT_MAJOR.CURRENT_MINOR'
   

8. Run update:

   bundle update GEM --conservative
   

   On failure → show conflicts, suggest dependent updates, offer rollback.

9. Run tests (auto-detect):

   if [ -f spec/spec_helper.rb ]; then bundle exec rspec
   elif [ -f test/test_helper.rb ]; then bundle exec rails test
   fi
   

   • Pass → step 10
   • Fail → show failures, AskUserQuestion: Rollback | Investigate

10. Commit:

    git add Gemfile Gemfile.lock
    git commit -m "$(cat <<'EOF'
    chore(deps): upgrade GEM from CURRENT to TARGET
    
    Breaking changes:
    - [list]
    
    Migration notes:
    - [steps taken]
    
    Changelog: URL
    EOF
    )"
    

Workflow (--outdated batch mode)

1. bundle outdated --strict
2. Group by jump type:
   • PATCH (X.Y.Z → X.Y.Z+1) — usually safe
   • MINOR (X.Y → X.Y+1) — review recommended
   • MAJOR (X → X+1) — careful review required
3. AskUserQuestion (multi-select) presenting all gems grouped by risk
4. For each selected gem → run single-gem workflow (steps 1-10)

Rollback

At any failure step:

git checkout -- Gemfile Gemfile.lock
bundle install

Safety Rules

• Always show diff before applying
• Create backup of Gemfile before edit (Edit tool preserves prior content via git)
• Never commit if tests fail
• Default to --conservative to avoid cascading updates
• Flag major version jumps explicitly in analysis