zhongwei/gh-claudeforge-marketplace-plugins-commands-migration-helper
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-29 18:13:36 +08:00
commit 1c174a3c2f
4 changed files with 683 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "migration-helper",
"description": "ClaudeForge Enterprise Migration Architect delivering comprehensive framework upgrade methodologies, version migration strategies, codemod automation, and AST transformation frameworks that transform risky migrations into systematic, tested, and reversible code evolution processes",
"version": "1.0.0",
"author": {
"name": "ClaudeForge Community",
"url": "https://github.com/claudeforge/marketplace"
},
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# migration-helper
ClaudeForge Enterprise Migration Architect delivering comprehensive framework upgrade methodologies, version migration strategies, codemod automation, and AST transformation frameworks that transform risky migrations into systematic, tested, and reversible code evolution processes

623
commands/migration-helper.md Normal file
View File

@@ -0,0 +1,623 @@
---
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
description: ClaudeForge code migration assistant for framework upgrades, version migrations, and codebase transformations.
---
# ClaudeForge Migration Helper
ClaudeForge intelligent migration system that automates complex framework upgrades, version migrations, and codebase transformations with comprehensive AST analysis, automated codemods, and risk-free migration strategies.
## Purpose
Transform framework and version migrations from risky manual refactoring to intelligent, automated processes that ensure code quality, backward compatibility, and minimal downtime across large-scale codebases.
## Features
- **Framework Migration**: Automated migration between frameworks (React, Vue, Angular, etc.)
- **Version Upgrades**: Intelligent version upgrade paths with breaking change detection
- **Codemod Generation**: Custom codemod creation using AST transformations
- **Breaking Change Analysis**: Comprehensive detection of breaking changes and deprecations
- **Migration Planning**: Risk assessment and phased migration strategy generation
- **Rollback Support**: Automated rollback procedures with version control integration
- **Testing Integration**: Automated test generation and validation during migration
- **Documentation**: Migration guides and change logs with team communication templates
## Usage
```bash
/migration-helper [migration-type] [options]
```
Target: $ARGUMENTS (if specified, otherwise analyze current project)
### Migration Commands
**Framework Version Upgrade:**
```bash
/migration-helper upgrade --framework=react --from=16.8 --to=18.2
```
Performs comprehensive version upgrade including:
- Breaking change detection and analysis
- Deprecated API identification and replacement
- New feature adoption recommendations
- Package.json dependency updates
- Lock file regeneration
- Migration script generation with rollback support
**Framework Migration:**
```bash
/migration-helper migrate --from=vue2 --to=react --strategy=incremental
```
Migrates between frameworks with:
- Component structure transformation
- State management migration (Vuex → Redux/Context)
- Template syntax to JSX conversion
- Lifecycle method mapping
- Router configuration migration
- Build tool configuration updates
**Library Replacement:**
```bash
/migration-helper replace --library=moment --with=date-fns --preserve-behavior
```
Replaces libraries maintaining behavior:
- API usage pattern detection
- Automated code transformation
- Test case updates
- Import statement rewriting
- Type definition updates
- Behavior validation tests
### Codemod Operations
**Custom Codemod Generation:**
```bash
/migration-helper codemod --pattern="class components" --transform="functional" --scope=src/
```
Generates and applies codemods with:
- AST-based pattern matching
- Safe transformation rules
- Dry-run preview with diff output
- Selective file application
- Transformation validation
- Rollback checkpoints
**AST Transformation:**
```bash
/migration-helper transform --ast-query="CallExpression[callee.name='require']" --replace-with="import"
```
Performs AST-level transformations:
- Complex syntax tree queries
- Multi-file transformations
- Scope-aware replacements
- Type-safe transformations
- Formatting preservation
- Comment retention
**Breaking Change Detection:**
```bash
/migration-helper analyze --version-from=3.0 --version-to=4.0 --report=detailed
```
Analyzes breaking changes with:
- API signature change detection
- Deprecated feature usage scanning
- Type incompatibility identification
- Runtime behavior changes
- Configuration format changes
- Impact severity assessment
### Migration Strategies
**Incremental Migration:**
```bash
/migration-helper plan --strategy=incremental --duration=4-weeks --risk-level=low
```
Creates phased migration plan with:
- Module-by-module migration sequence
- Dual-version compatibility layer
- Feature flag integration
- Progressive rollout timeline
- Risk mitigation strategies
- Team coordination schedule
**Big Bang Migration:**
```bash
/migration-helper plan --strategy=big-bang --cutover-date=2024-03-15 --backup-plan
```
Plans complete migration with:
- Comprehensive preparation checklist
- Parallel environment setup
- Cutover procedure documentation
- Rollback decision criteria
- Post-migration validation
- Emergency response procedures
**Strangler Fig Pattern:**
```bash
/migration-helper strangler --routes-first --proxy-config --parallel-run
```
Implements strangler fig migration:
- Route-level migration strategy
- Proxy configuration for dual systems
- Parallel execution with comparison
- Gradual traffic shifting
- Legacy system decommissioning plan
- Data synchronization strategy
## Migration Methodologies
### React Migration Patterns
**Class to Functional Components:**
```javascript
// Before: Class component with lifecycle
class UserProfile extends React.Component {
state = { user: null, loading: true };
componentDidMount() {
this.fetchUser(this.props.userId);
}
componentDidUpdate(prevProps) {
if (prevProps.userId !== this.props.userId) {
this.fetchUser(this.props.userId);
}
}
fetchUser = async (userId) => {
const user = await api.getUser(userId);
this.setState({ user, loading: false });
};
render() {
return this.state.loading ? <Spinner /> : <User data={this.state.user} />;
}
}
// After: Functional component with hooks
function UserProfile({ userId }) {
const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
let cancelled = false;
async function fetchUser() {
const userData = await api.getUser(userId);
if (!cancelled) {
setUser(userData);
setLoading(false);
}
}
fetchUser();
return () => { cancelled = true; };
}, [userId]);
return loading ? <Spinner /> : <User data={user} />;
}
```
**Context API Migration:**
```javascript
// Legacy Context API
const ThemeContext = React.createContext();
class ThemeProvider extends React.Component {
static childContextTypes = {
theme: PropTypes.object
};
getChildContext() {
return { theme: this.props.theme };
}
}
// Modern Context API
const ThemeContext = React.createContext();
function ThemeProvider({ children, theme }) {
return (
<ThemeContext.Provider value={theme}>
{children}
</ThemeContext.Provider>
);
}
function useTheme() {
const theme = useContext(ThemeContext);
if (!theme) throw new Error('useTheme must be used within ThemeProvider');
return theme;
}
```
### Vue Migration Patterns
**Vue 2 to Vue 3 Composition API:**
```javascript
// Vue 2 Options API
export default {
data() {
return {
count: 0,
user: null
};
},
computed: {
doubleCount() {
return this.count * 2;
}
},
methods: {
increment() {
this.count++;
}
},
async mounted() {
this.user = await api.fetchUser();
}
};
// Vue 3 Composition API
import { ref, computed, onMounted } from 'vue';
export default {
setup() {
const count = ref(0);
const user = ref(null);
const doubleCount = computed(() => count.value * 2);
function increment() {
count.value++;
}
onMounted(async () => {
user.value = await api.fetchUser();
});
return { count, user, doubleCount, increment };
}
};
```
### Angular Migration Patterns
**AngularJS to Angular:**
```typescript
// AngularJS Controller
angular.module('app').controller('UserController', function($scope, UserService) {
$scope.users = [];
UserService.getUsers().then(function(users) {
$scope.users = users;
});
$scope.deleteUser = function(userId) {
UserService.delete(userId).then(function() {
$scope.users = $scope.users.filter(u => u.id !== userId);
});
};
});
// Angular Component
@Component({
selector: 'app-user-list',
template: `
<div *ngFor="let user of users$ | async">
{{ user.name }}
<button (click)="deleteUser(user.id)">Delete</button>
</div>
`
})
export class UserListComponent implements OnInit {
users$: Observable<User[]>;
constructor(private userService: UserService) {}
ngOnInit() {
this.users$ = this.userService.getUsers();
}
deleteUser(userId: string) {
this.userService.delete(userId).pipe(
switchMap(() => this.userService.getUsers())
).subscribe(users => this.users$ = of(users));
}
}
```
## Codemod Tools Integration
### jscodeshift Usage
**Custom Codemod Example:**
```javascript
// transform-class-to-hooks.js
module.exports = function transformer(file, api) {
const j = api.jscodeshift;
const root = j(file.source);
// Find class components
root.find(j.ClassDeclaration, {
superClass: {
type: 'MemberExpression',
object: { name: 'React' },
property: { name: 'Component' }
}
}).forEach(path => {
const componentName = path.value.id.name;
// Extract state
const stateProperties = extractState(path);
// Extract lifecycle methods
const effects = extractEffects(path);
// Generate functional component
const functionalComponent = buildFunctionalComponent(
componentName,
stateProperties,
effects
);
j(path).replaceWith(functionalComponent);
});
return root.toSource({ quote: 'single' });
};
```
**Running Codemods:**
```bash
# Apply transformation
npx jscodeshift -t transform-class-to-hooks.js src/components
# Dry run to preview changes
npx jscodeshift -t transform.js src/ --dry --print
# Transform with TypeScript parser
npx jscodeshift -t transform.js src/ --parser=tsx
```
### ts-migrate Integration
**TypeScript Migration:**
```bash
# Initialize TypeScript migration
npx ts-migrate init
# Add TypeScript configs
npx ts-migrate-server --config-file tsconfig.json
# Rename files to .ts/.tsx
npx ts-migrate rename src/
# Add @ts-expect-error comments
npx ts-migrate migrate src/
# Run type checking and fix
npx tsc --noEmit && npx ts-migrate reignore src/
```
### AST Explorer Integration
**Interactive Transformation Development:**
- Real-time AST visualization at astexplorer.net
- Test transformations before production use
- Support for multiple parsers (babel, typescript, flow)
- jscodeshift template generation
- Share transformations with team
## Migration Planning Framework
### Risk Assessment Matrix
**Risk Categories:**
```
High Risk:
- Breaking changes in core dependencies
- Major framework version jumps (e.g., React 16 → 18)
- Database schema migrations
- Authentication/security changes
- Payment processing updates
Medium Risk:
- Minor version upgrades with deprecations
- State management library changes
- Build tool migrations
- UI library updates
- Testing framework changes
Low Risk:
- Patch version updates
- Development dependency updates
- Code style/linting changes
- Documentation updates
- Internal utility refactoring
```
### Migration Checklist
**Pre-Migration Phase:**
- [ ] Comprehensive test coverage (minimum 80%)
- [ ] Feature freeze on affected modules
- [ ] Full database backup and restore test
- [ ] Dependency audit and vulnerability scan
- [ ] Performance baseline measurements
- [ ] Rollback procedure documentation
- [ ] Team training and knowledge transfer
- [ ] Communication plan to stakeholders
**Migration Phase:**
- [ ] Branch protection and code freeze
- [ ] Automated migration script execution
- [ ] Incremental commit strategy
- [ ] Continuous integration pipeline validation
- [ ] Manual QA testing of critical paths
- [ ] Performance regression testing
- [ ] Security vulnerability scanning
- [ ] Documentation updates
**Post-Migration Phase:**
- [ ] Production deployment with canary release
- [ ] Real-time monitoring and alerting
- [ ] User acceptance testing
- [ ] Performance comparison with baseline
- [ ] Legacy code cleanup
- [ ] Post-mortem and lessons learned
- [ ] Knowledge base article creation
- [ ] Celebration of successful migration
## Testing Strategy
### Automated Testing
**Migration Test Suite:**
```javascript
describe('Migration: Class to Hooks', () => {
it('preserves component behavior', () => {
const { container: before } = render(<ClassComponent />);
const { container: after } = render(<HooksComponent />);
expect(before.innerHTML).toBe(after.innerHTML);
});
it('maintains state management', () => {
const { getByText } = render(<HooksComponent />);
fireEvent.click(getByText('Increment'));
expect(getByText('Count: 1')).toBeInTheDocument();
});
it('handles lifecycle equivalents', async () => {
const fetchMock = jest.fn().mockResolvedValue({ data: 'test' });
render(<HooksComponent fetch={fetchMock} />);
await waitFor(() => expect(fetchMock).toHaveBeenCalled());
});
});
```
**Visual Regression Testing:**
```javascript
// Chromatic integration
describe('Visual Regression', () => {
it('matches previous component appearance', async () => {
await page.goto('http://localhost:6006/iframe.html?id=migrated-component');
const screenshot = await page.screenshot();
expect(screenshot).toMatchImageSnapshot({
failureThreshold: 0.01,
failureThresholdType: 'percent'
});
});
});
```
### Manual Testing Guides
**Critical Path Testing:**
```markdown
## User Authentication Flow
1. Navigate to login page
2. Enter valid credentials
3. Verify redirect to dashboard
4. Check user profile information
5. Test logout functionality
## Payment Processing
1. Add items to cart
2. Proceed to checkout
3. Enter payment information
4. Verify payment confirmation
5. Check order history
## Data Export Feature
1. Navigate to export page
2. Select date range
3. Choose export format
4. Download file
5. Verify file contents
```
## CI/CD Integration
### GitHub Actions Migration Workflow
```yaml
name: Framework Migration
on:
workflow_dispatch:
inputs:
migration_type:
description: 'Migration type'
required: true
type: choice
options:
- react-upgrade
- vue-migration
- angular-update
jobs:
migrate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Create migration branch
run: |
git checkout -b migration/${{ github.event.inputs.migration_type }}-$(date +%Y%m%d)
- name: Install dependencies
run: npm ci
- name: Run migration scripts
run: npm run migrate:${{ github.event.inputs.migration_type }}
- name: Run tests
run: npm test
- name: Build project
run: npm run build
- name: Commit changes
run: |
git config user.name "Migration Bot"
git config user.email "bot@example.com"
git add .
git commit -m "chore: automated migration - ${{ github.event.inputs.migration_type }}"
- name: Create pull request
uses: peter-evans/create-pull-request@v5
with:
title: "Migration: ${{ github.event.inputs.migration_type }}"
body: |
## Automated Migration
Migration type: ${{ github.event.inputs.migration_type }}
Date: $(date)
### Changes
- Framework/library updates
- Code transformations via codemods
- Test suite updates
### Testing Required
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual QA complete
- [ ] Performance benchmarks reviewed
branch: migration/${{ github.event.inputs.migration_type }}-$(date +%Y%m%d)
```
---
**ClaudeForge Migration Helper** - Intelligent framework migration with automated codemods, comprehensive testing, and risk-free transformation strategies for modern development teams.

45
plugin.lock.json Normal file
View File

@@ -0,0 +1,45 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:claudeforge/marketplace:plugins/commands/migration-helper",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "5faae45d5a7d0233213b72e1b7adee034f6e44f8",
"treeHash": "55fd0babf1a375a4f5537b0dd3695b6254c40866b524309114c84bcae689d1a6",
"generatedAt": "2025-11-28T10:15:33.379531Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "migration-helper",
"description": "ClaudeForge Enterprise Migration Architect delivering comprehensive framework upgrade methodologies, version migration strategies, codemod automation, and AST transformation frameworks that transform risky migrations into systematic, tested, and reversible code evolution processes",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "c09b73a513777c746060d827b1cec8efc5b959ccb6c6e2202eb4192b75019e3b"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "9d9f5cc6eb1fa604580c35add84e2cf585cd68ecbafe7c98c71050b514d6964e"
},
{
"path": "commands/migration-helper.md",
"sha256": "476cc9c9fc7867785597dac262a1790c351f2878eb4b96b5f897719f900e1953"
}
],
"dirSha256": "55fd0babf1a375a4f5537b0dd3695b6254c40866b524309114c84bcae689d1a6"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}