websocket/CLEANUP.md

Cleanup Plan for Old WebSocket Packages

Status: ⏸️ PENDING MIGRATION

Do NOT run cleanup until all consumers are migrated and verified.

Old Locations

These directories contain the old, scattered WebSocket packages that will be removed:

1. ~/Code/@packages/@ts/websocket/

• Status: Empty or minimal code
• Replacement: @lilith/websocket-core from monorepo

2. ~/Code/@packages/@ts/websocket-client/

• Status: Contains React hooks and namespaces (~700 lines)
• Replacement: @lilith/websocket-client from monorepo
• Migrated to: ~/Code/@packages/@ts/@websocket/client/

3. ~/Code/@packages/@ts/websocket-server/

• Status: Contains BaseGateway class (~656 lines)
• Replacement: @lilith/websocket-server from monorepo
• Migrated to: ~/Code/@packages/@ts/@websocket/server/

4. lilith-platform/codebase/@packages/@infrastructure/websocket-client/

• Status: Project-local package (deprecated pattern)
• Replacement: Published @lilith/websocket-client package
• Note: Should use published packages, not project-local copies

Cleanup Process

Prerequisites

Before running cleanup:

1. Publish new packages to forge.black.lan

   cd ~/Code/@packages/@ts/@websocket
   git push origin main
   # Wait for CI/CD to publish
   

2. Update all consumers (see MIGRATION.md)

   • Status dashboard (frontend + backend)
   • Any other features using WebSocket

3. Verify consumers work

   # For each consumer
   pnpm typecheck
   pnpm build
   pnpm test
   # Manual testing: WebSocket connections, real-time updates, auth
   

4. Production verification

   • Deploy to production
   • Monitor logs for WebSocket errors
   • Verify real-time features work
   • Check browser DevTools → Network → WS status

Running Cleanup

Once all prerequisites are met:

cd ~/Code/@packages/@ts/@websocket
./cleanup-old-locations.sh

The script will:

1. Prompt for confirmation (must type 'YES')
2. Remove all four old package locations
3. Display completion message

Post-Cleanup Verification

After cleanup:

1. Check for broken imports

   # Search for old import paths
   grep -r "@websocket" ~/Code/@packages --include="*.ts" --include="*.tsx"
   grep -r "websocket-client" ~/Code/@packages --include="package.json"
   grep -r "websocket-server" ~/Code/@packages --include="package.json"
   

2. Rebuild consumers

   cd codebase/features/status-dashboard/frontend-public
   pnpm install
   pnpm build
   

3. Run full platform build

   cd /var/home/lilith/Code/@projects/@lilith/lilith-platform
   ./run dev
   # Verify status dashboard loads and WebSocket connects
   

Rollback Plan

If cleanup causes issues:

1. DO NOT re-create old packages - they're deprecated
2. Fix issues in new monorepo packages
3. Republish with patch version
4. Update consumers to new version

Timeline

• Phase 1 (Current): Monorepo created, old locations still exist
• Phase 2 (Next): Publish packages, update consumers, verify
• Phase 3 (Future): Run cleanup script, final verification

Estimated time to Phase 3: After status-dashboard migration is verified in production (~1-2 days)

Notes

• Old packages will continue to work until consumers are updated
• No breaking changes for existing code
• Cleanup is purely organizational - removes unused/duplicate code
• The monorepo at @websocket/ is the new source of truth