@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/bridge/bridge-session.test.ts

@@ -0,0 +1,336 @@
+/**
+ * Unit tests for BridgeSession -- validates action delegation to
+ * TransportHandle, disconnect error handling, and event forwarding.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { EventEmitter } from 'events';
+import { BridgeSession } from './bridge-session.js';
+import type { SessionInfo } from './types.js';
+import { SessionDisconnectedError } from './types.js';
+import type {
+  PluginMessage,
+  ServerMessage,
+} from '../server/web-socket-protocol.js';
+
+// Mock loadActionSourcesAsync to return empty array so _ensureActionsAsync
+// is a no-op in unit tests (no syncActions round-trip needed).
+vi.mock('../commands/framework/action-loader.js', () => ({
+  loadActionSourcesAsync: vi.fn(async () => []),
+}));
+
+class MockTransportHandle extends EventEmitter {
+  private _isConnected: boolean;
+
+  sendActionAsync = vi.fn(async () => ({})) as any;
+  sendMessage = vi.fn();
+
+  constructor(connected = true) {
+    super();
+    this._isConnected = connected;
+  }
+
+  get isConnected(): boolean {
+    return this._isConnected;
+  }
+
+  simulateDisconnect(): void {
+    this._isConnected = false;
+    this.emit('disconnected');
+  }
+
+  simulateMessage(msg: PluginMessage): void {
+    this.emit('message', msg);
+  }
+}
+
+function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: 'session-1',
+    placeName: 'TestPlace',
+    state: 'Edit',
+    pluginVersion: '1.0.0',
+    capabilities: ['execute', 'queryState'],
+    connectedAt: new Date(),
+    origin: 'user',
+    context: 'edit',
+    instanceId: 'inst-1',
+    placeId: 123,
+    gameId: 456,
+    ...overrides,
+  };
+}
+
+describe('BridgeSession', () => {
+  describe('properties', () => {
+    it('exposes session info', () => {
+      const info = createSessionInfo({
+        sessionId: 'my-session',
+        context: 'server',
+      });
+      const handle = new MockTransportHandle();
+      const session = new BridgeSession(info, handle);
+
+      expect(session.info.sessionId).toBe('my-session');
+      expect(session.context).toBe('server');
+    });
+
+    it('reflects connection state from handle', () => {
+      const handle = new MockTransportHandle(true);
+      const session = new BridgeSession(createSessionInfo(), handle);
+
+      expect(session.isConnected).toBe(true);
+
+      handle.simulateDisconnect();
+
+      expect(session.isConnected).toBe(false);
+    });
+  });
+
+  describe('disconnect handling', () => {
+    it('emits disconnected event when handle disconnects', () => {
+      const handle = new MockTransportHandle();
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const listener = vi.fn();
+
+      session.on('disconnected', listener);
+      handle.simulateDisconnect();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws SessionDisconnectedError when action called after disconnect', async () => {
+      const handle = new MockTransportHandle(false);
+      const session = new BridgeSession(
+        createSessionInfo({ sessionId: 'disc-session' }),
+        handle
+      );
+
+      await expect(session.execAsync('print("hi")')).rejects.toThrow(
+        SessionDisconnectedError
+      );
+      await expect(session.queryStateAsync()).rejects.toThrow(
+        SessionDisconnectedError
+      );
+      await expect(session.captureScreenshotAsync()).rejects.toThrow(
+        SessionDisconnectedError
+      );
+      await expect(session.queryLogsAsync()).rejects.toThrow(
+        SessionDisconnectedError
+      );
+      await expect(
+        session.queryDataModelAsync({ path: 'game' })
+      ).rejects.toThrow(SessionDisconnectedError);
+    });
+  });
+
+  describe('execAsync', () => {
+    it('delegates to handle.sendActionAsync with execute message', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'scriptComplete',
+        sessionId: 'session-1',
+        payload: { success: true },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.execAsync('print("hello")');
+
+      expect(handle.sendActionAsync).toHaveBeenCalledTimes(1);
+      const [msg, timeout] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as ServerMessage).type).toBe('execute');
+      expect((msg as any).payload.script).toBe('print("hello")');
+      expect(timeout).toBe(120_000);
+
+      expect(result.success).toBe(true);
+    });
+
+    it('uses custom timeout when provided', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'scriptComplete',
+        sessionId: 'session-1',
+        payload: { success: true },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      await session.execAsync('print("hello")', 5_000);
+
+      const [, timeout] = handle.sendActionAsync.mock.calls[0];
+      expect(timeout).toBe(5_000);
+    });
+
+    it('returns error info from error response', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'error',
+        sessionId: 'session-1',
+        payload: { code: 'SCRIPT_RUNTIME_ERROR', message: 'boom' },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.execAsync('error("boom")');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('boom');
+    });
+  });
+
+  describe('queryStateAsync', () => {
+    it('returns state result from handle response', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: {
+          state: 'Play',
+          placeId: 100,
+          placeName: 'Test',
+          gameId: 200,
+        },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.queryStateAsync();
+
+      expect(result.state).toBe('Play');
+      expect(result.placeId).toBe(100);
+      expect(result.placeName).toBe('Test');
+      expect(result.gameId).toBe(200);
+    });
+
+    it('sends queryState message type', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: { state: 'Edit', placeId: 0, placeName: 'Test', gameId: 0 },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      await session.queryStateAsync();
+
+      const [msg] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as ServerMessage).type).toBe('queryState');
+    });
+  });
+
+  describe('captureScreenshotAsync', () => {
+    it('returns screenshot result', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'screenshotResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: { data: 'base64data', format: 'png', width: 800, height: 600 },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.captureScreenshotAsync();
+
+      expect(result.data).toBe('base64data');
+      expect(result.format).toBe('png');
+      expect(result.width).toBe(800);
+      expect(result.height).toBe(600);
+    });
+  });
+
+  describe('queryLogsAsync', () => {
+    it('returns logs result', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'logsResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: {
+          entries: [{ level: 'Print', body: 'hello', timestamp: 12345 }],
+          total: 1,
+          bufferCapacity: 1000,
+        },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.queryLogsAsync({
+        count: 10,
+        direction: 'tail',
+      });
+
+      expect(result.entries).toHaveLength(1);
+      expect(result.total).toBe(1);
+    });
+
+    it('passes options to payload', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'logsResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: { entries: [], total: 0, bufferCapacity: 1000 },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      await session.queryLogsAsync({ count: 5, levels: ['Error', 'Warning'] });
+
+      const [msg] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as any).payload.count).toBe(5);
+      expect((msg as any).payload.levels).toEqual(['Error', 'Warning']);
+    });
+  });
+
+  describe('queryDataModelAsync', () => {
+    it('returns data model result', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'dataModelResult',
+        sessionId: 'session-1',
+        requestId: 'r-1',
+        payload: {
+          instance: {
+            name: 'Workspace',
+            className: 'Workspace',
+            path: 'game.Workspace',
+            properties: {},
+            attributes: {},
+            childCount: 5,
+          },
+        },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.queryDataModelAsync({
+        path: 'game.Workspace',
+      });
+
+      expect(result.instance.name).toBe('Workspace');
+      expect(result.instance.className).toBe('Workspace');
+    });
+  });
+
+  describe('state change events', () => {
+    it('emits state-changed and updates info on stateChange message', () => {
+      const handle = new MockTransportHandle();
+      const session = new BridgeSession(
+        createSessionInfo({ state: 'Edit' }),
+        handle
+      );
+      const listener = vi.fn();
+
+      session.on('state-changed', listener);
+
+      handle.simulateMessage({
+        type: 'stateChange',
+        sessionId: 'session-1',
+        payload: {
+          previousState: 'Edit',
+          newState: 'Play',
+          timestamp: Date.now(),
+        },
+      });
+
+      expect(listener).toHaveBeenCalledWith('Play');
+      expect(session.info.state).toBe('Play');
+    });
+  });
+});

package/src/bridge/bridge-session.ts

@@ -0,0 +1,365 @@
+/**
+ * Public session handle that delegates to a TransportHandle. Provides
+ * typed action methods for interacting with a connected Studio plugin.
+ * Works identically whether backed by a direct WebSocket connection
+ * (host) or a relayed connection through the host (client).
+ *
+ * Consumers get BridgeSession instances from BridgeConnection -- they
+ * never construct them directly.
+ */
+
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+import type { TransportHandle } from './internal/session-tracker.js';
+import type {
+  SessionInfo,
+  SessionContext,
+  ExecResult,
+  StateResult,
+  ScreenshotResult,
+  LogsResult,
+  DataModelResult,
+  LogOptions,
+  QueryDataModelOptions,
+} from './types.js';
+import { SessionDisconnectedError } from './types.js';
+import type {
+  PluginMessage,
+  OutputLevel,
+} from '../server/web-socket-protocol.js';
+import {
+  loadActionSourcesAsync,
+  type ActionSource,
+} from '../commands/framework/action-loader.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+
+const DEFAULT_TIMEOUTS: Record<string, number> = {
+  execute: 120_000,
+  queryState: 5_000,
+  captureScreenshot: 30_000,
+  queryDataModel: 10_000,
+  queryLogs: 10_000,
+};
+
+/**
+ * Build a descriptive error from a plugin response that didn't match the
+ * expected type. Extracts error details from error-typed responses.
+ */
+function pluginError(expectedType: string, result: PluginMessage): Error {
+  if (result.type === 'error') {
+    const code = result.payload?.code ?? 'UNKNOWN';
+    const message = result.payload?.message ?? 'Unknown plugin error';
+    return new Error(`Plugin error (${code}): ${message}`);
+  }
+  return new Error(
+    `Expected '${expectedType}' response from plugin, got '${result.type}'`
+  );
+}
+
+export class BridgeSession extends EventEmitter {
+  private _info: SessionInfo;
+  private _handle: TransportHandle;
+  private _actionsReady = false;
+  private _actionSources: ActionSource[] | undefined;
+
+  constructor(info: SessionInfo, handle: TransportHandle) {
+    super();
+    this._info = info;
+    this._handle = handle;
+
+    this._handle.on('disconnected', () => {
+      this.emit('disconnected');
+    });
+
+    this._handle.on('message', (msg: PluginMessage) => {
+      if (msg.type === 'stateChange') {
+        this._info = { ...this._info, state: msg.payload.newState };
+        this.emit('state-changed', msg.payload.newState);
+      }
+    });
+  }
+
+  /** Read-only metadata about this session. */
+  get info(): SessionInfo {
+    return this._info;
+  }
+
+  /** Which Studio VM this session represents (edit, client, or server). */
+  get context(): SessionContext {
+    return this._info.context;
+  }
+
+  /** Whether the session's plugin is still connected. */
+  get isConnected(): boolean {
+    return this._handle.isConnected;
+  }
+
+  async execAsync(code: string, timeout?: number): Promise<ExecResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const timeoutMs = timeout ?? DEFAULT_TIMEOUTS.execute;
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'execute',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: { script: code },
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'scriptComplete') {
+      const output = (result.payload.output ?? []).map((entry) => ({
+        level: entry.level as OutputLevel,
+        body: entry.body,
+      }));
+      return {
+        success: result.payload.success,
+        output,
+        error: result.payload.error,
+      };
+    }
+
+    if (result.type === 'error') {
+      return {
+        success: false,
+        output: [],
+        error: result.payload?.message ?? 'Unknown plugin error',
+      };
+    }
+
+    return {
+      success: false,
+      output: [],
+      error: pluginError('scriptComplete', result).message,
+    };
+  }
+
+  async queryStateAsync(): Promise<StateResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const timeoutMs = DEFAULT_TIMEOUTS.queryState;
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'queryState',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: {} as Record<string, never>,
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'stateResult') {
+      return {
+        state: result.payload.state,
+        placeId: result.payload.placeId,
+        placeName: result.payload.placeName,
+        gameId: result.payload.gameId,
+      };
+    }
+
+    throw pluginError('stateResult', result);
+  }
+
+  async captureScreenshotAsync(): Promise<ScreenshotResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const timeoutMs = DEFAULT_TIMEOUTS.captureScreenshot;
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'captureScreenshot',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: { format: 'png' },
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'screenshotResult') {
+      return {
+        data: result.payload.data,
+        format: result.payload.format,
+        width: result.payload.width,
+        height: result.payload.height,
+      };
+    }
+
+    throw pluginError('screenshotResult', result);
+  }
+
+  async queryLogsAsync(options?: LogOptions): Promise<LogsResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const timeoutMs = DEFAULT_TIMEOUTS.queryLogs;
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'queryLogs',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: {
+          count: options?.count,
+          direction: options?.direction,
+          levels: options?.levels,
+          includeInternal: options?.includeInternal,
+        },
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'logsResult') {
+      return {
+        entries: result.payload.entries,
+        total: result.payload.total,
+        bufferCapacity: result.payload.bufferCapacity,
+      };
+    }
+
+    throw pluginError('logsResult', result);
+  }
+
+  async queryDataModelAsync(
+    options: QueryDataModelOptions
+  ): Promise<DataModelResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const timeoutMs = DEFAULT_TIMEOUTS.queryDataModel;
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'queryDataModel',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: {
+          path: options.path,
+          depth: options.depth,
+          properties: options.properties,
+          includeAttributes: options.includeAttributes,
+          find: options.find,
+          listServices: options.listServices,
+        },
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'dataModelResult') {
+      return {
+        instance: result.payload.instance,
+      };
+    }
+
+    throw pluginError('dataModelResult', result);
+  }
+
+  private _assertConnected(): void {
+    if (!this._handle.isConnected) {
+      throw new SessionDisconnectedError(this._info.sessionId);
+    }
+  }
+
+  /**
+   * Ensure action modules are synced to the plugin before first use.
+   * Uses syncActions to determine which actions need updating, then
+   * registers only those that are missing or have changed hashes.
+   */
+  private async _ensureActionsAsync(): Promise<void> {
+    if (this._actionsReady) return;
+
+    // Lazy-load action sources from this process's disk
+    if (!this._actionSources) {
+      this._actionSources = await loadActionSourcesAsync();
+      OutputHelper.verbose(
+        `[actions] Loaded ${this._actionSources.length} action source(s): ${
+          this._actionSources.map((a) => a.name).join(', ') || '(none)'
+        }`
+      );
+    }
+
+    if (this._actionSources.length === 0) {
+      OutputHelper.verbose('[actions] No action sources found — skipping sync');
+      this._actionsReady = true;
+      return;
+    }
+
+    const actions: Record<string, string> = {};
+    for (const action of this._actionSources) {
+      actions[action.name] = action.hash;
+    }
+
+    OutputHelper.verbose(
+      `[actions] Sending syncActions (${
+        Object.keys(actions).length
+      } hashes) to session ${this._info.sessionId}`
+    );
+    const syncResult = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'syncActions',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: { actions },
+      },
+      10_000
+    );
+
+    if (syncResult.type === 'syncActionsResult') {
+      const needed = syncResult.payload.needed as string[];
+      OutputHelper.verbose(
+        `[actions] syncActions response: ${
+          needed.length
+        } action(s) need updating${
+          needed.length > 0 ? ': ' + needed.join(', ') : ''
+        }`
+      );
+
+      for (const actionName of needed) {
+        const action = this._actionSources.find((a) => a.name === actionName);
+        if (!action) continue;
+
+        OutputHelper.verbose(`[actions] Registering action: ${actionName}`);
+        const regResult = await this._handle.sendActionAsync<PluginMessage>(
+          {
+            type: 'registerAction',
+            sessionId: this._info.sessionId,
+            requestId: randomUUID(),
+            payload: {
+              name: action.name,
+              source: action.source,
+              hash: action.hash,
+            },
+          },
+          10_000
+        );
+        if (regResult.type === 'registerActionResult') {
+          const p = regResult.payload;
+          OutputHelper.verbose(
+            `[actions]   ${actionName}: ${
+              p.success
+                ? p.skipped
+                  ? 'skipped (same hash)'
+                  : 'registered'
+                : `FAILED: ${p.error}`
+            }`
+          );
+        } else if (regResult.type === 'error') {
+          OutputHelper.verbose(
+            `[actions]   ${actionName}: plugin error: ${
+              (regResult as any).payload?.message ?? regResult.type
+            }`
+          );
+        }
+      }
+    } else {
+      OutputHelper.verbose(
+        `[actions] syncActions returned unexpected type '${
+          syncResult.type
+        }': ${JSON.stringify((syncResult as any).payload ?? {}).slice(0, 200)}`
+      );
+    }
+
+    this._actionsReady = true;
+    OutputHelper.verbose('[actions] Action sync complete');
+  }
+}