Rae Compiler Development Dashboard

Lightweight developer dashboard that keeps Rae compiler contributors aware of build health, test coverage, and historical performance trends without relying on heavy frameworks. The current implementation lives in this repository so it can eventually be re-authored in Rae itself.

Project Overview

• Goal: Provide a simple yet powerful dashboard for monitoring the Rae compiler (builds, tests, stats, Codex automation).
• Constraint: Keep everything transparent and portable so the entire stack can be rewritten in Rae once the language has UI primitives.
• Scope: Focus on developer productivity (build/test monitoring, stats, Codex hand-off). No attempt to replace IDE/editor tooling.

Technology Stack

Layer	Choice	Rationale
Runtime	Bun (preferred) or Node.js	Fast startup, familiar ecosystem, easy to port
Language	TypeScript	Static safety without build-time complexity
Server	Raw HTTP + WebSocket (Bun primitives or ws)	Low abstraction overhead
Storage	SQLite via Bun's driver or better-sqlite3	Single-file DB, easy backup/versioning
Client	Vanilla JS / optional Preact micro-components + CSS variables	Minimal runtime, easy to inspect and port
Charts	Chart.js	Straightforward API
Syntax	Prism.js (or lightweight equivalent)	Highlight compiler/code snippets

Getting Started

Prerequisites

• Bun ≥ 1.0 (preferred) or Node.js ≥ 18
• Rae compiler repository available next to this project (default ../rae)

Install Dependencies

bun install

Configuration

config.json ships with the repo and should work out of the box. If you need local overrides (different paths/ports/commands), create a config.local.json file with the same shape. Any keys in config.local.json override config.json (and config.local.json is git-ignored). config.example.json mirrors the default config for reference.

{
  "compilerPath": "../rae",
  "port": 3000,
  "examplesPath": "examples",
  "defaultTarget": "live",
  "targets": [
    {
      "id": "live",
      "label": "Live (bytecode VM)",
      "testCommand": "cd compiler && TEST_TARGET=live make test",
      "buildCommand": "cd compiler && make",
      "cleanCommand": "cd compiler && make clean",
      "rebuildCommand": "cd compiler && make clean && make",
      "exampleRunCommand": "./compiler/bin/rae run {{ENTRY}}",
      "exampleWatchCommand": "./compiler/bin/rae run --watch {{ENTRY}}",
      "exampleBuildCommand": "./compiler/bin/rae build --target live --out {{OUTDIR}} {{ENTRY}}"
    },
    {
      "id": "compiled",
      "label": "Compiled (C backend)",
      "testCommand": "cd compiler && TEST_TARGET=compiled make test",
      "buildCommand": "cd compiler && make",
      "cleanCommand": "cd compiler && make clean",
      "rebuildCommand": "cd compiler && make clean && make",
      "exampleRunCommand": "./compiler/bin/rae build --target compiled --out {{OUTDIR}} {{ENTRY}}",
      "exampleBuildCommand": "./compiler/bin/rae build --target compiled --out {{OUTDIR}} {{ENTRY}}"
    },
    {
      "id": "hybrid",
      "label": "Hybrid Dev",
      "testCommand": "cd compiler && TEST_TARGET=hybrid make test",
      "buildCommand": "cd compiler && make",
      "cleanCommand": "cd compiler && make clean",
      "rebuildCommand": "cd compiler && make clean && make",
      "exampleRunCommand": "./compiler/bin/rae build --target hybrid --out {{OUTDIR}} {{ENTRY}}",
      "exampleBuildCommand": "./compiler/bin/rae build --target hybrid --out {{OUTDIR}} {{ENTRY}}"
    }
  ]
}

Run the Dashboard

# Development server with auto-restart + client reload
bun run dev

# Stop the dev server (kills the listener on the configured port)
make stop

# Production build (if/when a bundle step exists)
bun run start

bun run dev launches a small watcher that restarts the Bun server whenever files under src/, config.json, config.local.json, or package.json change. The browser auto-reloads after each restart, so you rarely need to refresh manually. The server exposes both HTTP and WebSocket endpoints; open http://localhost:3000 in a browser.

Use the Inline Test Runner

• Use the Target dropdown (Live / Compiled / Hybrid) in the panel header to pick which compiler mode to exercise. The default comes from defaultTarget, but you can switch at any time.
• Click Run all tests (or press Ctrl+T/Cmd+T) inside the dashboard to execute the command mapped to the selected target. Each target can point at a different script/Make target in config.json.
• Live stdout/stderr output appears in the terminal panel; the run status chip flips to Passed/Failed when complete.
• Real-time per-test updates populate the suite summary and the test list so you can see which specific files passed/failed.
• The browser auto-reloads whenever the Bun dev server restarts, so you rarely need to manually refresh during local development.
• Compiled and Hybrid targets use the slim build suites (make test TARGET=compiled|hybrid), so dashboard-triggered runs stay fast while still exercising the new codegen and packaging flows.

Use the Build Controls

• Buttons for Build, Clean, and Rebuild run whichever commands you defined for the currently selected target. Ctrl+T/Cmd+T still triggers tests, while Ctrl+B/Cmd+B triggers Build.
• Build stdout/stderr streams into its own terminal panel with copy button and status indicator.
• Rebuild executes the clean command followed by the build command (via clean && build) so you can reset the compiler tree before building again.

Run the Examples

• The Examples panel scans the configured examplesPath (defaults to ../rae/examples) and lists every .rae demo project, including metadata from optional devtools.json files (name, target restrictions, etc.).
• Select an example and pick a target via the dropdown in the panel header. Examples can opt into specific targets (e.g., the new Hybrid hot reload demo only exposes the Hybrid profile).
• Use Run, Live watch, or Build artifacts:
  • Run executes the configured per-target command (Live uses rae run, Hybrid/Compiled run rae build with a temp output dir).
  • Live watch is only enabled for targets that define exampleWatchCommand (typically Live).
  • Build artifacts runs the target’s exampleBuildCommand and lists the emitted files + hashes so you can inspect Hybrid/Compiled bundles without leaving the browser.
• Output streams into a terminal next to the file tree; click any file button to view the highlighted source without leaving the dashboard.
• The inline editor still lets you tweak files in place. Save changes and rerun/watch as needed to simulate hot reload workflows.
• The examples/hybrid_hot_reload sample demonstrates the Hybrid packaging pipeline: build it via the dashboard to see both the compiled host stubs and VM chunks listed in the artifacts panel.
• The hybrid demo now exposes versioned Dev download v1/v2/v3 and Release download v1/v2/v3 buttons; each one runs the helper script, stages the generated .vmchunk + manifest under .simulated_downloads/<profile>/<version>/, and streams the resulting hashes back into the terminal so you can mimic “downloaded code” events without leaving the UI.
• Staged bundles appear in the Staged downloads card right below Build artifacts so you can verify which profiles, versions, and timestamps are available for the host to reload.

Track Stats

• Every test/build command stores metrics (durations, pass/fail counts) in data/devtools.db via SQLite.
• The Stats preview panel pulls recent entries from the database (default metrics: tests.duration_ms, builds.duration_ms) so you can see trends without leaving the dashboard.
• Data can be exported later for Chart.js visualizations; each entry carries metadata (success, run id, etc.).

Browse Rae Test Sources

• The Test sources panel lists files from testsPath (default compiler/tests) and renders them with a lightweight Rae syntax highlighter.
• Select a file to see its contents; use the corner copy icon to grab the code for editor reproduction or bug reports.
• The highlighter loads syntaxSummaryPath (default ../rae/docs/rae_syntax.json) for authoritative tokens—keep that file up to date as the language evolves.

Error Log

• A warning icon in the header lights up when the dashboard encounters fetch/WebSocket/runtime errors; click it to open the error log for details.
• Use the log to capture errors (e.g., missing syntax file) before reporting issues—entries include timestamps and sources.

Core Features

Test Dashboard (Priority: High)

• File-system tree of Rae tests with real-time status (⚪ not run, 🟡 running, 🟢 pass, 🔴 fail, 🟠 error).
• Detailed view: expected vs. actual output diff, compiler stdout/stderr, stack traces.
• Controls for Run All Tests, Run Failed, Run This Test, Clear Results.
• WebSocket streaming for incremental updates; optimistic UI and sticky summary header.

Build Controls (Priority: High)

• Buttons for Build Compiler, Clean, Rebuild.
• Terminal-style streaming panel with timestamps, ANSI-aware highlighting for warnings/errors, and auto-scroll.
• Status indicator with elapsed time tracking and cancellation support (future).

Statistics Viewer (Priority: Medium)

• Records build/test durations, pass rate, file/line counts, binary size, and other metrics after each successful run.

• Uses SQLite schema:

  CREATE TABLE stats (
    id INTEGER PRIMARY KEY,
    timestamp TEXT NOT NULL,
    metric_name TEXT NOT NULL,
    metric_value REAL NOT NULL,
    metadata TEXT
  );
  CREATE INDEX idx_metric_time ON stats(metric_name, timestamp);

• Chart.js line charts with toggles, multiple axes, and CSV export (last 30 days by default).

• Manual "Snapshot Stats" button plus automatic post-build recording.

Codex Integration (Priority: Low for MVP)

• "Ask Codex" button opens a panel with current failures/context and free-form prompt.
• Invokes the codex CLI inside the Rae compiler repo and streams output back into the UI.
• Optional templates to re-use common prompts.

Modern UI/UX

• Dark theme by default with planned toggle.
• Consistent spacing via CSS variables, subtle shadows, and 200–300ms transitions.
• Keyboard shortcuts: Ctrl+B build, Ctrl+T run all tests, Ctrl+R re-run failed tests.
• Toast notifications and friendly error handling when Rae paths/commands are misconfigured.

Architecture

rae-devtools/
├── src/
│   ├── server/
│   │   ├── main.ts          # HTTP server + websocket upgrade
│   │   ├── compiler.ts      # Build orchestration
│   │   ├── tests.ts         # Test runner + parsing
│   │   ├── stats.ts         # SQLite accessors
│   │   ├── codex.ts         # Wrapper around Codex CLI
│   │   └── websocket.ts     # Pub/sub for live updates
│   ├── client/
│   │   ├── index.html
│   │   ├── style.css
│   │   ├── app.js
│   │   └── components/
│   └── shared/
│       └── types.ts         # Shared DTOs and enums
├── data/                    # Houses SQLite DB (tracked via .gitkeep)
├── package.json
├── tsconfig.json
└── README.md

• Backend: Minimal HTTP handlers plus WebSocket broadcaster. Uses child processes for build/test commands and streams stdout/stderr line-by-line.
• Frontend: Single-page layout with sidebar test tree and main content area for build logs/stats/test detail.
• Shared Types: Keep WebSocket messages and HTTP responses type-safe and portable.
• Data Folder: Contains SQLite DB (devtools.db or similar). Only the .gitkeep file is tracked; DB files stay local.

Extending Statistics

1. Add a metric descriptor in src/server/stats.ts (name, units, query strategy).
2. Produce measurements after builds/tests (e.g., parse CLI output or inspect the Rae repo).
3. Insert into SQLite with optional JSON metadata ({ "commit": "...", "branch": "..." }).
4. Update frontend Chart.js config to display/select the metric.
5. Document the new metric in this README so contributors understand how it is sourced.

Development Phases

1. Core Infrastructure – project scaffolding, HTTP server, WebSocket plumbing, simple HTML shell.
2. Test Dashboard – command execution, parser, tree UI, diff view.
3. Build Controls – build/clean tooling with streaming output and status tracking.
4. Statistics – SQLite integration, data recording, and visualization widgets.
5. Polish – keyboard shortcuts, theming, Codex integration, accessibility.

Testing & Quality

• Unit tests for log parsing, stats persistence, and message serialization (to be added in src/server/__tests__).
• Manual checklist:
  • Build runs end-to-end and updates status indicator.
  • Full test suite plus "Run Failed" scenario.
  • SQLite stats entries appear after builds/tests and persist across restarts.
  • WebSocket reconnect handles server restarts gracefully.
  • UI remains responsive during long-running operations.

Future Ideas

• Run arbitrary Rae programs from the dashboard.
• Performance profiling overlays once Rae exposes profiling hooks.
• Benchmark suite tracking with regressions alerts.
• Git metadata correlation (stats + commits).
• Multi-project dashboards if Rae spawns additional repos.
• Plugin system for community metrics or custom panels.

Contributing

1. Fork/clone this repo alongside the main Rae compiler repo.
2. Configure the path/commands in config.json.
3. Work on one phase/feature at a time; keep abstractions simple.
4. Commit meaningful increments frequently (aim for 1–10 commits per day) and push once changes build/run cleanly.
5. Open PRs with screenshots or terminal captures so reviewers can visualize the UI.

Hub Workflow

The lightweight hub under hub/ coordinates all Rae work (compiler and devtools) via numbered tasks:

1. Queue a task in hub/QUEUE.md with a short summary and acceptance checks. Every task uses the T### - title format.
2. Move the task to hub/INPROGRESS.md once you start working. Create a branch named agent/<repo>/T###-slug in the relevant repo.
3. Log starts, completions, and verification commands in hub/LOG.md so the UI (and humans) can track progress.
4. When finished, record the outcome in hub/RESULTS/T###.md (summary + tests), run the acceptance checks, and remove the task from the queue.

The single-agent setup simply repeats these steps task-by-task, ensuring the devtools dashboard and the CLI stay in sync with the latest automation work.

License

Apache 2.0 (see LICENSE file).