From 1c174a3c2f5058bd7e97019d21940f176ff1e798 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:13:36 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + commands/migration-helper.md | 623 +++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 +++ 4 files changed, 683 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/migration-helper.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..a507a40 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..91c7c9c --- /dev/null +++ b/README.md @@ -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 diff --git a/commands/migration-helper.md b/commands/migration-helper.md new file mode 100644 index 0000000..ac1710b --- /dev/null +++ b/commands/migration-helper.md @@ -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 ? : ; + } +} + +// 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 ? : ; +} +``` + +**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 ( + + {children} + + ); +} + +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: ` +
+ {{ user.name }} + +
+ ` +}) +export class UserListComponent implements OnInit { + users$: Observable; + + 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(); + const { container: after } = render(); + expect(before.innerHTML).toBe(after.innerHTML); + }); + + it('maintains state management', () => { + const { getByText } = render(); + fireEvent.click(getByText('Increment')); + expect(getByText('Count: 1')).toBeInTheDocument(); + }); + + it('handles lifecycle equivalents', async () => { + const fetchMock = jest.fn().mockResolvedValue({ data: 'test' }); + render(); + 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. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..4e7b90e --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file