zhongwei/gh-martybonacci-specswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:39:24 +08:00
commit 7e16d8a2a1
40 changed files with 16981 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

631
commands/upgrade.md Normal file
View File

@@ -0,0 +1,631 @@
---
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