CLI Development Server & Session Metadata

Published Updated
Overview of Aircada's real-time hot-swapping development server, live-sync WebSocket channel, and .aircada/dev-session.json metadata discovery.

Developer Live-Reload Sync

Aircada CLI provides a real-time development mode (air dev) that establishes a localized WebSocket and HTTP/HTTPS server.

This mounts a high-performance, live-sync channel directly connecting your local filesystem with the active web-based AIRCADA STUDIO Panel viewport.

Dev Session Runtime Metadata (.aircada/dev-session.json)

When air dev launches, the CLI automatically writes real-time runtime metadata to <projectRoot>/.aircada/dev-session.json:

json
{
  "pid": 17492,
  "devPort": 9005,
  "projectRoot": "C:\\path\\to\\project",
  "projectId": "SwVpawyqDK1qpDKw",
  "name": "basic",
  "mode": "ui",
  "studioUrl": "https://localhost:3002/SwVpawyqDK1qpDKw?devPort=9005&mode=ui",
  "startedAt": "2026-09-15T17:08:40.483Z"
}

Automated tools, test scripts, and browser testing subagents inspect this file to obtain the exact studioUrl without trial-and-error port scanning or protocol guessing.

CLI Dev Server Hot-Swapping & Telemetry Architecture#

Technical breakdown of Chokidar file watchers, esbuild compilers, WebSocket telemetry, and APEX REST mutations.

Dev-Client WebSocket Bridge & State Preservation

Alongside code-update and build-error frames on Port 9005, the dev-client WebSocket bridge forwards live browser console and runtime telemetry back to the CLI terminal. During hot-swaps, AIR Engine snapshots active operator fields into _hot_snapshots_ and restores state after re-instantiation so live configurator selections persist across edits without a full page reload.

Dual-Channel Communication Architecture

During live development sessions (air dev), the CLI dev server coordinates files, bundles, and remote APEX instructions across a WebSocket (Port 9005), HTTP server, and REST API mutations pipeline:

mermaid
graph TD
    subgraph Local Workspace
        A[File Watcher: Chokidar] -->|Detects Change| B[Builder: Scan + Gen virtual entry]
        B -->|Compile Bundle| C[Bundler: esbuild]
        C -->|Raw JS Code| D[Dev Server]
    end

    subgraph Dual Communication Channel
        D -->|WS: code-update / build-error| E(WebSocket Server - Port 9005)
        D -->|HTTP: GET /bundle.js| F(HTTP Server - Port 9005)
        D -->|HTTP: POST /api/apex/execute| G(REST APEX endpoint)
    end

    subgraph Aircada Studio - Live Web App
        E <-->|WS Link| H[Studio Runtime Engine]
        H -->|Hot Swap Bundle| I[Interactive Preview]
        H -.->|Trigger remote mutation| G
    end

    classDef local fill:#2a2b36,stroke:#4a50ff,stroke-width:2px,color:#fff;
    classDef comm fill:#1c1d24,stroke:#39c362,stroke-width:2px,color:#fff;
    classDef cloud fill:#202127,stroke:#e95420,stroke-width:2px,color:#fff;

    class A,B,C,D local;
    class E,F,G comm;
    class H,I cloud;

Step-by-Step Hot Swap Loop

  1. File Watcher (Chokidar): Monitors your local src/ folder for TypeScript edits.
  1. Incremental Builder (esbuild): Re-compiles your bundle into an optimized virtual distribution output in milliseconds upon change.
  1. Telemetry Push: The Dev Server broadcasts a code-update WebSocket frame containing the raw JS bundle to the web dashboard runtime.
  1. Interactive Swap: The Aircada Studio runtime intercepts the WebSocket event, immediately evaluates the new logic block, and hot-swaps it into the active browser spatial preview without refreshing or losing session state.
  1. Dynamic Mutations (APEX REST): Interactive gestures or changes in Aircada Studio propagate remote mutation calls back to the REST APEX endpoint, maintaining synchronized local-to-cloud alignment.

Ephemeral Authentication Loopback Flow

Logging into the CLI (air login) coordinates securely with the browser without manual credentials copying via a custom loopback sequence:

mermaid
sequenceDiagram
    autonumber
    participant CLI as CLI (air login)
    participant OS as OS / Default Browser
    participant Cloud as Aircada Live Webapp
    participant LocalHost as Ephemeral Local HTTP Server

    CLI->>LocalHost: Bind to random port & register state token
    CLI->>OS: open(Aircada Studio Auth URL + Port + State)
    OS->>Cloud: Navigate to Auth Page
    Note over Cloud: User logs in via Web UI
    Cloud->>LocalHost: POST /auth-callback (Credentials + State)
    LocalHost->>LocalHost: Validate state token
    LocalHost-->>CLI: Resolve credentials payload
    CLI->>CLI: Encrypt and store locally in credentials.lock
    LocalHost->>Cloud: Response: Status 200 OK
    CLI->>LocalHost: Graceful shutdown & terminate server