@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/process/studio-process-manager.ts

@@ -1,17 +1,15 @@
 /**
  * Locates a Roblox Studio installation and manages the Studio process
- * lifecycle. Supports Windows and macOS.
+ * lifecycle. Supports Windows, macOS, and Linux (via Wine).
  */
 
 import * as fs from 'fs/promises';
+import * as os from 'os';
 import * as path from 'path';
-import { execa, type ResultPromise } from 'execa';
+import { spawn, type ChildProcess } from 'child_process';
+import { execa } from 'execa';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 
-// ---------------------------------------------------------------------------
-// Path resolution
-// ---------------------------------------------------------------------------
-
 /**
  * Find the path to the RobloxStudioBeta executable.
  * Throws if Studio cannot be located.
@@ -21,6 +19,8 @@ export async function findStudioPathAsync(): Promise<string> {
     return findStudioPathWindowsAsync();
   } else if (process.platform === 'darwin') {
     return findStudioPathMacAsync();
+  } else if (process.platform === 'linux') {
+    return findStudioPathLinuxAsync();
   }
   throw new Error(`Unsupported platform: ${process.platform}`);
 }
@@ -67,6 +67,20 @@ async function findStudioPathMacAsync(): Promise<string> {
   }
 }
 
+async function findStudioPathLinuxAsync(): Promise<string> {
+  const { resolveLinuxConfig } = await import('../linux/linux-config.js');
+  const config = resolveLinuxConfig();
+
+  try {
+    await fs.access(config.studioExe);
+    return config.studioExe;
+  } catch {
+    throw new Error(
+      `Could not find Roblox Studio at ${config.studioExe}. Run "studio-bridge linux setup" first.`
+    );
+  }
+}
+
 /**
  * Resolve the Studio plugins folder for the current platform.
  */
@@ -83,41 +97,58 @@ export function findPluginsFolder(): string {
       throw new Error('HOME environment variable is not set');
     }
     return path.join(home, 'Documents', 'Roblox', 'Plugins');
+  } else if (process.platform === 'linux') {
+    // Studio runs under Wine and resolves plugins via %LOCALAPPDATA%.
+    // Use path.posix so the produced path is a real Linux/Wine path even
+    // when this function is exercised on a Windows host (tests).
+    const winePrefix =
+      process.env.WINEPREFIX || path.posix.join(os.homedir(), '.wine');
+    const wineUser = process.env.USER || os.userInfo().username;
+    return path.posix.join(
+      winePrefix,
+      'drive_c',
+      'users',
+      wineUser,
+      'AppData',
+      'Local',
+      'Roblox',
+      'Plugins'
+    );
   }
   throw new Error(`Unsupported platform: ${process.platform}`);
 }
 
-// ---------------------------------------------------------------------------
-// Process management
-// ---------------------------------------------------------------------------
-
 export interface StudioProcess {
   /** The underlying child process handle */
-  process: ResultPromise;
+  process: ChildProcess;
   /** Kill the Studio process (idempotent, best-effort) */
   killAsync: () => Promise<void>;
 }
 
 /**
  * Launch Roblox Studio with the given place file.
+ *
+ * Uses Node's built-in `spawn` with `detached: true` + `unref()` so that
+ * Studio survives after the CLI process exits. execa's internal Job Object
+ * on Windows kills children on parent exit, so we avoid it here.
  */
 export async function launchStudioAsync(
   placePath: string
 ): Promise<StudioProcess> {
+  if (process.platform === 'linux') {
+    return launchStudioLinuxAsync(placePath);
+  }
+
   const studioExe = await findStudioPathAsync();
   OutputHelper.verbose(`[StudioBridge] ${studioExe} "${placePath}"`);
 
-  const proc = execa(studioExe, [placePath], {
-    // Don't tie Studio's lifetime to our process
+  const proc = spawn(studioExe, placePath ? [placePath] : [], {
     detached: true,
-    // Don't wait for stdio
     stdio: 'ignore',
-    // Don't reject on non-zero exit
-    reject: false,
   });
 
-  // Allow our Node process to exit even if Studio is still running
-  proc.unref?.();
+  // Allow our Node process to exit without waiting for Studio
+  proc.unref();
 
   let killed = false;
   const killAsync = async () => {
@@ -141,3 +172,13 @@ export async function launchStudioAsync(
 
   return { process: proc, killAsync };
 }
+
+async function launchStudioLinuxAsync(
+  placePath: string
+): Promise<StudioProcess> {
+  const { launchStudioLinuxAsync: launch } = await import(
+    '../linux/linux-studio-launcher.js'
+  );
+  const studioExe = await findStudioPathAsync();
+  return launch(studioExe, placePath);
+}

package/src/server/action-dispatcher.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Unit tests for ActionDispatcher -- validates request creation, response
+ * handling, timeout behavior, error handling, and cancel-all functionality.
+ */
+
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { ActionDispatcher, ACTION_TIMEOUTS } from './action-dispatcher.js';
+import type { PluginMessage } from './web-socket-protocol.js';
+
+describe('ActionDispatcher', () => {
+  let dispatcher: ActionDispatcher;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    dispatcher = new ActionDispatcher();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('createRequestAsync', () => {
+    it('generates a unique requestId', () => {
+      const req1 = dispatcher.createRequestAsync('queryState');
+      const req2 = dispatcher.createRequestAsync('queryState');
+
+      expect(req1.requestId).not.toBe(req2.requestId);
+      expect(typeof req1.requestId).toBe('string');
+      expect(req1.requestId.length).toBeGreaterThan(0);
+    });
+
+    it('returns a promise that can be resolved', async () => {
+      const { requestId, responsePromise } =
+        dispatcher.createRequestAsync('queryState');
+
+      const response: PluginMessage = {
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId,
+        payload: { state: 'Edit', placeId: 0, placeName: 'Test', gameId: 0 },
+      };
+
+      // Resolve via handleResponse
+      const consumed = dispatcher.handleResponse(response);
+      expect(consumed).toBe(true);
+
+      const result = await responsePromise;
+      expect(result.type).toBe('stateResult');
+    });
+
+    it('increments pendingCount', () => {
+      expect(dispatcher.pendingCount).toBe(0);
+
+      dispatcher.createRequestAsync('queryState');
+      expect(dispatcher.pendingCount).toBe(1);
+
+      dispatcher.createRequestAsync('captureScreenshot');
+      expect(dispatcher.pendingCount).toBe(2);
+    });
+  });
+
+  describe('timeout', () => {
+    it('uses default timeout for known action type', async () => {
+      const { responsePromise } = dispatcher.createRequestAsync('queryState');
+
+      // Advance time just past the queryState timeout
+      vi.advanceTimersByTime(ACTION_TIMEOUTS.queryState + 100);
+
+      await expect(responsePromise).rejects.toThrow('timed out');
+    });
+
+    it('uses custom timeout when provided', async () => {
+      const { responsePromise } = dispatcher.createRequestAsync(
+        'queryState',
+        500
+      );
+
+      vi.advanceTimersByTime(600);
+
+      await expect(responsePromise).rejects.toThrow('timed out');
+    });
+
+    it('does not reject before timeout', async () => {
+      const { requestId, responsePromise } =
+        dispatcher.createRequestAsync('queryState');
+
+      // Advance time to just before the timeout
+      vi.advanceTimersByTime(ACTION_TIMEOUTS.queryState - 100);
+
+      // Should still be pending
+      expect(dispatcher.pendingCount).toBe(1);
+
+      // Now resolve it
+      dispatcher.handleResponse({
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId,
+        payload: { state: 'Edit', placeId: 0, placeName: 'Test', gameId: 0 },
+      });
+
+      const result = await responsePromise;
+      expect(result.type).toBe('stateResult');
+    });
+
+    it('uses 30s fallback for unknown action type', async () => {
+      const { responsePromise } =
+        dispatcher.createRequestAsync('unknownAction');
+
+      vi.advanceTimersByTime(31_000);
+
+      await expect(responsePromise).rejects.toThrow('timed out');
+    });
+  });
+
+  describe('handleResponse', () => {
+    it('resolves the matching pending request', async () => {
+      const { requestId, responsePromise } =
+        dispatcher.createRequestAsync('captureScreenshot');
+
+      const response: PluginMessage = {
+        type: 'screenshotResult',
+        sessionId: 'session-1',
+        requestId,
+        payload: { data: 'base64', format: 'png', width: 800, height: 600 },
+      };
+
+      const consumed = dispatcher.handleResponse(response);
+      expect(consumed).toBe(true);
+      expect(dispatcher.pendingCount).toBe(0);
+
+      const result = await responsePromise;
+      expect(result.type).toBe('screenshotResult');
+    });
+
+    it('returns false for messages without requestId', () => {
+      const consumed = dispatcher.handleResponse({
+        type: 'heartbeat',
+        sessionId: 'session-1',
+        payload: { uptimeMs: 1000, state: 'Edit', pendingRequests: 0 },
+      });
+
+      expect(consumed).toBe(false);
+    });
+
+    it('returns false for messages with unknown requestId', () => {
+      const consumed = dispatcher.handleResponse({
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId: 'nonexistent-request',
+        payload: { state: 'Edit', placeId: 0, placeName: 'Test', gameId: 0 },
+      });
+
+      expect(consumed).toBe(false);
+    });
+
+    it('rejects pending request when plugin sends error response', async () => {
+      const { requestId, responsePromise } =
+        dispatcher.createRequestAsync('queryDataModel');
+
+      const errorResponse: PluginMessage = {
+        type: 'error',
+        sessionId: 'session-1',
+        requestId,
+        payload: {
+          code: 'INSTANCE_NOT_FOUND',
+          message: 'Instance not found at path game.NonExistent',
+        },
+      };
+
+      const consumed = dispatcher.handleResponse(errorResponse);
+      expect(consumed).toBe(true);
+
+      await expect(responsePromise).rejects.toThrow('INSTANCE_NOT_FOUND');
+      await expect(responsePromise).rejects.toThrow('Instance not found');
+    });
+
+    it('handles multiple concurrent requests independently', async () => {
+      const req1 = dispatcher.createRequestAsync('queryState');
+      const req2 = dispatcher.createRequestAsync('captureScreenshot');
+
+      expect(dispatcher.pendingCount).toBe(2);
+
+      // Resolve req2 first
+      dispatcher.handleResponse({
+        type: 'screenshotResult',
+        sessionId: 'session-1',
+        requestId: req2.requestId,
+        payload: { data: 'img', format: 'png', width: 100, height: 100 },
+      });
+
+      expect(dispatcher.pendingCount).toBe(1);
+
+      // Resolve req1
+      dispatcher.handleResponse({
+        type: 'stateResult',
+        sessionId: 'session-1',
+        requestId: req1.requestId,
+        payload: { state: 'Play', placeId: 1, placeName: 'Place', gameId: 2 },
+      });
+
+      expect(dispatcher.pendingCount).toBe(0);
+
+      const result1 = await req1.responsePromise;
+      const result2 = await req2.responsePromise;
+
+      expect(result1.type).toBe('stateResult');
+      expect(result2.type).toBe('screenshotResult');
+    });
+  });
+
+  describe('cancelAll', () => {
+    it('rejects all pending requests', async () => {
+      const req1 = dispatcher.createRequestAsync('queryState');
+      const req2 = dispatcher.createRequestAsync('captureScreenshot');
+
+      dispatcher.cancelAll('Server shutting down');
+
+      expect(dispatcher.pendingCount).toBe(0);
+
+      await expect(req1.responsePromise).rejects.toThrow(
+        'Server shutting down'
+      );
+      await expect(req2.responsePromise).rejects.toThrow(
+        'Server shutting down'
+      );
+    });
+
+    it('uses default message when no reason provided', async () => {
+      const { responsePromise } = dispatcher.createRequestAsync('queryState');
+
+      dispatcher.cancelAll();
+
+      await expect(responsePromise).rejects.toThrow('cancelled');
+    });
+
+    it('is safe to call when no requests pending', () => {
+      expect(() => dispatcher.cancelAll()).not.toThrow();
+    });
+  });
+});

package/src/server/action-dispatcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Action dispatcher for v2 protocol actions. Generates request IDs,
+ * tracks pending requests, applies per-action-type timeouts, and
+ * correlates incoming plugin responses to outgoing requests.
+ *
+ * Used by StudioBridgeServer for the v2 `performActionAsync` path.
+ * The v1 `executeAsync` path bypasses this entirely.
+ */
+
+import { randomUUID } from 'crypto';
+import { PendingRequestMap } from './pending-request-map.js';
+import type { PluginMessage } from './web-socket-protocol.js';
+
+export const ACTION_TIMEOUTS: Record<string, number> = {
+  queryState: 5_000,
+  captureScreenshot: 15_000,
+  queryDataModel: 10_000,
+  queryLogs: 10_000,
+  execute: 120_000,
+  subscribe: 5_000,
+  unsubscribe: 5_000,
+};
+
+export class ActionDispatcher {
+  private _pendingRequests = new PendingRequestMap<PluginMessage>();
+
+  /**
+   * Create a new pending request for the given action type.
+   * Returns the generated requestId and a promise that resolves when
+   * the plugin responds (or rejects on timeout).
+   */
+  createRequestAsync(
+    actionType: string,
+    timeoutMs?: number
+  ): { requestId: string; responsePromise: Promise<PluginMessage> } {
+    const requestId = randomUUID();
+    const timeout = timeoutMs ?? ACTION_TIMEOUTS[actionType] ?? 30_000;
+    const responsePromise = this._pendingRequests.addRequestAsync(
+      requestId,
+      timeout
+    );
+
+    return { requestId, responsePromise };
+  }
+
+  /**
+   * Handle an incoming plugin message. If it has a requestId and matches
+   * a pending request, resolves (or rejects for error type) the request.
+   * Returns true if the message was consumed by the dispatcher.
+   */
+  handleResponse(message: PluginMessage): boolean {
+    // Extract requestId from the message -- it may or may not exist
+    const requestId =
+      'requestId' in message ? (message as any).requestId : undefined;
+
+    if (typeof requestId !== 'string') {
+      return false;
+    }
+
+    if (!this._pendingRequests.hasPendingRequest(requestId)) {
+      return false;
+    }
+
+    if (message.type === 'error') {
+      const errorMsg = message.payload.message ?? 'Unknown plugin error';
+      const code = message.payload.code ?? 'INTERNAL_ERROR';
+      this._pendingRequests.rejectRequest(
+        requestId,
+        new Error(`Plugin error [${code}]: ${errorMsg}`)
+      );
+      return true;
+    }
+
+    this._pendingRequests.resolveRequest(requestId, message);
+    return true;
+  }
+
+  /**
+   * Cancel all pending requests, rejecting each with the given reason.
+   */
+  cancelAll(reason?: string): void {
+    this._pendingRequests.cancelAll(reason);
+  }
+
+  /** Number of currently pending requests. */
+  get pendingCount(): number {
+    return this._pendingRequests.pendingCount;
+  }
+}

package/src/server/index.ts

@@ -11,10 +11,7 @@ export type {
   OutputLevel,
   PluginMessage,
   ServerMessage,
-  HelloMessage,
-  OutputMessage,
   ScriptCompleteMessage,
-  WelcomeMessage,
   ExecuteMessage,
   ShutdownMessage,
 } from './web-socket-protocol.js';