metabuilder/docs/refactoring/REFACTORING_CHECKLIST.md

Refactoring Implementation Checklist

Phase 1: Violation #1 - GitHubActionsFetcher.tsx

Database Setup

• Add GitHubWorkflowRun model to schema
• Add GitHubWorkflowJob model to schema
• Add GitHubConfig model to schema
• Run npm run db:generate
• Run npm run db:push
• Create database migration file
• Seed initial GitHub config

Hook Development (useGitHubActions)

• Create src/hooks/useGitHubActions.ts
• Implement Octokit integration
• Add database caching logic
• Implement auto-refresh polling
• Add error handling
• Write unit tests
• Add TypeScript types

Hook Development (useWorkflowLogs)

• Create src/hooks/useWorkflowLogs.ts
• Implement log fetching from GitHub API
• Add log aggregation logic
• Handle different log formats
• Implement file download
• Write unit tests

Hook Development (useWorkflowAnalysis)

• Create src/hooks/useWorkflowAnalysis.ts
• Implement LLM API integration
• Add result caching
• Format markdown output
• Write unit tests

Lua Scripts

• Create FilterWorkflowRuns script
• Create AggregateJobLogs script
• Create AnalyzeWorkflowPatterns script
• Seed scripts to database
• Test script execution

UI Configuration

• Define status colors in JSON
• Define column definitions
• Define tab configuration
• Store in database or seed file
• Create config loader function

Component Refactoring

• Create GitHubActionsToolbar.tsx
• Create GitHubActionsRunRow.tsx
• Create GitHubActionsRunsList.tsx
• Create GitHubActionsJobStep.tsx
• Create GitHubActionsJobsPanel.tsx
• Create GitHubActionsAnalysisPanel.tsx
• Refactor GitHubActionsFetcher.tsx to <150 LOC

Testing

• Unit test each hook
• Unit test each component
• Integration test component composition
• E2E test full workflow
• Test error scenarios
• Test auto-refresh
• Test log download

Documentation

• Document hook APIs
• Document component props
• Add JSDoc comments
• Create usage examples
• Document Lua scripts

---

Phase 2: Violation #2 - NerdModeIDE.tsx

Database Setup

• Add IDEProject model
• Add IDEFile model
• Add GitConfig model (update if already exists)
• Add IDETestRun model
• Run migrations
• Seed sample project data

Hook Development (useIDEProject)

• Create src/hooks/useIDEProject.ts
• Implement project loading
• Implement project metadata updates
• Add error handling
• Write unit tests

Hook Development (useIDEFileTree)

• Create src/hooks/useIDEFileTree.ts
• Implement file create operation
• Implement file delete operation
• Implement file update operation
• Implement folder toggle
• Implement tree traversal
• Add database persistence
• Write unit tests

Hook Development (useIDEEditor)

• Create src/hooks/useIDEEditor.ts
• Implement file selection state
• Implement content state
• Implement save logic
• Implement language detection
• Write unit tests

Hook Development (useIDEGit)

• Create src/hooks/useIDEGit.ts
• Implement config management
• Implement token encryption/decryption
• Implement push/pull operations
• Implement commit operation
• Write unit tests

Hook Development (useIDETest)

• Create src/hooks/useIDETest.ts
• Implement test execution
• Implement result caching
• Implement history tracking
• Write unit tests

Lua Scripts

• Create FileTreeOperations script
• Create LanguageDetection script
• Create RunCodeAnalysis script
• Seed to database
• Test execution

Component Refactoring

• Create IDEFileTreeNode.tsx
• Create IDEFileTreePanel.tsx
• Create IDEEditorPanel.tsx
• Create IDEToolbar.tsx
• Create IDEConsolePanel.tsx
• Create IDEGitDialog.tsx
• Create IDENewFileDialog.tsx
• Refactor NerdModeIDE.tsx to <150 LOC

Testing

• Test file creation
• Test file deletion
• Test file editing
• Test folder expansion/collapse
• Test git config
• Test code execution
• Test console output
• E2E test complete workflow

---

Phase 3: Violation #3 - LuaEditor.tsx

Database Setup

• Update LuaScript model with description
• Add LuaScriptParameter model
• Add LuaTestRun model
• Run migrations
• Seed example scripts

Configuration Extraction

• Create LuaMonacoConfig.tsx
• Move autocomplete suggestions (60+ LOC)
• Move language configuration
• Move bracket matching config
• Export reusable functions
• Test Monaco integration

Hook Development (useLuaScripts)

• Create src/hooks/useLuaScripts.ts
• Implement script CRUD
• Add database persistence
• Write unit tests

Hook Development (useLuaEditor)

• Create src/hooks/useLuaEditor.ts
• Implement selection state
• Implement code state
• Write unit tests

Hook Development (useLuaExecution)

• Create src/hooks/useLuaExecution.ts
• Implement execution
• Implement result caching
• Implement history
• Write unit tests

Hook Development (useLuaSecurity)

• Create src/hooks/useLuaSecurity.ts
• Integrate security scanner
• Implement warning state
• Write unit tests

Component Refactoring

• Create LuaScriptSelector.tsx
• Create LuaCodeEditor.tsx
• Create LuaParameterItem.tsx
• Create LuaParametersPanel.tsx
• Create LuaExecutionResult.tsx
• Create LuaExecutionPanel.tsx
• Create LuaSecurityWarningDialog.tsx
• Create LuaSnippetLibraryPanel.tsx
• Refactor LuaEditor.tsx to <150 LOC

Testing

• Test script creation
• Test script deletion
• Test parameter management
• Test script execution
• Test security scanning
• Test snippet insertion
• Test error display
• E2E test complete workflow

---

General Tasks

Code Quality

• Run ESLint on all new files
• Run TypeScript type check
• No unused imports
• No console.log statements
• Proper error handling
• JSDoc comments on all public functions

Testing

• 80%+ code coverage
• All critical paths tested
• Error scenarios tested
• Edge cases tested
• E2E tests passing
• No flaky tests

Performance

• Profile component renders
• Optimize re-renders
• Cache expensive computations
• Lazy load where possible
• Measure bundle size impact

Security

• No hardcoded secrets
• Tokens properly encrypted
• Input validation
• XSS prevention
• CSRF protection if needed

Documentation

• README for each hook
• Props documentation for each component
• Example usage in comments
• Update main project README
• Migration guide for breaking changes

Database

• Migration files created
• Seed files created
• Indexes added for common queries
• Prisma types generated
• No N+1 queries

---

Validation Checklist

Before Merge

• All tests passing
• No regressions in existing features
• Code review approved
• No breaking changes (or documented)
• Documentation complete
• Performance acceptable

Before Deploy

• Staging environment tested
• Database backed up
• Rollback plan documented
• Monitoring set up
• On-call engineer available
• Change log updated

Post Deploy

• Monitor error rates
• Check performance metrics
• User feedback collection
• Fix any critical issues
• Close related issues
• Celebrate! 🎉

---

Metrics to Track

Code Metrics

• LOC per component (target: <150)
• Number of components
• Number of hooks
• Test coverage percentage
• Number of bugs found

Performance Metrics

• Component render time (target: <100ms)
• Database query time (target: <50ms)
• Bundle size increase
• Memory usage
• Time to interactive

Quality Metrics

• ESLint violations
• TypeScript errors
• Code review iterations
• Defect escape rate
• Performance regressions

---

Notes

• Estimate each task in hours
• Update as work progresses
• Track blockers and dependencies
• Schedule code reviews early
• Plan testing strategy upfront
• Communicate progress regularly
• Celebrate milestones!