From de88dc65454b7d735291733ea2c3442e00106e7e Mon Sep 17 00:00:00 2001 From: Richard Ward Date: Tue, 30 Dec 2025 17:31:34 +0000 Subject: [PATCH] docs: plan,migration,master (1 files) --- MASTER_MIGRATION_PLAN.md | 428 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 428 insertions(+) create mode 100644 MASTER_MIGRATION_PLAN.md diff --git a/MASTER_MIGRATION_PLAN.md b/MASTER_MIGRATION_PLAN.md new file mode 100644 index 000000000..f7cac0eea --- /dev/null +++ b/MASTER_MIGRATION_PLAN.md @@ -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 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 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 +```