@buoy-gg/sync-broker 4.0.1

package/LICENSE

@@ -0,0 +1,58 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-present Buoy. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+
+NOTICE: This is NOT open source software. This software is licensed,
+not sold, and is protected by copyright laws and international treaties.
+
+TERMS AND CONDITIONS:
+
+1. LICENSE GRANT
+   Subject to the terms of this Agreement and payment of applicable fees,
+   Buoy grants you a limited, non-exclusive, non-transferable license
+   to use the compiled software packages in your applications.
+
+2. RESTRICTIONS
+   You may NOT:
+   - Copy, modify, or distribute the source code
+   - Reverse engineer, decompile, or disassemble the software
+   - Remove or alter any proprietary notices or labels
+   - Sublicense, rent, lease, or lend the software
+   - Use the software to create competing products
+   - Share access credentials with unauthorized parties
+
+3. OWNERSHIP
+   React Buoy retains all right, title, and interest in the software,
+   including all intellectual property rights. This license does not
+   grant you any rights to trademarks or service marks.
+
+4. TERMINATION
+   This license is effective until terminated. Your rights under this
+   license will terminate automatically without notice if you fail to
+   comply with any of its terms. Upon termination, you must cease all
+   use and destroy all copies of the software.
+
+5. DISCLAIMER OF WARRANTIES
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL BUOY BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN
+   CONNECTION WITH THIS LICENSE OR THE USE OF THE SOFTWARE.
+
+7. GOVERNING LAW
+   This Agreement shall be governed by and construed in accordance with
+   the laws of the United States, without regard to its conflict of
+   law provisions.
+
+For licensing inquiries and subscription information:
+- Website: https://buoy.gg
+- Email: AustinLovesWorking@gmail.com
+
+Unauthorized reproduction or distribution of this software, or any
+portion of it, may result in severe civil and criminal penalties,
+and will be prosecuted to the maximum extent possible under the law.

package/README.md

@@ -0,0 +1,55 @@
+# @buoy-gg/sync-broker
+
+Headless Socket.IO **broker** for the Buoy devtool sync protocol (v1).
+
+This is the message router that sits between **devices** (React Native apps running a Buoy devtool, connected as Socket.IO clients) and **dashboard clients** (the Buoy desktop app, and the Buoy MCP server). It was extracted from the desktop app's `apps/desktop/src/server` so the same implementation can be hosted by either:
+
+- the **desktop app** (which owns its own express/http server), or
+- a **standalone process** such as the Buoy MCP server, when no desktop app is running.
+
+## Usage
+
+### Host a complete broker (standalone / MCP)
+
+```ts
+import { createBroker, DEFAULT_BROKER_PORT } from "@buoy-gg/sync-broker";
+
+const broker = createBroker({
+  port: DEFAULT_BROKER_PORT, // 42831
+  onListening: (port) => console.log(`broker listening on ${port}`),
+  onError: (err) => {
+    if (err.code === "EADDRINUSE") {
+      // Another broker (e.g. the desktop app) already owns the port —
+      // connect to it as a client instead of hosting your own.
+    }
+  },
+});
+
+// later
+await broker.close();
+```
+
+### Attach to an existing Socket.IO server (desktop app)
+
+```ts
+import { Server } from "socket.io";
+import { socketHandle } from "@buoy-gg/sync-broker";
+
+const io = new Server(httpServer, socketOptions);
+socketHandle({ io });
+```
+
+## Protocol
+
+The wire contract (events, message shapes, watch/backpressure model) is **v1**, canonically defined in [`@buoy-gg/external-sync`](../external-sync). The broker reproduces the server-relevant types in `src/protocol.ts` to stay a dependency-light Node package (no React Native / `socket.io-client`).
+
+Topology and message flow:
+
+- Devices connect with a handshake carrying `deviceId`, `platform`, etc.
+- Dashboard clients connect with `deviceName: "Dashboard"` (exact, no suffix).
+- Devices announce `devtool-capabilities`; the broker replays them to dashboards.
+- Dashboards `devtool-watch` tools; the broker **consolidates** watch counts so a device receives a single `watching` true/false per `(device, tool)` regardless of how many dashboards are watching.
+- Dashboards invoke `devtool-action`; devices reply `devtool-action-result`.
+- Devices push `devtool-sync` snapshots; the broker forwards them to dashboards.
+
+> **Security:** dev-only. No authentication, CORS is open (`*`), intended for loopback / trusted LAN.

package/dist/index.d.mts

@@ -0,0 +1,167 @@
+import { Server, ServerOptions } from 'socket.io';
+import http from 'http';
+
+type DefaultEventsMap = Record<string, (...args: any[]) => void>;
+interface Props {
+    io: Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>;
+}
+/**
+ * Server-side socket handler that manages:
+ * - Communication between devices and dashboard
+ * - User connection tracking
+ * - Query state synchronization
+ * - Action forwarding
+ */
+declare function socketHandle({ io }: Props): void;
+
+/** Default port the Buoy sync broker listens on. */
+declare const DEFAULT_BROKER_PORT = 42831;
+/**
+ * Socket.IO server config shared by every broker host (the desktop app and the
+ * standalone/MCP host). Mirrors the desktop's historical config.
+ */
+declare const SOCKET_CONFIG: Partial<ServerOptions>;
+interface CreateBrokerOptions {
+    /** Port to listen on. @default DEFAULT_BROKER_PORT (42831) */
+    port?: number;
+    /**
+     * Extra Socket.IO server options merged over {@link SOCKET_CONFIG}. Use to
+     * override CORS, transports, etc. for a specific host.
+     */
+    socketOptions?: Partial<ServerOptions>;
+    /** Called once the broker is listening. */
+    onListening?: (port: number) => void;
+    /**
+     * Called on a server error. `EADDRINUSE` means another broker (e.g. the
+     * desktop app) already owns the port — the caller should connect to it as a
+     * client instead of hosting its own. Headless on purpose: no UI/dialog here,
+     * unlike the Electron app which surfaces a native dialog.
+     */
+    onError?: (error: NodeJS.ErrnoException) => void;
+}
+interface BrokerHandle {
+    /** The underlying Socket.IO server. */
+    io: Server;
+    /** The underlying HTTP server. */
+    httpServer: http.Server;
+    /** The port the broker is listening on. */
+    port: number;
+    /** Stop the broker and release the port. */
+    close: () => Promise<void>;
+}
+/**
+ * Create and start a headless Buoy sync broker: an HTTP + Socket.IO server with
+ * the devtool sync protocol (v1) message routing attached. This is the same
+ * broker the desktop app embeds, extracted so a standalone process (the MCP
+ * server) can host one when no desktop app is running.
+ *
+ * Connect-or-spawn pattern: a client should first try to connect to a running
+ * broker on the port; only if that fails should it call `createBroker` to host
+ * its own. An `EADDRINUSE` from {@link CreateBrokerOptions.onError} means the
+ * port was taken between the probe and the spawn — fall back to connecting.
+ */
+declare function createBroker(options?: CreateBrokerOptions): BrokerHandle;
+
+/**
+ * DEVTOOL SYNC PROTOCOL (v1) — server-side wire contract.
+ *
+ * Canonical source of truth for these shapes is `@buoy-gg/external-sync`
+ * (packages/external-sync/src/types.ts). They are reproduced here so the
+ * broker stays a self-contained Node package with no React Native / client
+ * dependency (external-sync pulls in `socket.io-client` + RN). The shapes are
+ * structurally compatible — keep them in sync when the protocol version bumps.
+ *
+ * Topology: devices are Socket.IO *clients*; this broker hosts the Socket.IO
+ * *server* and routes messages between devices and one or more "Dashboard"
+ * clients (the desktop app today, the MCP server tomorrow).
+ */
+/** Version of the envelope/event contract itself (not tool payloads). */
+declare const SYNC_PROTOCOL_VERSION = 1;
+/** What a sync payload represents. "events"/"diff" reserved for future use. */
+type SyncKind = "snapshot";
+/** Announces available tools + actions on connect and when tools change. */
+interface DeviceCapabilitiesMessage {
+    persistentDeviceId: string;
+    protocolVersion: number;
+    tools: ToolCapability[];
+}
+interface ToolCapability {
+    toolId: string;
+    version: number;
+    actions: string[];
+}
+/** Carries a tool's state to the dashboard. */
+interface DevToolSyncMessage {
+    toolId: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    /** Tool payload version (ToolSyncAdapter.version). */
+    version: number;
+    kind: SyncKind;
+    payload: unknown;
+}
+/** Response to a `devtool-action` request. */
+interface DevToolActionResultMessage {
+    requestId: string;
+    toolId: string;
+    action: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    ok: boolean;
+    /** Present when ok. JSON-serializable value returned by the action. */
+    result?: unknown;
+    /** Present when not ok. */
+    error?: string;
+}
+/** Server-consolidated signal that a tool gained/lost its audience. */
+interface DevToolWatchMessage {
+    toolId: string;
+    targetDeviceId: string;
+    watching: boolean;
+}
+/** Explicit request for a tool's current state (works even while unwatched). */
+interface DevToolRequestMessage {
+    toolId: string;
+    targetDeviceId: string;
+}
+/** Invokes a registered action on the device. */
+interface DevToolActionMessage {
+    requestId: string;
+    toolId: string;
+    targetDeviceId: string;
+    action: string;
+    params?: unknown;
+}
+/**
+ * A connected client (device or dashboard) as tracked by the broker.
+ * Mirrors the desktop dashboard's `User` type; the dashboard UI carries a few
+ * extra presentational fields, but the broker only needs these.
+ */
+interface User {
+    id: string;
+    deviceName: string;
+    /**
+     * Persisted device ID. Optional because dashboard clients (the desktop app /
+     * MCP server) connect with `deviceName: "Dashboard"` and no deviceId — only
+     * real devices carry one.
+     */
+    deviceId?: string;
+    platform?: string;
+    isConnected?: boolean;
+    extraDeviceInfo?: string;
+    envVariables?: string;
+    /**
+     * Per-socket-instance identifier the device sends in its handshake. Stays
+     * constant across socket.io reconnects of the SAME client, but changes when
+     * the app creates a fresh socket (remount / Fast Refresh / duplicate mount).
+     */
+    connectionNonce?: string;
+    /** The socket.io reason for this client's most recent disconnect. */
+    lastDisconnectReason?: string;
+    /** Whether the device announced an active Buoy Pro license. */
+    isPro?: boolean;
+    /** The device's Buoy Pro license key, if any. Local dev connection only. */
+    licenseKey?: string;
+}
+
+export { type BrokerHandle, type CreateBrokerOptions, DEFAULT_BROKER_PORT, type DevToolActionMessage, type DevToolActionResultMessage, type DevToolRequestMessage, type DevToolSyncMessage, type DevToolWatchMessage, type DeviceCapabilitiesMessage, SOCKET_CONFIG, SYNC_PROTOCOL_VERSION, type SyncKind, type ToolCapability, type User, createBroker, socketHandle };

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { Server, ServerOptions } from 'socket.io';
+import http from 'http';
+
+type DefaultEventsMap = Record<string, (...args: any[]) => void>;
+interface Props {
+    io: Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>;
+}
+/**
+ * Server-side socket handler that manages:
+ * - Communication between devices and dashboard
+ * - User connection tracking
+ * - Query state synchronization
+ * - Action forwarding
+ */
+declare function socketHandle({ io }: Props): void;
+
+/** Default port the Buoy sync broker listens on. */
+declare const DEFAULT_BROKER_PORT = 42831;
+/**
+ * Socket.IO server config shared by every broker host (the desktop app and the
+ * standalone/MCP host). Mirrors the desktop's historical config.
+ */
+declare const SOCKET_CONFIG: Partial<ServerOptions>;
+interface CreateBrokerOptions {
+    /** Port to listen on. @default DEFAULT_BROKER_PORT (42831) */
+    port?: number;
+    /**
+     * Extra Socket.IO server options merged over {@link SOCKET_CONFIG}. Use to
+     * override CORS, transports, etc. for a specific host.
+     */
+    socketOptions?: Partial<ServerOptions>;
+    /** Called once the broker is listening. */
+    onListening?: (port: number) => void;
+    /**
+     * Called on a server error. `EADDRINUSE` means another broker (e.g. the
+     * desktop app) already owns the port — the caller should connect to it as a
+     * client instead of hosting its own. Headless on purpose: no UI/dialog here,
+     * unlike the Electron app which surfaces a native dialog.
+     */
+    onError?: (error: NodeJS.ErrnoException) => void;
+}
+interface BrokerHandle {
+    /** The underlying Socket.IO server. */
+    io: Server;
+    /** The underlying HTTP server. */
+    httpServer: http.Server;
+    /** The port the broker is listening on. */
+    port: number;
+    /** Stop the broker and release the port. */
+    close: () => Promise<void>;
+}
+/**
+ * Create and start a headless Buoy sync broker: an HTTP + Socket.IO server with
+ * the devtool sync protocol (v1) message routing attached. This is the same
+ * broker the desktop app embeds, extracted so a standalone process (the MCP
+ * server) can host one when no desktop app is running.
+ *
+ * Connect-or-spawn pattern: a client should first try to connect to a running
+ * broker on the port; only if that fails should it call `createBroker` to host
+ * its own. An `EADDRINUSE` from {@link CreateBrokerOptions.onError} means the
+ * port was taken between the probe and the spawn — fall back to connecting.
+ */
+declare function createBroker(options?: CreateBrokerOptions): BrokerHandle;
+
+/**
+ * DEVTOOL SYNC PROTOCOL (v1) — server-side wire contract.
+ *
+ * Canonical source of truth for these shapes is `@buoy-gg/external-sync`
+ * (packages/external-sync/src/types.ts). They are reproduced here so the
+ * broker stays a self-contained Node package with no React Native / client
+ * dependency (external-sync pulls in `socket.io-client` + RN). The shapes are
+ * structurally compatible — keep them in sync when the protocol version bumps.
+ *
+ * Topology: devices are Socket.IO *clients*; this broker hosts the Socket.IO
+ * *server* and routes messages between devices and one or more "Dashboard"
+ * clients (the desktop app today, the MCP server tomorrow).
+ */
+/** Version of the envelope/event contract itself (not tool payloads). */
+declare const SYNC_PROTOCOL_VERSION = 1;
+/** What a sync payload represents. "events"/"diff" reserved for future use. */
+type SyncKind = "snapshot";
+/** Announces available tools + actions on connect and when tools change. */
+interface DeviceCapabilitiesMessage {
+    persistentDeviceId: string;
+    protocolVersion: number;
+    tools: ToolCapability[];
+}
+interface ToolCapability {
+    toolId: string;
+    version: number;
+    actions: string[];
+}
+/** Carries a tool's state to the dashboard. */
+interface DevToolSyncMessage {
+    toolId: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    /** Tool payload version (ToolSyncAdapter.version). */
+    version: number;
+    kind: SyncKind;
+    payload: unknown;
+}
+/** Response to a `devtool-action` request. */
+interface DevToolActionResultMessage {
+    requestId: string;
+    toolId: string;
+    action: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    ok: boolean;
+    /** Present when ok. JSON-serializable value returned by the action. */
+    result?: unknown;
+    /** Present when not ok. */
+    error?: string;
+}
+/** Server-consolidated signal that a tool gained/lost its audience. */
+interface DevToolWatchMessage {
+    toolId: string;
+    targetDeviceId: string;
+    watching: boolean;
+}
+/** Explicit request for a tool's current state (works even while unwatched). */
+interface DevToolRequestMessage {
+    toolId: string;
+    targetDeviceId: string;
+}
+/** Invokes a registered action on the device. */
+interface DevToolActionMessage {
+    requestId: string;
+    toolId: string;
+    targetDeviceId: string;
+    action: string;
+    params?: unknown;
+}
+/**
+ * A connected client (device or dashboard) as tracked by the broker.
+ * Mirrors the desktop dashboard's `User` type; the dashboard UI carries a few
+ * extra presentational fields, but the broker only needs these.
+ */
+interface User {
+    id: string;
+    deviceName: string;
+    /**
+     * Persisted device ID. Optional because dashboard clients (the desktop app /
+     * MCP server) connect with `deviceName: "Dashboard"` and no deviceId — only
+     * real devices carry one.
+     */
+    deviceId?: string;
+    platform?: string;
+    isConnected?: boolean;
+    extraDeviceInfo?: string;
+    envVariables?: string;
+    /**
+     * Per-socket-instance identifier the device sends in its handshake. Stays
+     * constant across socket.io reconnects of the SAME client, but changes when
+     * the app creates a fresh socket (remount / Fast Refresh / duplicate mount).
+     */
+    connectionNonce?: string;
+    /** The socket.io reason for this client's most recent disconnect. */
+    lastDisconnectReason?: string;
+    /** Whether the device announced an active Buoy Pro license. */
+    isPro?: boolean;
+    /** The device's Buoy Pro license key, if any. Local dev connection only. */
+    licenseKey?: string;
+}
+
+export { type BrokerHandle, type CreateBrokerOptions, DEFAULT_BROKER_PORT, type DevToolActionMessage, type DevToolActionResultMessage, type DevToolRequestMessage, type DevToolSyncMessage, type DevToolWatchMessage, type DeviceCapabilitiesMessage, SOCKET_CONFIG, SYNC_PROTOCOL_VERSION, type SyncKind, type ToolCapability, type User, createBroker, socketHandle };