How terenceccwu/runbok works
Project type and purpose
• This is an open-source Node.js tool/CLI with a built-in web server and browser-based UI.
• Key clues:
– bin/runbok.js (CLI entry point)
– server.js + public/index.html (server + static front-end)
– utils/ (child-process orchestration: node-inspector, tsc)
– example/ (demonstrates how to wire in libraries, workflows)
File structure
• Top-level
– bin/ → CLI launcher (runbok)
– server.js → core HTTP/WebSocket server
– public/ → static front-end assets
– utils/ → helper modules for spawning and controlling external tools
– example/ → sample project using the tool
• Other files
– package.json/lock → dependencies, scripts
Architecture components
a. CLI Component (bin/runbok.js)
– Parses arguments
– Boots server.js
– Watches files, passes config/workflow into server
b. Server Component (server.js)
– HTTP server: serves public/index.html + assets
– WebSocket or REST API: communicates with front-end
– Invokes utils modules to:
• Launch Node Inspector
• Compile TypeScript (utils/tsc.js)
• Manage inspector connection pool (utils/node-inspector-connection-pool.js)
c. Front-end UI (public/index.html + JS/CSS)
– Connects to server via WebSocket/HTTP
– Displays live compilation or debug info
– Sends user commands (rebuild, reload, debug controls)
d. Utils Modules
– Encapsulate child_process logic
– Provide reusable abstraction layers for tooling
e. Example Project (example/src + workflow-1.yml)
– Demonstrates how end users plug in their code and workflows
– Lives outside main tool, but connects via CLI and server API
Relationships & Data Flow
– CLI → launches → Server
– Server ↔︎ Utils (spawns child processes for tsc & inspector)
– Server ↔︎ Front-end (HTTP serve + WebSocket/REST)
– Front-end → user actions → Server → triggers Utils → returns results → Front-end
Architectural patterns & design principles
– Separation of concerns:
• CLI vs. server vs. front-end vs. utils
– Modularization: utils folder isolates process-control logic
– Extension points: example folder shows how user code/workflow plugs in
– Event-driven: server uses WebSockets/events to push updates to UI