metabuilder/docs/analysis/IMMEDIATE_FIXES.md

MetaBuilder: Immediate Fixes (Next 2 Hours to Functional System)

Target: Get Next.js building and styled, then test all 3 frontends

---

FIX #1: Next.js TypeScript Error (5 minutes)

File

/frontends/nextjs/src/app/page.tsx

Error (Current)

src/app/page.tsx:67 - error TS2322
Type 'unknown' is not assignable to type 'string'

Root Cause

Line 67: const renderObj = parsed.render as Record<string, unknown> | undefined

When cast to unknown, TypeScript loses the prior typeof renderObj.type === 'string' check.

Solution

Replace lines 64-76 with:

if (hasValidRender) {
  // Type-safe render object with required 'type' field
  const safeRender: { type: string; template?: unknown } = {
    type: renderObj.type as string,
    template: renderObj.template,
  }
  const componentDef = {
    id: parsed.id,
    name: parsed.name,
    description: typeof parsed.description === 'string' ? parsed.description : undefined,
    props: Array.isArray(parsed.props) ? parsed.props : undefined,
    render: safeRender,
  }
  return <JSONComponentRenderer component={componentDef} />
}

Verification

cd /frontends/nextjs
npm run typecheck
# Expected output: Compiled successfully

---

FIX #2: Re-enable SCSS Styling (30 minutes)

File

/frontends/nextjs/src/main.scss

Current State

Lines 3-11 are commented out:

// @use './styles/core/theme.scss';
// @import '@/fakemui/styles/components.scss';
// @import '@/fakemui/styles/tokens.scss';
// etc.

Comment explanation: // TODO: Fix SCSS imports - causing build errors

Investigation Steps

Step 1: Check if files exist

ls -la /frontends/nextjs/src/styles/core/theme.scss
ls -la /frontends/nextjs/src/fakemui/styles/components.scss
# If missing, check alternate paths
find /frontends -name "theme.scss" -o -name "components.scss"

Step 2: Try uncommenting one import at a time

# In main.scss, uncomment just the first @use:
@use './styles/core/theme.scss';
# Build and see what error appears
npm run build

Step 3: Debug the specific error

• If file not found: Adjust path
• If syntax error: Fix SCSS syntax
• If type error: Check Tailwind/SCSS version compatibility

Step 4: Fix root cause Common issues:

• Wrong path (should be relative to main.scss location)
• SCSS version incompatibility (check package.json sass version)
• Tailwind not installed (check package.json)
• TypeScript strictness on CSS imports

Step 5: Uncomment all imports once working

@use './styles/core/theme.scss';
@import '@/fakemui/styles/components.scss';
@import '@/fakemui/styles/tokens.scss';
@import '@/fakemui/styles/overrides.scss';
@import './styles/custom.scss';

Testing

cd /frontends/nextjs
npm run dev
# Navigate to http://localhost:3000
# Verify Material Design styling is visible:
# - Buttons should have color, shadow
# - Cards should have elevation
# - Text should have proper typography
# - Layout should have proper spacing

---

FIX #3: Uncomment PackageStyleLoader (2 minutes)

File

/frontends/nextjs/src/app/layout.tsx

Current State

Lines 60-61 are commented out:

// const packageStyles = await PackageStyleLoader()
// styleSheets = [...styleSheets, ...packageStyles]

Solution

Simply uncomment once SCSS is working:

const packageStyles = await PackageStyleLoader()
styleSheets = [...styleSheets, ...packageStyles]

Verification

• Packages can now apply custom styles
• No additional testing needed (covered by SCSS verification)

---

VERIFICATION: Build Complete Next.js (10 minutes)

Once all 3 fixes applied:

cd /frontends/nextjs

# Step 1: Type check
npm run typecheck
# Expected: ✓ Compiled successfully

# Step 2: Build production
npm run build
# Expected: ✓ Successfully built, output available

# Step 3: Run dev server
npm run dev
# Expected: ✓ Ready on http://localhost:3000

# Step 4: Verify UI
# In browser, navigate to http://localhost:3000
# Verify:
# - Page loads without errors
# - Material Design styling visible (buttons have color, cards have shadow)
# - Navigation works
# - Database connection works (check console for any errors)

---

TEST: Next.js E2E (10 minutes)

cd /frontends/nextjs

# Run E2E test suite
npm run test:e2e

# Expected result:
# ✓ 326+ tests passing
# ✓ 1 failing (auth middleware - different issue)
# Pass rate: 99%+

---

BUILD: CLI Frontend (30 minutes parallel)

While Next.js is building, start CLI:

cd /frontends/cli

# Step 1: Install dependencies
conan install . --output-folder build --build missing
# Expected: Conan downloads cpr, lua, sol2, nlohmann_json

# Step 2: Generate CMake
cmake -S . -B build -G Ninja
# Expected: CMake generates build files

# Step 3: Compile
cmake --build build
# Expected: C++ compilation succeeds, binary in build/bin/metabuilder-cli

# Step 4: Test basic command
./build/bin/metabuilder-cli --version
# Should output version info

# Step 5: Test DBAL commands (requires Next.js running at localhost:3000)
export METABUILDER_BASE_URL=http://localhost:3000
./build/bin/metabuilder-cli dbal ping
# Should output: {"status": "ok"}

./build/bin/metabuilder-cli package list
# Should output: JSON array of installed packages

CLI Verification

# Test all major commands work
./build/bin/metabuilder-cli auth session
./build/bin/metabuilder-cli user list
./build/bin/metabuilder-cli package run ui_home home_page

---

BUILD: QT6 Frontend (30 minutes parallel)

While Next.js/CLI are building:

cd /frontends/qt6

# Step 1: Install dependencies
conan install . --output-folder build --build missing
# Expected: Conan downloads Qt6, cpr, libopenmpt

# Step 2: Generate CMake
cmake -S . -B build -G Ninja
# Expected: CMake generates build files

# Step 3: Compile
cmake --build build
# Expected: C++ compilation succeeds, app binary in build/

# Step 4: Run application
./build/metabuilder-qt6
# Expected: Qt6 window opens with landing page

# Step 5: Verify UI
# In the window, check:
# - Material Design colors and styling
# - Navigation works
# - Components render correctly
# - No console errors

QT6 Verification

• Landing page displays
• Material Design visible
• Package manager shows packages
• Storybook shows components

---

DEPLOYMENT: Docker Stack (20 minutes)

Once all frontends build successfully:

cd /deployment

# Start development stack
./deploy.sh development

# Expected:
# ✓ PostgreSQL starts
# ✓ Redis starts
# ✓ Nginx starts
# ✓ Next.js app starts
# Services available at:
#   - Frontend: http://localhost:3000
#   - Nginx: http://localhost:80
#   - PostgreSQL: localhost:5432

# Verify services
docker ps
# Should show 4-5 running containers

# Check logs
docker logs metabuilder-app-dev
docker logs metabuilder-postgres-dev

# Test database connection
docker exec metabuilder-postgres-dev psql -U metabuilder -c "SELECT * FROM \"InstalledPackage\" LIMIT 5;"

# Verify bootstrap completed
curl http://localhost:3000/api/bootstrap
# Should return: {"success": true, "packagesInstalled": 12, ...}

---

Summary: Timeline

Task	Time	Type	Status
Fix TypeScript error	5 min	Sequential	Critical
Restore SCSS styling	30 min	Sequential	Critical
Uncomment PackageStyleLoader	2 min	Sequential	Quick
Verify Next.js build	10 min	Sequential	Validation
Test Next.js E2E	10 min	Sequential	Validation
SUBTOTAL (Next.js)	57 min
PARALLEL START
Build CLI	30 min	Parallel	Optional
Build QT6	30 min	Parallel	Optional
Docker deployment	20 min	After main	Deployment
TOTAL	2 hours

Critical Path: TypeScript fix (5) → SCSS fix (30) → Next.js verify (10) → Deploy (20) = 65 minutes minimum

---

Troubleshooting

If TypeScript fix doesn't work

• Verify no other TypeScript errors in page.tsx
• Run: npm run typecheck 2>&1 | head -20 to see full error
• Check that JSONComponent type definition has render: { type: string }

If SCSS still has errors after uncomment

• Check SCSS syntax (look for unclosed braces, missing semicolons)
• Verify sass version in package.json (should be 1.70+)
• Try CSS @import instead of SCSS @use
• Check Tailwind configuration

If CLI build fails

• Verify CMake 3.27+ installed: cmake --version
• Verify Conan 2.0+ installed: conan --version
• Check C++20 compiler available: g++ --version or clang --version
• Verify internet connection (Conan downloads packages)

If QT6 build fails

• Verify Qt6 installation via Conan
• Check platform (Linux/Mac/Windows) supported
• Verify OpenGL/graphics libraries available

If Docker fails

• Verify Docker daemon running: docker ps
• Check port conflicts: lsof -i :3000
• Verify .env variables set in docker-compose

---

Success Criteria

✅ Next.js

• npm run typecheck passes
• npm run build succeeds
• npm run dev starts server
• UI loads at http://localhost:3000 with styling
• Tests pass: npm run test:e2e

✅ CLI

• Builds without errors
• metabuilder-cli --version works
• metabuilder-cli dbal ping succeeds
• metabuilder-cli package list returns packages

✅ QT6

• Builds without errors
• Application window opens
• Material Design styling visible
• Components render correctly

✅ Docker

• All containers start
• Database initialized
• Bootstrap completes
• API endpoints responsive

---

When all criteria met: System is production-ready