rspade_system/app/RSpade/BuildUI/resource/build-service/README.md

RSpade Build UI Service

A Node.js service that provides real-time visibility into RSpade manifest and bundle compilation processes via WebSocket streaming to an xterm.js terminal interface.

Architecture

• HTTP Server: Express on port 3100
• WebSocket Server: ws library on port 3101
• Terminal UI: xterm.js for build output display
• Frontend: Vanilla JavaScript bundled with Webpack
• Auto-reload: Webpack watch + nodemon for development

Directory Structure

build-service/
├── rspade-build-ui-server.js  # Express + WebSocket server
├── src/
│   └── app.js                 # Frontend application with xterm.js
├── public/
│   ├── index.html             # Terminal UI page
│   ├── hello_world.html       # Test page
│   └── dist/                  # Webpack output (generated)
│       └── bundle.js
├── package.json
├── webpack.config.js
├── nodemon.json
├── start-with-backoff.sh      # Startup script with exponential backoff
└── rspade-build-ui.conf       # Supervisord configuration

Development

Install Dependencies

npm install

Development Mode (Auto-reload)

npm start
# or
npm run dev

This runs:

• Webpack in watch mode (rebuilds on src/ changes)
• Nodemon (restarts server on rspade-build-ui-server.js changes)

Production Build

npm run build
npm run server

Ports

• 3100 - HTTP server (serves UI and API)
• 3101 - WebSocket server (real-time communication)

Endpoints

HTTP

• GET /_build/ - Terminal UI showing build output
• GET /_hello_world - WebSocket test page
• GET /api/hello - Hello world endpoint
• GET /api/health - Service status

WebSocket

• ws://localhost:3101 - WebSocket connection for build streaming

Testing

Test HTTP Server

curl http://localhost:3100/api/hello

Test Terminal UI

1. Visit http://localhost:3100/_build/
2. WebSocket connects automatically
3. Build process starts automatically when clients connect
4. Watch real-time build output in xterm terminal

Supervisord Setup

Copy configuration to supervisord:

cp rspade-build-ui.conf /etc/supervisor/conf.d/
supervisorctl reread
supervisorctl update
supervisorctl start rspade-build-ui

Crash Recovery with Exponential Backoff

The service uses a wrapper script (start-with-backoff.sh) that implements exponential backoff:

Retry Schedule:

• Attempt 1: Immediate
• Attempt 2: 1 second delay
• Attempt 3: 2 second delay
• Attempt 4: 4 second delay
• Attempt 5: 8 second delay
• Attempt 6: 16 second delay
• Attempt 7: 32 second delay
• Attempt 8: 64 second delay
• Attempt 9: 128 second delay
• Attempt 10: 256 second delay
• Attempt 11: 512 second delay
• Attempt 12+: 600 seconds (10 minutes) - caps here

Additional Safety:

• Kills processes on ports 3100/3101 before starting
• Kills any orphaned rspade-build-ui-server.js processes
• Ensures clean startup even after crashes

Behavior:

• Retries infinitely (never gives up)
• Short delays for transient issues
• Long delays for persistent problems
• Supervisord manages the wrapper script
• All retry logic is in the wrapper, not supervisord

WebSocket Protocol

Server → Client Messages

Connection Established

{
  "type": "connected",
  "message": "Connected to RSpade Build UI WebSocket",
  "timestamp": "2025-10-31T05:40:00.000Z"
}

Build Output

{
  "type": "output",
  "content": "[BUILD] Parsing JS file: app/RSpade/Core/Js/Ajax.js\n"
}

Build Complete

{
  "type": "build_complete",
  "exit_code": 0,
  "timestamp": "2025-10-31T05:40:15.123Z"
}

Build Error

{
  "type": "build_error",
  "error": "Error message",
  "timestamp": "2025-10-31T05:40:15.123Z"
}

Build Process Integration

--build-debug Flag

Both rsx:manifest:build and rsx:bundle:compile commands support the --build-debug flag:

• Enables verbose build output via console_debug('BUILD', ...) messages
• Filters console_debug to ONLY show BUILD channel messages
• Forces CLI output even if console_debug is disabled in config
• Implemented via $_SERVER['argv'] detection in Debugger class

Current Implementation

The WebSocket server automatically:

1. Spawns php artisan rsx:bundle:compile --build-debug on client connection
2. Captures both stdout and stderr
3. Buffers output for late-joining clients
4. Broadcasts output to all connected clients in real-time
5. Only runs one build process at a time (shared across clients)
6. Notifies clients when build completes with exit code

Build Output Streaming

When a client connects:

• If no build is running: starts new build process
• If build is running: sends buffered output + continues streaming
• All clients see the same shared build output
• Build completion triggers visual notification in terminal

Features

• ✅ HTTP server with static file serving
• ✅ WebSocket server for real-time communication
• ✅ xterm.js terminal emulation
• ✅ Build process spawning with --build-debug flag
• ✅ Real-time stdout/stderr streaming
• ✅ Shared build process across multiple clients
• ✅ Buffered output for late joiners
• ✅ Build completion notifications
• ✅ Webpack bundling with watch mode
• ✅ Auto-restart on code changes (nodemon)
• ✅ Visual connection status indicator
• ✅ ANSI color support in terminal

Next Steps

Phase 1: Build Redirection Integration (Planned)

Integrate with RSpade's manifest and bundle rebuild detection:

1. Detect Build Need

   • When Manifest detects rebuild needed (file changes)
   • When BundleCompiler detects compilation needed

2. Redirect to Build UI

   • Set cookie with build hash: rsx_build_${hash}=1
   • Redirect user to /_build/ with build UI
   • Cookie prevents multiple redirects for same build

3. Execute Build

   • WebSocket server spawns appropriate build command
   • Streams output to terminal in real-time
   • User watches build progress live

4. Forward Back

   • On build completion, automatically redirect to original URL
   • Clear build hash cookie
   • User continues to intended page with fresh build

Additional Planned Features

• Handle both manifest AND bundle builds
• Queue multiple build requests if needed
• Better error handling and recovery
• Build status persistence across page reloads
• Ability to cancel/restart builds

Note: This is the general direction - implementation will require additional tweaks to handle edge cases, error conditions, and ensure smooth UX.