gemfile-upgrade

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)

1. Locate repo:

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

1. 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

1. 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

1. 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]

1. 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

1. Update Gemfile (Edit):

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

1. Run update:

   bundle update GEM --conservative

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

1. 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

1. 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

1. AskUserQuestion (multi-select) presenting all gems grouped by risk
2. 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