@yoltra/devtools-server 0.2.0

package/dist/types/hub.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Central WebSocket hub that brokers DevTools protocol traffic.
+ *
+ * @module @yoltra/devtools-server
+ */
+/**
+ * Configuration for the DevTools hub server.
+ *
+ * @remarks
+ * All fields are optional; sensible defaults are applied when omitted.
+ *
+ * @public
+ */
+export interface DevtoolsHubOptions {
+    /** Port to bind on. @default 9800 */
+    port?: number;
+    /** Host to bind on. @default "127.0.0.1" (localhost only for v1 security) */
+    host?: string;
+    /** Maximum events retained in the ring buffer for late-connecting extensions. @default 1000 */
+    historySize?: number;
+    /**
+     * Extra WebSocket `Origin` values to accept, beyond the always-allowed set
+     * (no Origin, browser-extension origins, and loopback origins). Use this only
+     * for a non-loopback local dev host (e.g. a custom `.local` domain). Adding a
+     * remote origin re-opens the cross-site hijack surface — don't.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Central WebSocket hub that brokers messages between Yoltra stores and DevTools extensions.
+ *
+ * @remarks
+ * - Accepts WS connections, validates protocol handshakes, and routes messages.
+ * - Store events are fan-out to all extension clients.
+ * - Extension commands are routed to the target store by `storeId`.
+ * - Maintains a ring buffer of recent events for late-connecting extensions.
+ * - Binds to localhost only (v1 security).
+ *
+ * @example Embeddable usage
+ * ```ts
+ * import { DevtoolsHub } from '@yoltra/devtools-server';
+ *
+ * const hub = new DevtoolsHub({ port: 9800 });
+ * await hub.start();
+ * // ... later
+ * await hub.stop();
+ * ```
+ *
+ * @public
+ */
+export declare class DevtoolsHub {
+    private readonly port;
+    private readonly host;
+    private readonly allowedOrigins;
+    private readonly router;
+    private readonly history;
+    private wss;
+    /**
+     * Create a new DevTools hub instance.
+     *
+     * @param opts - Hub configuration. All fields are optional.
+     *
+     * @public
+     */
+    constructor(opts?: DevtoolsHubOptions);
+    /**
+     * Start the WebSocket server and begin accepting connections.
+     *
+     * @returns Resolves once the server is bound and listening.
+     * @throws If the underlying `WebSocketServer` emits an error during
+     *         startup (e.g. port already in use).
+     *
+     * @public
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server and close all connections.
+     *
+     * @remarks
+     * Existing client sockets are closed with code `1001` ("Going Away")
+     * before the server socket is torn down.
+     *
+     * @returns Resolves once the server has fully shut down.
+     *
+     * @public
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if a DevTools hub is already running on the given port.
+     *
+     * @param port - Port to probe.
+     * @returns `true` if a hub is listening and responds to handshake.
+     *
+     * @public
+     */
+    static probe(port: number): Promise<boolean>;
+    /**
+     * Handle a new WebSocket connection: wait for handshake, then route messages.
+     *
+     * @remarks
+     * Starts a handshake timeout timer. If the first valid message is a
+     * `HANDSHAKE_REQUEST` the connection is promoted to a routed client;
+     * otherwise it is closed after {@link HANDSHAKE_TIMEOUT_MS}.
+     *
+     * @param ws - Newly accepted WebSocket.
+     */
+    private handleConnection;
+    /**
+     * Process a handshake request: validate, register, and respond.
+     *
+     * @remarks
+     * Performs a major-version compatibility check against
+     * {@link PROTOCOL_VERSION}. On success the connection is registered with
+     * the {@link Router} and post-handshake side-effects are triggered
+     * (store-connected broadcast or registry + history replay).
+     *
+     * @param ws  - The client WebSocket.
+     * @param req - Parsed handshake request payload.
+     * @returns The new {@link ConnectionInfo} on success, or `null` if the
+     *          handshake was rejected.
+     */
+    private handleHandshake;
+    /**
+     * Route a post-handshake message based on the sender's role.
+     *
+     * @remarks
+     * Store messages are fanned-out to all extensions and, if the message
+     * type is `STORE_EVENT`, buffered in the ring buffer for replay.
+     * Extension messages are forwarded to the store identified by
+     * `msg.storeId`.
+     *
+     * @param sender - Connection info of the sending client.
+     * @param msg    - Parsed message payload (untyped; serialized internally).
+     */
+    private routeMessage;
+    /**
+     * Handle a client disconnection.
+     *
+     * @remarks
+     * Unregisters the client from the {@link Router}. If the client was a
+     * store, a `STORE_DISCONNECTED` event is broadcast to all extensions.
+     *
+     * @param info - Connection info of the disconnected client.
+     */
+    private handleDisconnect;
+    /**
+     * Current number of connected stores.
+     *
+     * @public
+     */
+    get storeCount(): number;
+    /**
+     * Current number of connected extensions.
+     *
+     * @public
+     */
+    get extensionCount(): number;
+    /**
+     * Number of events in the history ring buffer.
+     *
+     * @public
+     */
+    get historySize(): number;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module @yoltra/devtools-server
+ *
+ * Central WebSocket hub for the Yoltra DevTools suite.
+ * Can be used as an embeddable library or a standalone CLI server.
+ */
+export { main as startCli } from './cli';
+export { DevtoolsHub } from './hub';
+export type { DevtoolsHubOptions } from './hub';
+export { RingBuffer } from './ring-buffer';

package/dist/types/ring-buffer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Fixed-size circular buffer for bounded event retention.
+ *
+ * @module @yoltra/devtools-server
+ */
+/**
+ * Fixed-size circular buffer that overwrites the oldest entry on overflow.
+ *
+ * @typeParam T - Item type stored in the buffer.
+ *
+ * @remarks
+ * Used by the hub to retain event history for late-connecting extensions.
+ * The buffer pre-allocates an array of the given capacity and uses modular
+ * arithmetic to track insertion position, making {@link push} an O(1)
+ * operation with no memory allocation after construction.
+ *
+ * @public
+ */
+export declare class RingBuffer<T> {
+    readonly capacity: number;
+    private readonly items;
+    private head;
+    private count;
+    /**
+     * @param capacity - Maximum number of items. Must be at least 1.
+     */
+    constructor(capacity: number);
+    /**
+     * Push an item. Overwrites the oldest if at capacity.
+     *
+     * @param item - Item to add.
+     *
+     * @public
+     */
+    push(item: T): void;
+    /**
+     * Returns all items in insertion order (oldest first).
+     *
+     * @returns A new array containing buffered items from oldest to newest.
+     *
+     * @public
+     */
+    toArray(): T[];
+    /**
+     * Current number of items stored in the buffer.
+     *
+     * @returns A value between `0` and {@link capacity} inclusive.
+     *
+     * @public
+     */
+    get size(): number;
+    /**
+     * Remove all items.
+     *
+     * @public
+     */
+    clear(): void;
+}

package/dist/types/router.d.ts

@@ -0,0 +1,118 @@
+import { DevtoolsRole } from '@yoltra/devtools-protocol';
+import { WebSocket } from 'ws';
+import { ConnectionInfo } from './connection';
+/**
+ * Routes DevTools protocol messages between stores and extensions.
+ *
+ * @remarks
+ * The router maintains two parallel maps -- one for store connections and
+ * one for extension connections -- and exposes helpers that implement the
+ * three core routing patterns of the DevTools protocol:
+ *
+ * - **Fan-out**: Store messages are forwarded to every connected extension.
+ * - **Targeted delivery**: Extension commands are routed to a specific
+ *   store identified by `storeId`.
+ * - **Lifecycle broadcast**: `STORE_CONNECTED` / `STORE_DISCONNECTED`
+ *   events are broadcast to all extensions whenever a store joins or
+ *   leaves.
+ *
+ * @public
+ */
+export declare class Router {
+    /** All store connections, keyed by store ID. */
+    private readonly stores;
+    /** All extension connections, keyed by extension ID. */
+    private readonly extensions;
+    /**
+     * Register a newly handshaked connection.
+     *
+     * @param info - Connection info from the completed handshake.
+     *
+     * @public
+     */
+    register(info: ConnectionInfo): void;
+    /**
+     * Remove a connection by ID.
+     *
+     * @param id - Client ID to remove.
+     * @param role - Client role (`STORE` or `EXTENSION`).
+     *
+     * @public
+     */
+    unregister(id: string, role: DevtoolsRole): void;
+    /**
+     * Get the WebSocket for a specific store.
+     *
+     * @param storeId - Store UUID.
+     * @returns The store's WebSocket, or `undefined` if not connected.
+     *
+     * @public
+     */
+    getStoreSocket(storeId: string): WebSocket | undefined;
+    /**
+     * Route a message from a store to all extensions (fan-out).
+     *
+     * @remarks
+     * Only sends to extensions whose WebSocket is in the `OPEN` ready-state;
+     * connections in a closing or closed state are silently skipped.
+     *
+     * @param message - Serialized JSON message string.
+     *
+     * @public
+     */
+    fanOutToExtensions(message: string): void;
+    /**
+     * Route a message from an extension to a specific store.
+     *
+     * @param storeId - Target store UUID.
+     * @param message - Serialized JSON message string.
+     * @returns `true` if the message was sent, `false` if the store was
+     *          not found or its socket was not open.
+     *
+     * @public
+     */
+    sendToStore(storeId: string, message: string): boolean;
+    /**
+     * Build a `STORE_CONNECTED` broadcast message.
+     *
+     * @param info - Store connection info (must have {@link ConnectionInfo.storeInfo}).
+     * @returns Serialized {@link StoreConnected} JSON string.
+     *
+     * @public
+     */
+    buildStoreConnectedMessage(info: ConnectionInfo): string | null;
+    /**
+     * Build a `STORE_DISCONNECTED` broadcast message.
+     *
+     * @param storeId - Disconnected store ID.
+     * @param reason - Optional human-readable disconnect reason.
+     * @returns Serialized {@link StoreDisconnected} JSON string.
+     *
+     * @public
+     */
+    buildStoreDisconnectedMessage(storeId: string, reason?: string): string;
+    /**
+     * Build a `STORE_REGISTRY` message listing all connected stores.
+     *
+     * @returns Serialized {@link StoreRegistry} JSON string.
+     *
+     * @public
+     */
+    buildRegistryMessage(): string;
+    /**
+     * Number of connected stores.
+     *
+     * @returns Current store connection count.
+     *
+     * @public
+     */
+    get storeCount(): number;
+    /**
+     * Number of connected extensions.
+     *
+     * @returns Current extension connection count.
+     *
+     * @public
+     */
+    get extensionCount(): number;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@yoltra/devtools-server",
+  "version": "0.2.0",
+  "description": "Hub WebSocket server for Yoltra DevTools — standalone CLI and embeddable library",
+  "license": "MIT",
+  "author": {
+    "name": "Manu Ramirez <@pixerael>",
+    "email": "manu@yoltra.dev"
+  },
+  "maintainers": [],
+  "homepage": "https://yoltra.dev",
+  "keywords": [
+    "yoltra",
+    "devtools",
+    "server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yoltra/yoltra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yoltra/yoltra/issues"
+  },
+  "type": "module",
+  "main": "dist/devtools-server.cjs.js",
+  "module": "dist/devtools-server.esm.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/devtools-server.esm.js",
+      "require": "./dist/devtools-server.cjs.js"
+    }
+  },
+  "bin": {
+    "devtools-server": "./bin/devtools-server.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ws": "^8.19.0",
+    "@yoltra/devtools-protocol": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "@types/node": "^24.0.12",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "4.9.0",
+    "typedoc-plugin-localization": "3.0.6",
+    "typescript": "5.9.3",
+    "vite": "^7.1.11",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-banner": "0.8.1",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest --watch=false",
+    "lint": "node ../../tools/repo-tools/bin/repo-eslint.cjs --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "docs": "rushx docs:js && rushx docs:md",
+    "docs:md": "pnpm typedoc --options ./typedoc.json",
+    "docs:js": "pnpm typedoc --options ./typedoc.json --json ./.typedoc/devtools-server-en.json",
+    "start": "node bin/devtools-server.js"
+  }
+}