@wendoo/bridge-app 0.2.2

package/README.md

@@ -0,0 +1,44 @@
+# @wendoo/bridge-app
+
+App-side client for the Wendoo bridge.
+
+Wraps `@wendoo/bridge-client` with app-role-specific behavior: automatic join code
+management and the `"app"` WebSocket path. Apps that connect to the bridge should depend on
+this package rather than using `bridge-client` directly.
+
+## Usage
+
+```typescript
+import { createAppBridge } from "@wendoo/bridge-app";
+import { createCompilationFeature } from "@wendoo/bridge-app/compilation";
+
+const bridge = createAppBridge({
+  appName: "My App",
+  bridgeUrl: "ws://localhost:6464",
+  filesystem: myProjectFileSystem,
+  features: [createCompilationFeature({ compiler })],
+});
+
+bridge.start();
+```
+
+The bridge facade supports:
+
+- `start()` / `stop()` -- lifecycle management
+- `requestSync()` -- request a full project file sync from the VS Code extension
+- `snapshot()` -- current connection status and join code
+- `onStateChange(...)` / `onRemoteChange(...)` -- event subscriptions
+
+Optional features (like compilation) attach through the `features` array and receive
+a `AppBridgeFeatureContext` with project file access, sync hooks, and diagnostic/status
+publication helpers.
+
+## Install
+
+```sh
+npm install @wendoo/bridge-app
+```
+
+## License
+
+MIT

package/dist/app-bridge.d.ts

@@ -0,0 +1,77 @@
+import type { ProjectFileChange, ProjectFileSnapshot, ProjectFileSystem } from "@wendoo/app-host";
+import type { ConnectionStatus } from "@wendoo/bridge-client";
+import type { CompileDiagnosticEntry } from "@wendoo/bridge-protocol";
+export type { ProjectFileSystem, ProjectFileChange, ProjectFileSnapshot };
+/** Connection status of the underlying bridge session. */
+export type AppBridgeState = ConnectionStatus;
+/** A single compiler diagnostic entry surfaced through the bridge. */
+export type DiagnosticEntry = CompileDiagnosticEntry;
+/**
+ * App-side handle for a Wendoo bridge session. Owns the lifecycle of the
+ * underlying connection and forwards local project file edits to and from the
+ * remote peer.
+ */
+export interface AppBridge {
+    /** Open the bridge connection. No-op if already started. */
+    start(): void;
+    /** Close the bridge connection and release resources. */
+    stop(): void;
+    /** Request a full project file resync from the peer. */
+    requestSync(): Promise<void>;
+    /** Read the current connection state. */
+    snapshot(): AppBridgeSnapshot;
+    /** Subscribe to connection-state changes. Returns an unsubscribe function. */
+    onStateChange(listener: (state: AppBridgeState) => void): () => void;
+    /** Subscribe to project file changes pushed by the remote peer. */
+    onRemoteChange(listener: (change: ProjectFileChange) => void): () => void;
+}
+/** Snapshot of the bridge connection state. */
+export interface AppBridgeSnapshot {
+    status: AppBridgeState;
+    /** Code the user pastes into the peer to bind the session, when available. */
+    joinCode?: string;
+}
+/** Options for {@link createAppBridge}. */
+export interface AppBridgeOptions {
+    bridgeUrl: string;
+    filesystem: ProjectFileSystem;
+    /** Optional features attached to the bridge for the duration of each session. */
+    features?: readonly AppBridgeFeature[];
+    /** Persisted token used to rebind to a previously established session. */
+    bindingToken?: string;
+    /** Callback invoked whenever the server issues an updated binding token. */
+    onBindingTokenChange?: (token: string) => void;
+}
+/**
+ * Pluggable extension to {@link AppBridge}. `attach` is invoked when the bridge
+ * starts and must return a disposer that cleans up when the bridge stops.
+ */
+export interface AppBridgeFeature {
+    attach(context: AppBridgeFeatureContext): () => void;
+}
+/** Context passed to an {@link AppBridgeFeature} on attach. */
+export interface AppBridgeFeatureContext {
+    snapshot(): AppBridgeSnapshot;
+    projectFileSnapshot(): ProjectFileSnapshot;
+    onStateChange(listener: (state: AppBridgeState) => void): () => void;
+    onRemoteChange(listener: (change: ProjectFileChange) => void): () => void;
+    /** Subscribe to full project file sync completions from the peer. */
+    onDidSync(listener: () => void): () => void;
+    /** Send the diagnostics for `file` to the peer. */
+    publishDiagnostics(file: string, diagnostics: readonly DiagnosticEntry[]): void;
+    /** Send a compile pass/fail status update for `file` to the peer. */
+    publishStatus(update: AppBridgeFeatureStatus): void;
+}
+/** Per-file compile status published by features through {@link AppBridgeFeatureContext}. */
+export interface AppBridgeFeatureStatus {
+    file: string;
+    /** `true` when the file compiled with no errors. */
+    success: boolean;
+    diagnosticCount: {
+        error: number;
+        warning: number;
+    };
+}
+/** Create an {@link AppBridge}. */
+export declare function createAppBridge(options: AppBridgeOptions): AppBridge;
+//# sourceMappingURL=app-bridge.d.ts.map

package/dist/app-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-bridge.d.ts","sourceRoot":"","sources":["../src/app-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAIxF,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAC;AAC1E,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAC9C,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAC;IACd,yDAAyD;IACzD,IAAI,IAAI,IAAI,CAAC;IACb,wDAAwD;IACxD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,8EAA8E;IAC9E,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACrE,mEAAmE;IACnE,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3E;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAAC;CACtD;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,mBAAmB,IAAI,mBAAmB,CAAC;IAC3C,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACrE,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1E,qEAAqE;IACrE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,mDAAmD;IACnD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAAC;IAChF,qEAAqE;IACrE,aAAa,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACrD;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAEpE"}

package/dist/app-bridge.js

@@ -0,0 +1,205 @@
+import { BridgeProject } from "./bridge-project.js";
+import { toFileSystemNotification, toFileSystemSnapshot, toProjectFileChange } from "./project-file-bridge.js";
+/** Create an {@link AppBridge}. */
+export function createAppBridge(options) {
+    return new AppBridgeController(options);
+}
+class AppBridgeController {
+    _options;
+    _stateListeners = new Set();
+    _remoteChangeListeners = new Set();
+    _syncListeners = new Set();
+    _diagnosticVersions = new Map();
+    _featureDisposers = [];
+    _project;
+    _filesystemUnsub;
+    _projectUnsubs = [];
+    _status = "disconnected";
+    _joinCode;
+    constructor(options) {
+        this._options = options;
+    }
+    start() {
+        if (this._project) {
+            return;
+        }
+        this.attachFeatures();
+        const project = new BridgeProject({
+            bridgeUrl: this._options.bridgeUrl,
+            initialFileSnapshot: toFileSystemSnapshot(this._options.filesystem.exportSnapshot()),
+            bindingToken: this._options.bindingToken,
+        });
+        this._project = project;
+        this._filesystemUnsub = this._options.filesystem.onLocalChange((change) => {
+            project.files.toRemote.applyNotification(toFileSystemNotification(change));
+        });
+        this._projectUnsubs = [
+            project.session.addEventListener("status", (status) => {
+                this.setStatus(status);
+            }),
+            project.session.on("session:welcome", (msg) => {
+                const token = msg.payload?.bindingToken;
+                if (token) {
+                    this._options.bindingToken = token;
+                    this._options.onBindingTokenChange?.(token);
+                }
+            }),
+            project.onJoinCodeChange((joinCode) => {
+                this.setJoinCode(joinCode);
+            }),
+            project.onRemoteFileChange((notification) => {
+                const change = toProjectFileChange(notification);
+                this._options.filesystem.applyRemoteChange(change);
+                this.emitRemoteChange(change);
+            }),
+            project.onDidSync(() => {
+                this.emitDidSync();
+            }),
+        ];
+        project.session.start();
+    }
+    stop() {
+        const project = this._project;
+        if (!project) {
+            this.setJoinCode(undefined);
+            this.setStatus("disconnected");
+            return;
+        }
+        project.session.stop();
+        this.disposeProjectBindings();
+        this._project = undefined;
+        this.setJoinCode(undefined);
+        this.disposeFeatures();
+    }
+    async requestSync() {
+        const project = this.requireProject();
+        await project.requestSync();
+    }
+    snapshot() {
+        return {
+            status: this._status,
+            joinCode: this._joinCode,
+        };
+    }
+    onStateChange(listener) {
+        this._stateListeners.add(listener);
+        return () => {
+            this._stateListeners.delete(listener);
+        };
+    }
+    onRemoteChange(listener) {
+        this._remoteChangeListeners.add(listener);
+        return () => {
+            this._remoteChangeListeners.delete(listener);
+        };
+    }
+    attachFeatures() {
+        if (this._featureDisposers.length > 0) {
+            return;
+        }
+        const features = this._options.features ?? [];
+        const context = {
+            snapshot: () => this.snapshot(),
+            projectFileSnapshot: () => this._options.filesystem.exportSnapshot(),
+            onStateChange: (listener) => this.onStateChange(listener),
+            onRemoteChange: (listener) => this.onRemoteChange(listener),
+            onDidSync: (listener) => this.onDidSync(listener),
+            publishDiagnostics: (file, diagnostics) => {
+                this.publishDiagnostics(file, diagnostics);
+            },
+            publishStatus: (update) => {
+                this.publishStatus(update);
+            },
+        };
+        for (const feature of features) {
+            this._featureDisposers.push(feature.attach(context));
+        }
+    }
+    disposeFeatures() {
+        for (const dispose of this._featureDisposers.splice(0)) {
+            dispose();
+        }
+    }
+    onDidSync(listener) {
+        this._syncListeners.add(listener);
+        return () => {
+            this._syncListeners.delete(listener);
+        };
+    }
+    emitDidSync() {
+        for (const listener of this._syncListeners) {
+            listener();
+        }
+    }
+    emitRemoteChange(change) {
+        for (const listener of this._remoteChangeListeners) {
+            listener(change);
+        }
+    }
+    publishDiagnostics(file, diagnostics) {
+        const project = this._project;
+        if (!project || this._status !== "connected") {
+            return;
+        }
+        const version = (this._diagnosticVersions.get(file) ?? 0) + 1;
+        this._diagnosticVersions.set(file, version);
+        const message = {
+            type: "compile:diagnostics",
+            payload: {
+                file,
+                version,
+                diagnostics: [...diagnostics],
+            },
+        };
+        project.session.send(message);
+    }
+    publishStatus(update) {
+        const project = this._project;
+        if (!project || this._status !== "connected") {
+            return;
+        }
+        const message = {
+            type: "compile:status",
+            payload: {
+                file: update.file,
+                success: update.success,
+                diagnosticCount: {
+                    error: update.diagnosticCount.error,
+                    warning: update.diagnosticCount.warning,
+                },
+            },
+        };
+        project.session.send(message);
+    }
+    setStatus(status) {
+        if (this._status === status) {
+            return;
+        }
+        this._status = status;
+        for (const listener of this._stateListeners) {
+            listener(status);
+        }
+    }
+    setJoinCode(joinCode) {
+        if (this._joinCode === joinCode) {
+            return;
+        }
+        this._joinCode = joinCode;
+        for (const listener of this._stateListeners) {
+            listener(this._status);
+        }
+    }
+    disposeProjectBindings() {
+        this._filesystemUnsub?.();
+        this._filesystemUnsub = undefined;
+        for (const unsub of this._projectUnsubs.splice(0)) {
+            unsub();
+        }
+    }
+    requireProject() {
+        if (!this._project) {
+            throw new Error("Bridge not started");
+        }
+        return this._project;
+    }
+}