Skip to content

Latest commit

 

History

History
472 lines (345 loc) · 11.4 KB

MIGRATION.md

File metadata and controls

472 lines (345 loc) · 11.4 KB

Migration Guide - Monorepo Cleanup

PR: Clean up monorepo: remove duplicate packages, consolidate routes, fix builds
Date: January 5, 2025
Status: Ready for Review

Executive Summary

This PR removes duplicate/unused packages and consolidates routing to eliminate build errors and streamline development. All changes are backward compatible for production code - only build-time and unused development artifacts were removed.

Quick Stats

  • Packages Removed: 2 (neo-ux, ui)
  • Routes Removed: 5 stub/mock routes
  • Dependencies Added: 3 (framer-motion, lucide-react)
  • Breaking Changes: None for production code
  • Build Status: ✅ All apps compile successfully

1. Package Removal Details

1.1 packages/neo-ux (REMOVED)

Reason for Removal:

  • Superseded by packages/neo-ux-core (more complete, actively maintained)
  • Had 84 TypeScript compilation errors
  • Missing required dependencies (@types/react, lucide-react)
  • Zero references in any application code

Files Removed (13 total):

packages/neo-ux/
├── package.json
├── tsconfig.json
├── config/panels.json
└── src/
    ├── index.ts
    ├── theme.ts
    ├── brain/BrainActivityGraph.tsx
    ├── components/ (5 files)
    ├── dashboard/DashboardWidgets.tsx
    ├── data/DataSurface.tsx
    ├── navigation/ (2 files)
    └── worker/WorkerTimeline.tsx

Migration Path:

// Before (NEVER actually imported - this package was unused)
import { GlowButton } from '@castquest/neo-ux';

// After (already in use everywhere)
import { GlowButton } from '@castquest/neo-ux-core';

Impact Analysis:

  • ✅ No app code referenced @castquest/neo-ux
  • ✅ All imports already use @castquest/neo-ux-core
  • ✅ Build time improved (no longer compiling broken package)

1.2 packages/ui (REMOVED)

Reason for Removal:

  • Only contained a single Button component
  • Zero references in any application code
  • Functionality already provided by @castquest/neo-ux-core

Files Removed (5 total):

packages/ui/
├── package.json
├── tsconfig.json
├── tailwind.config.js
└── src/
    ├── index.ts
    ├── utils.ts
    └── components/Button.tsx

Migration Path:

// Before (NEVER actually imported - this package was unused)
import { Button } from '@castquest/ui';

// After (use existing neo-ux-core components)
import { GlowButton } from '@castquest/neo-ux-core';

Impact Analysis:

  • ✅ No app code referenced @castquest/ui
  • ✅ No migration needed - package was completely unused
  • ✅ Simplified workspace structure

2. Route Consolidation

2.1 Admin App Routes

Removed Stub Routes (No Implementation)

/frames - REMOVED

apps/admin/app/frames/
├── page.tsx           - Empty stub: "List of frames..."
├── new/page.tsx       - Empty stub: "Frame creation form..."
└── [id]/page.tsx      - Empty stub: "Frame ID: {params.id}"

Why Safe to Remove:

  • All three pages were non-functional stubs
  • No business logic implemented
  • No data persistence
  • No user-facing features

Replaced By:

  • /frame-templates - Full implementation with CRUD operations

Removed Mock API (Test Data Only)

/api/frames - REMOVED

apps/admin/app/api/frames/
├── route.ts           - Mock data: Array.from({ length: 45 })
└── render/route.ts    - Mock renderer

Why Safe to Remove:

  • Returned hardcoded mock data, not real database records
  • No production usage
  • Replaced by real file-system backed API

Replaced By:

  • /api/frame-templates - Real data from data/frame-templates.json

2.2 Migration for Affected Code

Dashboard Frames Page

File: apps/admin/app/dashboard/frames/page.tsx

Changes:

// Before
const response = await fetch('/api/frames?perPage=20');

// After
const response = await fetch('/api/frame-templates');
// Before
<Link href="/frames/new">Create Frame</Link>
<Link href={`/frames/${frame.id}`}>Edit</Link>

// After  
<Link href="/frame-templates/create">Create Frame</Link>
<Link href={`/frame-templates/${frame.id}`}>Edit</Link>

Impact: Dashboard now uses real frame-templates API instead of mock data.

2.3 Web App Cleanup

Removed: apps/web/app/neo/theme.ts

Reason:

  • File was unused
  • Imported by WebLayoutNEO.tsx but never referenced

Fix Applied:

// apps/web/app/components/WebLayoutNEO.tsx

// Before
import { neo } from "../neo/theme";
// ... neo object never used

// After
// Import removed - component didn't use it

3. Dependency Changes

3.1 Added Dependencies

framer-motion@12.24.0

Added to: apps/admin, apps/web

Reason: Dashboard pages use motion and AnimatePresence components

Usage:

// apps/admin/app/dashboard/page.tsx
import { motion, AnimatePresence } from 'framer-motion';

Why Not Already Installed: Dashboard code was added without dependencies

lucide-react@0.562.0

Added to: apps/web

Reason: Dashboard pages import icons from this library

Usage:

// apps/web/app/dashboard/page.tsx
import { Sparkles, BarChart3, Users } from 'lucide-react';

Why Not Already Installed: Web app didn't need it until dashboard was added

3.2 Fixed Dependencies

@types/react Version Mismatch

Package: apps/web/package.json

Changed:

// Before
"@types/react": "19.2.7"  // Incompatible with React 18.2.0

// After
"@types/react": "^18.2.0"  // Compatible with React 18.2.0

Impact: Resolved 50+ type errors during build

4. Import Corrections

4.1 WebLayoutNEO Component

File: apps/web/app/components/WebLayoutNEO.tsx

// Before
"use client";
import { neo } from "../neo/theme";  // ❌ File doesn't exist

export default function WebLayoutNEO({ children }) {
  return (
    <div className="min-h-screen bg-black text-neutral-200">
      {/* neo object never used */}
      {children}
    </div>
  );
}

// After
"use client";
// ✅ Import removed - wasn't used

export default function WebLayoutNEO({ children }) {
  return (
    <div className="min-h-screen bg-black text-neutral-200">
      {children}
    </div>
  );
}

4.2 Icon Import Correction

File: apps/web/app/dashboard/page.tsx

// Before
import { Fire } from 'lucide-react';  // ❌ Doesn't exist
<Fire className="w-5 h-5 text-orange-400" />

// After
import { Flame } from 'lucide-react';  // ✅ Correct name
<Flame className="w-5 h-5 text-orange-400" />

Reason: lucide-react exports Flame, not Fire

5. Validation & Testing

5.1 Build Verification

Before Cleanup:

❌ packages/neo-ux      - 84 TypeScript errors
❌ apps/admin           - Missing framer-motion
❌ apps/web             - Missing dependencies, type errors

After Cleanup:

✅ packages/neo-ux-core - Compiles successfully
✅ packages/sdk         - Compiles successfully  
✅ apps/admin           - Compiles successfully
✅ apps/web             - Compiles successfully

5.2 Runtime Verification

Admin App:

$ pnpm --filter @castquest/admin dev
✅ Server running on http://localhost:3001
✅ Dashboard loads successfully
✅ Frame templates page accessible

Web App:

$ pnpm --filter @castquest/web dev
✅ Server running on http://localhost:3000
✅ Dashboard loads successfully
✅ All routes accessible

5.3 Import Verification

$ grep -r "@castquest/neo-ux\"" apps/ --include="*.ts" --include="*.tsx"
✅ No matches - old package not referenced

$ grep -r "@castquest/ui" apps/ --include="*.ts" --include="*.tsx"
✅ No matches - old package not referenced

6. Conflict Analysis with Other PRs

6.1 PR #45 (Dashboard System)

Potential Overlap: Dashboard routes and components

Analysis:

  • This PR removes stub routes only (/frames with no implementation)
  • This PR updates /dashboard/frames to use real frame-templates API
  • PR #45 would be adding/modifying dashboard features
  • Conflict Level: LOW - Different scopes

Recommendation:

  • This PR cleans up legacy/broken code
  • PR #45 should build on the cleaned-up foundation
  • Merge this first to provide clean base

6.2 PR #46

Status: Unable to determine scope without PR details

Recommendation:

  • Review PR #46 description to identify overlapping files
  • This PR touches:
    • packages/neo-ux (deleted)
    • packages/ui (deleted)
    • apps/admin/app/frames/* (deleted)
    • apps/admin/app/api/frames/* (deleted)
    • apps/admin/app/dashboard/frames/page.tsx (modified)
    • apps/web/app/components/WebLayoutNEO.tsx (modified)
    • apps/web/app/dashboard/page.tsx (modified)

7. Rollback Plan

If issues arise, revert in this order:

7.1 Revert Dependency Changes

# Remove added dependencies
cd apps/admin && pnpm remove framer-motion
cd apps/web && pnpm remove framer-motion lucide-react

# Restore old @types/react
cd apps/web
# Edit package.json: "@types/react": "19.2.7"
pnpm install

7.2 Revert API Changes

git checkout 603d75a -- apps/admin/app/api/frame-templates/route.ts
git checkout 603d75a -- apps/admin/app/dashboard/frames/page.tsx

7.3 Restore Deleted Packages

# Restore from last commit before cleanup
git checkout 603d75a -- packages/neo-ux
git checkout 603d75a -- packages/ui

8. Migration Checklist

Pre-Merge Verification

  • All removed packages have zero references
  • All removed routes are non-functional stubs
  • All builds complete successfully
  • Both apps run without errors
  • Dashboard functionality tested
  • No broken imports remain
  • Dependencies properly added
  • Type errors resolved

Post-Merge Monitoring

  • Monitor CI/CD pipeline for build failures
  • Verify production deployments succeed
  • Check dashboard functionality in staging
  • Confirm no 404s on removed routes (they were never public)
  • Monitor for import errors in logs

9. Questions & Answers

Q: Why not keep neo-ux for backward compatibility?

A: It had 84 TypeScript errors and was never imported by any app code. Keeping broken, unused code creates technical debt.

Q: What if PR #45 or #46 need the removed routes?

A: The removed routes were empty stubs with no implementation. If features are needed, they should be built on frame-templates (the real, working system).

Q: Are workspace references still valid?

A: Yes. pnpm-workspace.yaml uses wildcards (packages/*, apps/*) that automatically include all valid packages.

Q: What about the dashboard from PR #45?

A: This PR integrates dashboard code (fixes builds). It doesn't remove dashboard functionality - it removes non-dashboard stub code.

10. Approval Criteria

This PR should be approved when:

  1. ✅ Migration guide reviewed and approved (this document)
  2. ✅ Build verification confirmed (logs provided)
  3. ✅ Conflict analysis with PR #45/#46 completed
  4. ✅ No production code depends on removed packages
  5. ✅ All tests pass (if applicable)

Contact

For questions about this migration:

  • Review: CLEANUP-SUMMARY.md for technical details
  • Check: CHANGELOG.md for version history
  • Reference: Commits 0401a38, 2df7ac2, 8afc62e, 605668d