Update npm packages to latest versions
Fix JavaScript sourcemap paths to show full file locations Implement --build-debug flag and complete Build UI streaming Add xterm.js terminal UI and fix asset path routing Add RSpade Build UI service with WebSocket support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
241
app/RSpade/BuildUI/resource/build-service/README.md
Executable file
241
app/RSpade/BuildUI/resource/build-service/README.md
Executable file
@@ -0,0 +1,241 @@
|
||||
# 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
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Development Mode (Auto-reload)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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**
|
||||
```json
|
||||
{
|
||||
"type": "connected",
|
||||
"message": "Connected to RSpade Build UI WebSocket",
|
||||
"timestamp": "2025-10-31T05:40:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Build Output**
|
||||
```json
|
||||
{
|
||||
"type": "output",
|
||||
"content": "[BUILD] Parsing JS file: app/RSpade/Core/Js/Ajax.js\n"
|
||||
}
|
||||
```
|
||||
|
||||
**Build Complete**
|
||||
```json
|
||||
{
|
||||
"type": "build_complete",
|
||||
"exit_code": 0,
|
||||
"timestamp": "2025-10-31T05:40:15.123Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Build Error**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user