mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-05-03 10:14:52 +00:00
docs: plan,migration,master (1 files)
This commit is contained in:
Richard Ward
@@ -0,0 +1,428 @@
|
||||
# MetaBuilder Master Migration Plan
|
||||
**Comprehensive Phased Approach to UI Independence**
|
||||
|
||||
**Created:** 2025-12-30
|
||||
**Status:** Active Development
|
||||
**Owner:** Automated Migration System
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
| Area | Current State | Target State |
|
||||
|------|---------------|--------------|
|
||||
| @mui/material | 20+ files still importing | ❌ Removed completely |
|
||||
| @mui/icons-material | ✅ Eliminated from source | ✅ Complete |
|
||||
| @phosphor-icons/react | In package.json | ❌ Removed |
|
||||
| fakemui icons | 357+ icons | 400+ icons |
|
||||
| fakemui components | ~160 components | 200+ (full MUI parity) |
|
||||
| Lua packages typed | ✅ All 43 packages | ✅ Complete |
|
||||
| Lua packages tested | 40/43 packages | All packages |
|
||||
| Dependencies | Heavy (2-3MB MUI) | Minimal |
|
||||
| Bundle size | Large | Reduced 15-25% |
|
||||
|
||||
---
|
||||
|
||||
## Phase Overview (12 Micro-Phases)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 1: Missing Tests [Hours: 2-4] │
|
||||
│ - Add tests to shared, config_summary, lua_test │
|
||||
│ - Ensure all test files have .cases.json parameterized data │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 2: Fakemui Component Gaps [Hours: 4-8] │
|
||||
│ - Add ToggleButtonGroup wrapper │
|
||||
│ - Add missing utility components (VirtualList, etc.) │
|
||||
│ - Ensure all MUI equivalents exist │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 3: Frontends MUI Elimination [Hours: 8-16] │
|
||||
│ - Migrate 20+ files from @mui/material to fakemui │
|
||||
│ - Update workflow/* components │
|
||||
│ - Update ui/molecules/* components │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 4: Fakemui Icons Expansion [Hours: 2-4] │
|
||||
│ - Add any remaining icons from usage audit │
|
||||
│ - Update icon index exports │
|
||||
│ - Document icon naming conventions │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 5: Package Validator Compliance [Hours: 2-4] │
|
||||
│ - Run validator on all 43 packages │
|
||||
│ - Fix any validation errors │
|
||||
│ - Update validator rules if needed │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 6: Lua Package Permissions System [Hours: 4-8] │
|
||||
│ - Add database toggle to packages │
|
||||
│ - Add component on/off switches │
|
||||
│ - Implement minLevel enforcement in renderer │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 7: CSS/Style System via Lua [Hours: 4-8] │
|
||||
│ - Create css_designer Lua package │
|
||||
│ - Enable style overlays via seed data │
|
||||
│ - Theme customization via database │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 8: Legacy TSX to Lua Conversion [Hours: 8-16] │
|
||||
│ - Convert hardcoded TSX to Lua packages │
|
||||
│ - Create new packages as needed │
|
||||
│ - Wire components to Lua renderer │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 9: Monaco/Markdown Fakemui Integration [Hours: 4-8] │
|
||||
│ - Create Monaco wrapper in fakemui │
|
||||
│ - Create Markdown renderer in fakemui │
|
||||
│ - Reduce external dependencies │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 10: Multi-Frontend Support [Hours: 8-16] │
|
||||
│ - Qt6/QML powered by generic packages │
|
||||
│ - CLI frontend integration │
|
||||
│ - Abstract package rendering layer │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 11: Dependency Cleanup [Hours: 2-4] │
|
||||
│ - Remove @mui/* from package.json │
|
||||
│ - Remove @emotion/* from package.json │
|
||||
│ - Remove @phosphor-icons/react │
|
||||
│ - Verify build still works │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ PHASE 12: Verification & Polish [Hours: 4-8] │
|
||||
│ - Playwright E2E tests │
|
||||
│ - Enable packages one at a time │
|
||||
│ - Final cleanup and documentation │
|
||||
│ - Notify completion │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Missing Tests (3 packages)
|
||||
|
||||
### 1.1 shared package
|
||||
**Status:** ❌ No tests
|
||||
**Path:** `packages/shared/seed/scripts/`
|
||||
|
||||
```
|
||||
Create:
|
||||
├── tests/
|
||||
│ ├── types.test.lua # Test type definitions work
|
||||
│ └── types.cases.json # Parameterized test data
|
||||
```
|
||||
|
||||
### 1.2 config_summary package
|
||||
**Status:** ❌ Empty tests folder
|
||||
**Path:** `packages/config_summary/seed/scripts/tests/`
|
||||
|
||||
```
|
||||
Create:
|
||||
├── config.test.lua # Test config summary functions
|
||||
└── config.cases.json # Parameterized test data
|
||||
```
|
||||
|
||||
### 1.3 lua_test package
|
||||
**Status:** ⚠️ Examples only, no formal tests/
|
||||
**Path:** `packages/lua_test/seed/scripts/`
|
||||
|
||||
```
|
||||
Create:
|
||||
├── tests/
|
||||
│ ├── framework.test.lua # Test the test framework itself
|
||||
│ └── framework.cases.json # Parameterized test data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Fakemui Component Gaps
|
||||
|
||||
### Currently Missing Components (compared to MUI)
|
||||
|
||||
| Component | MUI Equivalent | Priority | Status |
|
||||
|-----------|----------------|----------|--------|
|
||||
| ToggleButtonGroup | ToggleButtonGroup | High | ❌ Need |
|
||||
| VirtualList | Virtuoso/react-window | Medium | ❌ Need |
|
||||
| TransferList | TransferList | Low | Optional |
|
||||
| DataGrid | @mui/x-data-grid | Medium | Lua pkg |
|
||||
| DesktopDatePicker | @mui/x-date-pickers | Done | ✅ |
|
||||
| Masonry | Masonry | Low | Optional |
|
||||
| LoadingButton | LoadingButton | Medium | ❌ Need |
|
||||
|
||||
### Components to Add
|
||||
|
||||
```typescript
|
||||
// fakemui/inputs/ToggleButtonGroup.tsx
|
||||
// fakemui/inputs/LoadingButton.tsx
|
||||
// fakemui/data-display/VirtualList.tsx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Frontends MUI Elimination
|
||||
|
||||
### Files Still Using @mui/material (20+ files)
|
||||
|
||||
#### Workflow Components (6 files)
|
||||
- [ ] `workflow/WorkflowEditor.tsx`
|
||||
- [ ] `workflow/WorkflowRunCard.tsx`
|
||||
- [ ] `workflow/WorkflowRunStatus.tsx`
|
||||
- [ ] `workflow/editor/WorkflowSidebar.tsx`
|
||||
- [ ] `workflow/editor/WorkflowTester.tsx`
|
||||
|
||||
#### UI Molecules (14+ files)
|
||||
- [ ] `ui/molecules/selection/ToggleGroup.tsx`
|
||||
- [ ] `ui/molecules/selection/Select.tsx`
|
||||
- [ ] `ui/molecules/selection/RadioGroup.tsx`
|
||||
- [ ] `ui/molecules/overlay/DropdownMenu.tsx`
|
||||
- [ ] `ui/molecules/overlay/DropdownMenu/MenuItem.tsx`
|
||||
- [ ] `ui/molecules/overlay/Popover.tsx`
|
||||
- [ ] `ui/molecules/overlay/Tooltip.tsx`
|
||||
- [ ] `ui/molecules/overlay/Dialog.tsx`
|
||||
- [ ] `ui/molecules/display/Card.tsx`
|
||||
- [ ] `ui/molecules/display/Alert.tsx`
|
||||
- [ ] `ui/molecules/tabs/core/Tabs.tsx`
|
||||
- [ ] `ui/molecules/tabs/components/TabsContent.tsx`
|
||||
|
||||
#### Library Files
|
||||
- [ ] `lib/lua/ui/generate-component-tree.tsx`
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Icon Expansion
|
||||
|
||||
### Target Icons to Add
|
||||
Based on common MUI icons not yet in fakemui:
|
||||
|
||||
```
|
||||
Editor:
|
||||
- [ ] Spellcheck ✅
|
||||
- [ ] Superscript ✅
|
||||
- [ ] Subscript ✅
|
||||
|
||||
Status:
|
||||
- [ ] HourglassEmpty ✅
|
||||
- [ ] HourglassFull ✅
|
||||
- [ ] Pending ✅
|
||||
- [ ] PendingActions ✅
|
||||
- [ ] PublishedWithChanges ✅
|
||||
|
||||
Charts:
|
||||
- [ ] DonutLarge ✅
|
||||
- [ ] DonutSmall ✅
|
||||
- [ ] StackedBarChart ✅
|
||||
- [ ] StackedLineChart ✅
|
||||
- [ ] TrendDown ✅
|
||||
- [ ] TrendingFlat ✅
|
||||
|
||||
Communication:
|
||||
- [ ] Forum ✅
|
||||
- [ ] Comment ✅
|
||||
- [ ] CommentOutlined ✅
|
||||
- [ ] Announcement ✅
|
||||
- [ ] Campaign ✅
|
||||
```
|
||||
|
||||
**Note:** Many of these may already exist - audit needed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Package Validator Compliance
|
||||
|
||||
### Validation Checklist Per Package
|
||||
|
||||
```bash
|
||||
# Run validator
|
||||
npm run validate:packages
|
||||
|
||||
# Expected checks:
|
||||
✓ Valid metadata.json with required fields
|
||||
✓ components.json array structure
|
||||
✓ All exported scripts exist
|
||||
✓ All component types are valid
|
||||
✓ No circular dependencies
|
||||
✓ Version follows semver
|
||||
✓ minLevel in valid range (0-6)
|
||||
✓ types.lua present
|
||||
✓ Test files present
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Lua Package Permissions System
|
||||
|
||||
### Permission Configuration Schema
|
||||
|
||||
```lua
|
||||
---@class PackagePermissions
|
||||
---@field minLevel PermissionLevel Minimum level to access package
|
||||
---@field databaseRequired boolean Whether package needs database
|
||||
---@field components table<string, ComponentPermission> Per-component permissions
|
||||
|
||||
---@class ComponentPermission
|
||||
---@field enabled boolean Whether component is enabled
|
||||
---@field minLevel PermissionLevel Minimum level for this component
|
||||
---@field featureFlags string[] Required feature flags
|
||||
```
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
1. Add `permissions.lua` to shared package
|
||||
2. Update renderer to check permissions before rendering
|
||||
3. Add database toggle support
|
||||
4. Add component-level on/off switches
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: CSS/Style System via Lua
|
||||
|
||||
### css_designer Package Structure
|
||||
|
||||
```
|
||||
packages/css_designer/
|
||||
├── seed/
|
||||
│ ├── metadata.json
|
||||
│ ├── components.json
|
||||
│ └── scripts/
|
||||
│ ├── init.lua
|
||||
│ ├── types.lua
|
||||
│ ├── parser/
|
||||
│ │ └── css_parser.lua
|
||||
│ ├── generator/
|
||||
│ │ └── style_generator.lua
|
||||
│ └── ui/
|
||||
│ ├── color_picker.lua
|
||||
│ └── style_editor.lua
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Legacy TSX to Lua Conversion
|
||||
|
||||
### High-Priority Conversions
|
||||
|
||||
| TSX Component | Target Lua Package | Status |
|
||||
|---------------|-------------------|--------|
|
||||
| WorkflowEditor | workflow_editor | ⏳ |
|
||||
| GitHubActionsFetcher | github_tools | ✅ Package exists |
|
||||
| SchemaEditor | schema_editor | ✅ Package exists |
|
||||
| FormBuilder | form_builder | ✅ Package exists |
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Monaco/Markdown Fakemui
|
||||
|
||||
### Monaco Wrapper
|
||||
|
||||
```typescript
|
||||
// fakemui/editors/MonacoEditor.tsx
|
||||
// Wrapper around @monaco-editor/react with fakemui styling
|
||||
```
|
||||
|
||||
### Markdown Component
|
||||
|
||||
```typescript
|
||||
// fakemui/data-display/Markdown.tsx ✅ Already exists!
|
||||
// Uses 'marked' library internally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: Multi-Frontend Support
|
||||
|
||||
### Abstract Rendering Layer
|
||||
|
||||
```lua
|
||||
---@class RenderTarget
|
||||
---@field type "react"|"qt6"|"cli" Target platform
|
||||
---@field capabilities table<string, boolean> Available features
|
||||
|
||||
---@class AbstractComponent
|
||||
---@field render fun(target: RenderTarget): any Platform-specific render
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: Dependency Cleanup
|
||||
|
||||
### Dependencies to Remove
|
||||
|
||||
```json
|
||||
{
|
||||
"remove": [
|
||||
"@emotion/react",
|
||||
"@emotion/styled",
|
||||
"@mui/material",
|
||||
"@mui/icons-material",
|
||||
"@mui/x-data-grid",
|
||||
"@mui/x-date-pickers",
|
||||
"@phosphor-icons/react"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Estimated Savings
|
||||
- Bundle size: -2-3 MB
|
||||
- Build time: -10-20%
|
||||
- Dependency tree: -50+ packages
|
||||
|
||||
---
|
||||
|
||||
## Phase 12: Verification
|
||||
|
||||
### Playwright E2E Tests
|
||||
|
||||
```typescript
|
||||
// Test each package renders correctly
|
||||
test.describe('Package Rendering', () => {
|
||||
for (const pkg of packages) {
|
||||
test(`${pkg.name} renders`, async ({ page }) => {
|
||||
await page.goto(`/packages/${pkg.name}`)
|
||||
await expect(page.locator('[data-package]')).toBeVisible()
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Smoke Test Order
|
||||
|
||||
1. ✅ shared (types only)
|
||||
2. ✅ lua_test (testing framework)
|
||||
3. ui_auth (authentication)
|
||||
4. ui_home (landing page)
|
||||
5. dashboard (main dashboard)
|
||||
6. ... remaining packages
|
||||
|
||||
---
|
||||
|
||||
## Tracking
|
||||
|
||||
### Daily Progress Log
|
||||
|
||||
| Date | Phase | Tasks Completed | Notes |
|
||||
|------|-------|-----------------|-------|
|
||||
| 2025-12-30 | Planning | Created master plan | - |
|
||||
|
||||
### Completion Criteria
|
||||
|
||||
- [ ] All 43 packages pass validator
|
||||
- [ ] All 43 packages have tests
|
||||
- [ ] Zero @mui/* imports in codebase
|
||||
- [ ] Zero @phosphor-icons imports
|
||||
- [ ] Playwright E2E tests pass
|
||||
- [ ] Bundle size reduced by 15%+
|
||||
- [ ] User notified of completion
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Run all package tests
|
||||
npm run test:packages
|
||||
|
||||
# Validate all packages
|
||||
npm run validate:packages
|
||||
|
||||
# Check for MUI imports
|
||||
grep -r "@mui/material" frontends/nextjs/src --include="*.tsx"
|
||||
|
||||
# Build and verify
|
||||
npm run build
|
||||
|
||||
# Run E2E tests
|
||||
npm run test:e2e
|
||||
```
|
||||
Reference in New Issue
Block a user