bellona app

A minimal Manifest V3 browser extension for the remote-control surface (apps/bellona/remote-extension). Its public surface (src/index.ts) is a set of pure, adversarially-unit-tested security primitives: a closed-by-default origin allow-list that fails loud on <all_urls> (origin-policy.ts), extension-origin authentication and per-session token minting (extension-auth.ts), sensitive-action guards for clipboard/upload/form (action-guards.ts), a tamper-resistant shadow-DOM automation indicator (automation-indicator.ts), session teardown (session-lifecycle.ts), and manifest domain-scoping invariants (manifest-policy.ts). The README is candid that the Chrome-runtime wiring (background.ts, content-script.ts) is "a thin shell" that cannot load in CI, so the logic is tested through the pure functions — a deliberate dependency-boundary approach, not a stub.

The remote creative-control plane gateway (apps/bellona/remote-gateway/src/app.ts), described as a Phase-180 walking skeleton but in fact a large, real control plane. createRemoteGatewayApp(...) composes a node http server exposing health/readiness plus /v1 endpoints for devices, commands, sessions, streams, approvals, artifacts, timeline, audit export, and pairing exchange, alongside a WS /v1/hosts/connect host channel. It owns a @bellona/remote-protocol-validated device registry, a command dispatcher that runs every command through the shared permission policy (capability scopes, approval gating, fail-closed on audit-store outages except read-only diagnostics), a hash-chained audit log, an approval service with deny-by-default expiry, one-time CSPRNG pairing codes, HMAC host tokens, session-lifecycle and stream registries, and in-memory telemetry. State is ephemeral by default but can opt into a documented first-stage atomic-JSON persistent store (schema v3 with forward migration). The honest boundary: it orchestrates and audits commands but executes nothing itself — real work happens on the connected host.

The remote host process that runs on the controlled workstation (apps/bellona/remote-host). It loads a macOS-Keychain-backed device identity, opens an outbound WebSocket to the gateway with bounded reconnect, and runs a host command executor that emits protocol-valid progress/result/error events. Its adapter registry is where the implemented-vs-mocked split is sharpest, and the README is unusually explicit about it: the Blender adapter is real (loopback-only discovery of the repo's addon/bridge, then a large canonical command surface — scene info, object/collection/material/modifier/mesh-edit mutations, asset import/export — each wrapped with before/after scene-info evidence and undo checkpoints); the browser adapter really launches Chrome/Chromium through Playwright bound to loopback CDP with blocked-domain policy; the desktop fallback adapter is macOS-only and shells real Swift CoreGraphics/AppKit helpers for screenshot/window/click/type/clipboard with fail-closed redaction; the Unreal adapter's project.info/world.query/ actor.spawn are deterministic mocks that validate the protocol schemas but do not yet drive a live editor. The command-policy preflight is honestly named a ...policy-preflight-stub pending the real policy package. Many capabilities are macOS-specific and report not-applicable elsewhere.

The Bellona game-development CLI (apps/bellona/cli/src/index.ts), built on commander + chalk. The bellona program registers command groups for build, export, sync (engine sync/push/conflicts), config, health, project/detect, and remote — the last being the remote creative-control plane client (pair, devices, sessions, stream, command, approve, diagnose, artifacts, audit export, unpair). It talks to the build API over HTTP (default http://localhost:3020) and to the remote gateway through src/utils/remote-client.ts. Quick aliases (b, e) re-parse into the canonical subcommands. A real, fully-wired CLI, not a scaffold.

The browser-first operator surface for the Phase-180 remote-control MVP (apps/bellona/control-room, a React + Vite app). It is explicitly scaffolded behind the VITE_BELLONA_CONTROL_ROOM_ENABLED feature flag (disabled by default, including production), and the README is clear that "no gateway, host, desktop, browser, Blender, or Unreal privileges are exposed from this scaffold" and queued commands record an audit preview rather than dispatching to a live host. Within that boundary the UI logic is substantial and real: an approval queue with keyboard shortcuts, a command palette sourced from REMOTE_COMMAND_NAMESPACE_VALUES, command search, a first-session guided tour, device permission diagnostics, a mobile-approval PWA route with a service worker, plus i18n and a11y modules — all fixture-backed (@bellona/remote-protocol fixtures) and exercised by Vitest + Playwright. Honest status: real, flag-gated, fixture-driven operator UI; not yet connected to a live gateway.

A standalone WebSocket bridge service for Blender (apps/bellona/bridge-blender/src/main.ts). createBlenderBridge() starts a @bellona/bridge-core server on ws://localhost:9001/blender, registers handshake/ping plus six Blender commands (blender:get-scene-info, create-object, import-asset, export-asset, set-frame, render), and forwards each to a connected blender-plugin client via forwardToEngine(...), returning the engine's real reply. It is the most fleshed-out bridge: it also tracks per-connection SessionMetadata and publishes BellonaSessionStarted/SessionEnded events through @bellona/event-publisher. Real proxy logic; the Blender-side addon that answers the commands lives outside this directory.

The Godot Engine WebSocket bridge (apps/bellona/bridge-godot/src/main.ts). createGodotBridge() listens on ws://localhost:9002/godot and registers nine Godot-specific commands covering the scene tree, node creation/property/method calls, scene and resource loading, signal emission, GDScript execution (with a 60s timeout), and project settings — each proxied to a connected godot-plugin client. Same forward-or-throw contract as the other bridges; it does not yet wire the event-publisher session tracking that the Blender bridge has.

The Unity Engine WebSocket bridge (apps/bellona/bridge-unity/src/main.ts), listening on ws://localhost:9004/unity. It registers the largest command set of the four — fourteen commands spanning GameObject create/destroy, component add/set, scene load/unload, prefab instantiation, transforms, Animator play/parameter, Rigidbody force, physics raycast, and SendMessage. Notable detail: this entrypoint ships its own small LOG_LEVEL-aware logger (routing through console.warn/console.error) to honour the Bellona logging contract without pulling a non-Bellona dependency into the standalone process. Commands are proxied to a connected unity-plugin client.

The Unreal Engine WebSocket bridge (apps/bellona/bridge-unreal/src/main.ts), listening on ws://localhost:9003/unreal. It registers eleven commands: world info, actor spawn/destroy/property, Blueprint function calls, streaming level load/unload, material parameters, Sequencer control, console-command execution, and screenshots — all forwarded to a connected unreal-plugin client. Structurally identical to the Godot/Unity bridges (forward-or-throw, console logging), specialised to Unreal's actor/level/Sequencer vocabulary.

The build/export API service (apps/bellona/build-api/src/main.ts). It owns a content-addressable build cache (createBuildCacheService, 100 MB in-memory tier over a 10 GB Redis tier with compression and deduplication) and wires cross-domain event handlers via @bellona/event-handlers and @oshun/event-bus so build/export requests arriving as events are enqueued. Its build/export queue adapters (createBuildQueueAdapter, createExportQueueAdapter) use Redis pipelines (hset/zadd/sadd, priority-scored pending sets) when REDIS_URL is set and fall back to in-memory Maps otherwise — an honest degraded mode, logged as backend: 'memory', not a fake. Exposes initialize/shutdown/getHealthStatus with real cache-hit-rate stats.

The build worker service (apps/bellona/build-worker/src/main.ts). BuildWorkerService is a polling job runner: it dequeues from a JobQueue and dispatches to four real workers — processAssetBakeJob, processValidationJob, processEngineProjectJob, processExportPackageJob — emitting progress and publishing BellonaBuildStarted/Progress/Completed and ExportStarted/Ready events. The work is genuine: asset-bake-worker.ts hashes files with SHA-256 and shells out to real tools (sharp/ImageMagick for textures, ffmpeg for audio, gltf-pipeline for models) via execFile. The service tracks completed/failed counts, average duration, heartbeats, retry-on-fail, and graceful shutdown that drains the in-flight job.

The render API service (apps/bellona/render-api/src/main.ts). It initialises a Redis-backed render cache (createRenderCacheService) — real content-addressable storage with pub/sub invalidation, distributed locking, LRU eviction, and TTL tiers for jobs/outputs/progress/metadata drawn from @oshun/cache. Behind it sits a GPU render queue (src/queue/gpu-queue.ts) that tracks GPU devices, memory, priority queuing, concurrent-job limits, timeouts, retries, and health checks, plus an output validator (src/validation/). Exposes the same initialize/shutdown/getHealthStatus lifecycle as the build API. The caching and queue-management logic is real; the GPU device list is the resource it schedules against.