---
description: Upgrade dependencies or frameworks with breaking change analysis and automated refactoring
args:
  - name: upgrade_target
    description: What to upgrade (e.g., "React 18 to React 19", "all dependencies", "react", "@latest")
    required: true
  - name: --deps
    description: Upgrade all dependencies to latest (alternative to specifying target)
    required: false
  - name: --package
    description: Upgrade specific package (e.g., --package react)
    required: false
  - name: --dry-run
    description: Analyze breaking changes without making changes
    required: false
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Goal

Upgrade dependencies or frameworks with automated breaking change analysis and code refactoring.

**Purpose**: Streamline complex upgrade processes by automating dependency updates, breaking change detection, and code refactoring.

**Workflow**: Analyze → Plan → Update → Refactor → Test → Report

**Scope**:
- Framework upgrades (React 18→19, Vue 2→3, Next.js 13→14, etc.)
- Dependency upgrades (specific packages or all dependencies)
- Breaking change detection from changelogs
- Automated code refactoring for breaking changes
- Test validation after upgrade

**User Experience**:
- Single command handles complex multi-step upgrades
- Automatic breaking change detection
- Guided refactoring with codemod suggestions
- Test-driven validation
- Clear migration report with manual tasks

---

## Pre-Flight Checks

```bash
# Parse arguments
UPGRADE_TARGET=""
UPGRADE_ALL_DEPS=false
PACKAGE_NAME=""
DRY_RUN=false

# Extract upgrade target (first non-flag argument)
for arg in $ARGUMENTS; do
  if [ "${arg:0:2}" != "--" ] && [ -z "$UPGRADE_TARGET" ]; then
    UPGRADE_TARGET="$arg"
  elif [ "$arg" = "--deps" ]; then
    UPGRADE_ALL_DEPS=true
  elif [ "$arg" = "--package" ]; then
    shift
    PACKAGE_NAME="$1"
  elif [ "$arg" = "--dry-run" ]; then
    DRY_RUN=true
  fi
done

# Validate upgrade target
if [ -z "$UPGRADE_TARGET" ] && [ "$UPGRADE_ALL_DEPS" = false ] && [ -z "$PACKAGE_NAME" ]; then
  echo "❌ Error: Upgrade target required"
  echo ""
  echo "Usage: /specswarm:upgrade \"target\" [--deps] [--package name] [--dry-run]"
  echo ""
  echo "Examples:"
  echo "  /specswarm:upgrade \"React 18 to React 19\""
  echo "  /specswarm:upgrade \"Next.js 14 to Next.js 15\""
  echo "  /specswarm:upgrade --deps                    # All dependencies"
  echo "  /specswarm:upgrade --package react           # Specific package"
  echo "  /specswarm:upgrade \"Vue 2 to Vue 3\" --dry-run"
  exit 1
fi

# Normalize upgrade target
if [ "$UPGRADE_ALL_DEPS" = true ]; then
  UPGRADE_TARGET="all dependencies"
elif [ -n "$PACKAGE_NAME" ]; then
  UPGRADE_TARGET="$PACKAGE_NAME to latest"
fi

# Get project root
if ! git rev-parse --git-dir > /dev/null 2>&1; then
  echo "❌ Error: Not in a git repository"
  exit 1
fi

REPO_ROOT=$(git rev-parse --show-toplevel)
cd "$REPO_ROOT"

# Check for package.json
if [ ! -f "package.json" ]; then
  echo "❌ Error: package.json not found"
  echo "   This command currently supports Node.js/npm projects."
  exit 1
fi
```

---

## Execution Steps

### Step 1: Display Welcome Banner

```bash
if [ "$DRY_RUN" = true ]; then
  echo "🔍 SpecSwarm Upgrade - Analysis Mode (Dry Run)"
else
  echo "⬆️  SpecSwarm Upgrade - Dependency & Framework Migration"
fi
echo "══════════════════════════════════════════"
echo ""
echo "Upgrade: $UPGRADE_TARGET"
echo ""

if [ "$DRY_RUN" = true ]; then
  echo "🔍 DRY RUN MODE: Analyzing only, no changes will be made"
  echo ""
  echo "This analysis will:"
  echo "  1. Detect current versions"
  echo "  2. Identify latest available versions"
  echo "  3. Analyze breaking changes from changelogs"
  echo "  4. Estimate refactoring impact"
  echo "  5. Generate migration plan"
  echo ""
else
  echo "This workflow will:"
  echo "  1. Analyze breaking changes"
  echo "  2. Generate migration plan"
  echo "  3. Update dependencies"
  echo "  4. Refactor code for breaking changes"
  echo "  5. Run tests to verify compatibility"
  echo "  6. Report manual migration tasks"
  echo ""
fi

read -p "Press Enter to start, or Ctrl+C to cancel..."
echo ""
```

---

### Step 2: Phase 1 - Analyze Current State

**YOU MUST NOW analyze the current dependency state:**

```bash
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🔍 Phase 1: Analyzing Current Dependencies"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
```

**Analysis steps:**

1. Read package.json to get current dependencies
2. Identify the packages to upgrade:
   - If UPGRADE_ALL_DEPS: all dependencies + devDependencies
   - If PACKAGE_NAME: specific package
   - If upgrade target like "React 18 to React 19": extract package names (react, react-dom, etc.)

3. For each package, detect:
   - Current version (from package.json)
   - Latest version (from npm registry)
   - Installed version (from package-lock.json or node_modules)

4. Check for framework-specific packages:
   - React: react, react-dom, @types/react
   - Vue: vue, @vue/*, vue-router
   - Next.js: next, react, react-dom
   - Remix: @remix-run/*
   - Angular: @angular/*

```bash
# Example analysis output
echo "📦 Current Versions:"
echo "   react: 18.2.0"
echo "   react-dom: 18.2.0"
echo "   @types/react: 18.0.28"
echo ""
echo "📦 Target Versions:"
echo "   react: 19.0.0"
echo "   react-dom: 19.0.0"
echo "   @types/react: 19.0.0"
echo ""
```

Store:
- PACKAGES_TO_UPGRADE (array of package names)
- CURRENT_VERSIONS (map of package → version)
- TARGET_VERSIONS (map of package → version)

---

### Step 3: Phase 2 - Breaking Change Analysis

**YOU MUST NOW analyze breaking changes:**

```bash
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📋 Phase 2: Analyzing Breaking Changes"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Fetching changelogs and release notes..."
echo ""
```

**For each package being upgraded:**

1. **Fetch changelog/release notes:**
   - Check GitHub releases (if repository URL in package.json)
   - Check npm package page
   - Use WebFetch tool to get changelog content

2. **Extract breaking changes:**
   - Look for "BREAKING CHANGE", "Breaking Changes", "⚠️", "❗" sections
   - Extract version-specific breaking changes (between current and target)
   - Parse common patterns:
     - "Removed X"
     - "X is now Y"
     - "X has been deprecated"
     - "X no longer supports Y"

3. **Categorize breaking changes:**
   - **API changes**: Function signature changes, removed methods
   - **Behavior changes**: Default behavior modifications
   - **Deprecations**: Deprecated but still working
   - **Removals**: Features completely removed
   - **Configuration**: Config file format changes

4. **Assess impact on codebase:**
   - Search codebase for usage of affected APIs
   - Estimate files requiring manual changes
   - Identify automated refactoring opportunities

```bash
echo "🔍 Breaking Changes Detected:"
echo ""
echo "React 18 → 19:"
echo "  ⚠️  ReactDOM.render removed (use createRoot)"
echo "  ⚠️  Legacy Context API deprecated"
echo "  ⚠️  PropTypes moved to separate package"
echo "  ✅ Automatic migration available for 2/3 changes"
echo ""
echo "Impact Analysis:"
echo "  📁 3 files use ReactDOM.render"
echo "  📁 1 file uses Legacy Context"
echo "  📁 0 files use PropTypes"
echo ""
```

Store:
- BREAKING_CHANGES (array of change descriptions)
- AFFECTED_FILES (map of change → files)
- AUTO_FIXABLE (array of changes with codemods available)

---

### Step 4: Phase 3 - Generate Migration Plan

**YOU MUST NOW generate a detailed migration plan:**

```bash
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📝 Phase 3: Generating Migration Plan"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
```

**Create a migration plan that includes:**

1. **Dependency Update Steps:**
   ```
   npm install react@19 react-dom@19 @types/react@19
   ```

2. **Automated Refactoring Steps:**
   - For each auto-fixable breaking change
   - Codemod command or manual find/replace pattern
   - Example: `npx react-codemod create-root src/`

3. **Manual Migration Tasks:**
   - For each non-auto-fixable breaking change
   - Which files need manual updates
   - What changes to make
   - Code examples (before/after)

4. **Test Validation:**
   - Test commands to run after changes
   - Expected test results

5. **Risk Assessment:**
   - Low/Medium/High risk rating
   - Estimated time
   - Recommended approach (all at once vs incremental)

```bash
echo "Migration Plan Generated:"
echo ""
echo "1. Update Dependencies (automated)"
echo "   └─ npm install react@19 react-dom@19"
echo ""
echo "2. Automated Refactoring (3 codemods)"
echo "   └─ ReactDOM.render → createRoot"
echo "   └─ Legacy Context → New Context API"
echo "   └─ Update TypeScript types"
echo ""
echo "3. Manual Tasks (1 required)"
echo "   └─ Review and test Legacy Context migration in src/contexts/ThemeContext.tsx"
echo ""
echo "4. Test Validation"
echo "   └─ npm test (all tests must pass)"
echo ""
echo "Risk Assessment: MEDIUM"
echo "Estimated Time: 15-30 minutes"
echo ""
```

IF DRY_RUN = true:
  - Stop here, display plan, exit
  - Do NOT make any changes

---

### Step 5: Phase 4 - Update Dependencies

**IF NOT dry run, YOU MUST NOW update dependencies:**

```bash
if [ "$DRY_RUN" = false ]; then
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "📦 Phase 4: Updating Dependencies"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
fi
```

**Use Bash tool to run npm install:**

```bash
# Build install command
INSTALL_CMD="npm install"

for package in "${PACKAGES_TO_UPGRADE[@]}"; do
  target_version="${TARGET_VERSIONS[$package]}"
  INSTALL_CMD="$INSTALL_CMD $package@$target_version"
done

echo "Running: $INSTALL_CMD"
echo ""

# Execute
$INSTALL_CMD

if [ $? -eq 0 ]; then
  echo ""
  echo "✅ Dependencies updated successfully"
  echo ""
else
  echo ""
  echo "❌ Dependency update failed"
  echo "   Check npm output above for errors"
  exit 1
fi
```

---

### Step 6: Phase 5 - Automated Refactoring

**IF NOT dry run, YOU MUST NOW apply automated refactorings:**

```bash
if [ "$DRY_RUN" = false ]; then
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "🔧 Phase 5: Automated Refactoring"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
fi
```

**For each auto-fixable breaking change:**

1. **Apply codemod** (if available):
   - React: `npx react-codemod <codemod-name> <path>`
   - Vue: `npx vue-codemod <codemod-name> <path>`
   - Other: Custom find/replace using Edit tool

2. **Apply manual refactoring patterns:**
   - Use Grep tool to find affected code
   - Use Edit tool to make changes
   - Log each change for rollback if needed

3. **Verify changes:**
   - Check syntax (bash -n for shell, tsc --noEmit for TypeScript)
   - Quick validation that files parse correctly

```bash
echo "Applying refactoring 1/3: ReactDOM.render → createRoot"
# Apply codemod or manual refactoring
echo "✅ Refactored 3 files"
echo ""

echo "Applying refactoring 2/3: Legacy Context → New Context API"
# Apply codemod or manual refactoring
echo "✅ Refactored 1 file"
echo ""

echo "Applying refactoring 3/3: Update TypeScript types"
# Apply codemod or manual refactoring
echo "✅ Updated type definitions"
echo ""
```

---

### Step 7: Phase 6 - Test Validation

**IF NOT dry run, YOU MUST NOW run tests:**

```bash
if [ "$DRY_RUN" = false ]; then
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "✓ Phase 6: Testing Compatibility"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
fi
```

**Run test suite:**

1. Detect test command (package.json scripts.test)
2. Run tests with Bash tool
3. Capture results
4. Report pass/fail

```bash
echo "Running test suite..."
echo ""

npm test

TEST_RESULT=$?

if [ $TEST_RESULT -eq 0 ]; then
  echo ""
  echo "✅ All tests passing after upgrade!"
  echo ""
  TESTS_PASSING=true
else
  echo ""
  echo "⚠️  Some tests failing after upgrade"
  echo "   This may be expected for breaking changes requiring manual migration"
  echo ""
  TESTS_PASSING=false
fi
```

---

### Step 8: Final Report

**Display completion summary:**

```bash
echo ""
echo "══════════════════════════════════════════"

if [ "$DRY_RUN" = true ]; then
  echo "🔍 UPGRADE ANALYSIS COMPLETE (DRY RUN)"
  echo "══════════════════════════════════════════"
  echo ""
  echo "Upgrade: $UPGRADE_TARGET"
  echo ""
  echo "📋 Migration Plan Ready"
  echo "📊 Risk Assessment: [RISK_LEVEL]"
  echo "⏱️  Estimated Time: [TIME_ESTIMATE]"
  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "📝 NEXT STEPS"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
  echo "1. Review migration plan above"
  echo "2. If acceptable, run actual upgrade:"
  echo "   /specswarm:upgrade \"$UPGRADE_TARGET\""
  echo ""
  echo "3. Or handle migration manually using plan as guide"
  echo ""
else
  echo "🎉 UPGRADE COMPLETE"
  echo "══════════════════════════════════════════"
  echo ""
  echo "Upgrade: $UPGRADE_TARGET"
  echo ""
  echo "✅ Dependencies updated"
  echo "✅ Automated refactoring applied"

  if [ "$TESTS_PASSING" = true ]; then
    echo "✅ All tests passing"
  else
    echo "⚠️  Tests require attention (see output above)"
  fi

  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "📝 MANUAL TASKS REMAINING"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""

  # List manual tasks from migration plan
  echo "The following tasks require manual intervention:"
  echo ""
  for task in "${MANUAL_TASKS[@]}"; do
    echo "  ⚠️  $task"
  done

  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "🧪 RECOMMENDED TESTING"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
  echo "1. 🔍 Review Changes"
  echo "   git diff"
  echo ""
  echo "2. 🧪 Manual Testing"
  echo "   - Start development server"
  echo "   - Test critical user flows"
  echo "   - Verify no console errors"
  echo "   - Check for visual regressions"
  echo ""
  echo "3. 📊 Performance Check"
  echo "   - Compare bundle size (if applicable)"
  echo "   - Verify no performance degradation"
  echo ""

  if [ "$TESTS_PASSING" = true ]; then
    echo "4. 🚢 Ship When Ready"
    echo "   /specswarm:ship"
    echo ""
    echo "   All tests passing - ready to merge after manual verification"
  else
    echo "4. 🔧 Fix Failing Tests"
    echo "   - Address test failures"
    echo "   - Complete manual migration tasks above"
    echo "   - Re-run: npm test"
    echo ""
    echo "5. 🚢 Ship When Tests Pass"
    echo "   /specswarm:ship"
  fi

  echo ""
fi

echo "══════════════════════════════════════════"
```

---

## Error Handling

If any step fails:

1. **Changelog fetch fails**: Continue with generic breaking change warnings
2. **Dependency update fails**: Display npm errors, suggest manual resolution
3. **Refactoring fails**: Roll back changes, report errors
4. **Tests fail**: Report as warning, not error (expected for breaking changes)

**All errors should report clearly and suggest remediation.**

---

## Design Philosophy

**Automated Where Possible**: Codemods and refactoring patterns reduce manual work

**Transparent Process**: Clear breaking change analysis before making changes

**Safety First**: Dry run mode for risk assessment, test validation after changes

**Guidance**: Manual tasks clearly documented with examples

**Realistic**: Acknowledges that some migrations require manual intervention

---

## Use Cases

**Framework Upgrades:**
- React 18 → 19
- Vue 2 → 3
- Next.js 14 → 15
- Angular major versions

**Dependency Upgrades:**
- All dependencies to latest
- Specific package upgrades
- Security vulnerability fixes

**Breaking Change Migrations:**
- API removals
- Configuration format changes
- Behavior modifications

---

## Limitations

**Current Support:**
- ✅ Node.js/npm projects (package.json)
- ✅ React framework upgrades
- ✅ Common JavaScript libraries

**Future Enhancements:**
- Python (pip, requirements.txt)
- Ruby (Gemfile)
- Rust (Cargo.toml)
- More framework-specific codemods
- Automated rollback on test failure