@quenty/studio-bridge 0.21.0 → 0.22.0

package/docker/Dockerfile

@@ -62,6 +62,9 @@ RUN mkdir -p /home/studio/.aftman/bin \
 # --- Build studio-bridge from source (via named build context "workspace") ---
 COPY --from=workspace --chown=studio:studio package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json /home/studio/build/
 COPY --from=workspace --chown=studio:studio tools/ /home/studio/build/tools/
+# The Luau test runner studio-bridge's plugin specs depend on
+COPY --from=workspace --chown=studio:studio src/loader/ /home/studio/build/src/loader/
+COPY --from=workspace --chown=studio:studio src/nevermore-test-runner/ /home/studio/build/src/nevermore-test-runner/
 WORKDIR /home/studio/build
 RUN pnpm install --frozen-lockfile --filter "@quenty/studio-bridge..." \
     && pnpm -r --filter "@quenty/studio-bridge..." run build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/studio-bridge",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "WebSocket-based bridge for running Luau scripts in Roblox Studio",
   "type": "module",
   "main": "dist/src/index.js",
@@ -15,15 +15,18 @@
     "studio-bridge": "./dist/src/cli/cli.js"
   },
   "dependencies": {
-    "@quenty/cli-output-helpers": "1.18.0",
-    "@quenty/nevermore-cli-helpers": "1.19.0",
-    "@quenty/nevermore-template-helpers": "1.20.0",
+    "@quenty/cli-output-helpers": "1.19.0",
+    "@quenty/nevermore-cli-helpers": "1.20.0",
+    "@quenty/nevermore-deploy": "1.1.1",
+    "@quenty/nevermore-template-helpers": "1.21.0",
     "execa": "^9.6.1",
     "ws": "^8.18.0",
     "yargs": "^18.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@quenty/nevermore-test-runner": "1.6.3",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2",
     "@types/node": "^18.11.4",
     "@types/ws": "^8.5.13",
     "@types/yargs": "^17.0.13",
@@ -36,8 +39,7 @@
     "build:clean": "tsc --build --clean",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:plugin": "lune run templates/studio-bridge-plugin-test/test/test-runner",
     "test:integration": "node dist/test/integration/smoke-test.js"
   },
-  "gitHead": "6b26147a6b432f17270769342498b4f2f08f60b1"
+  "gitHead": "8ccad9d519f633a4af6659664374605cf2df7ecf"
 }

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

@@ -25,6 +25,7 @@ async function performRegisterHandshake(
     placeName?: string;
     state?: string;
     context?: string;
+    playerName?: string;
     capabilities?: string[];
   }
 ): Promise<{ ws: WebSocket }> {
@@ -39,6 +40,8 @@ async function performRegisterHandshake(
         instanceId: options?.instanceId ?? 'inst-1',
         placeName: options?.placeName ?? 'TestPlace',
         state: options?.state ?? 'Edit',
+        context: options?.context,
+        playerName: options?.playerName,
         capabilities: options?.capabilities ?? ['execute', 'queryState'],
       },
     })
@@ -656,6 +659,129 @@ describe('BridgeConnection', () => {
     });
   });
 
+  describe('target matching', () => {
+    async function connectPlaytestAsync(): Promise<BridgeConnection> {
+      const conn = await BridgeConnection.connectAsync({
+        port: 0,
+        keepAlive: true,
+      });
+      connections.push(conn);
+
+      const plugins: Array<[string, string, string, string]> = [
+        ['test-place-3f9a-edit', 'test-place-3f9a', 'edit', 'test-place.rbxl'],
+        ['test-place-3f9a-server', 'test-place-3f9a', 'server', 'Game'],
+        ['test-place-3f9a-client', 'test-place-3f9a', 'client', 'Game'],
+        ['other-map-77c1-edit', 'other-map-77c1', 'edit', 'Other Map'],
+      ];
+      for (const [sessionId, instanceId, context, placeName] of plugins) {
+        const { ws } = await performRegisterHandshake(conn.port, sessionId, {
+          instanceId,
+          context,
+          placeName,
+        });
+        openClients.push(ws);
+      }
+      await new Promise((r) => setTimeout(r, 50));
+      return conn;
+    }
+
+    it('resolves an instance id prefix to its edit session', async () => {
+      const conn = await connectPlaytestAsync();
+
+      const session = await conn.resolveSessionAsync('test-place');
+      expect(session.info.sessionId).toBe('test-place-3f9a-edit');
+    });
+
+    it('applies --context within the targeted instance', async () => {
+      const conn = await connectPlaytestAsync();
+
+      const session = await conn.resolveSessionAsync(
+        'test-place-3f9a-edit',
+        'server'
+      );
+      expect(session.info.sessionId).toBe('test-place-3f9a-server');
+    });
+
+    it('refuses a prefix that matches several instances', async () => {
+      const conn = await connectPlaytestAsync();
+      const { ws } = await performRegisterHandshake(
+        conn.port,
+        'test-place-b2c4-edit',
+        { instanceId: 'test-place-b2c4', context: 'edit' }
+      );
+      openClients.push(ws);
+      await new Promise((r) => setTimeout(r, 50));
+
+      await expect(conn.resolveSessionAsync('test-place')).rejects.toThrow(
+        /matches several Studio instances/
+      );
+      await expect(conn.resolveSessionAsync('missing')).rejects.toThrow(
+        SessionNotFoundError
+      );
+    });
+
+    it('resolves a prefix that matches one session to that session', async () => {
+      const conn = await connectPlaytestAsync();
+
+      const session = await conn.resolveSessionAsync('test-place-3f9a-ser');
+      expect(session.info.sessionId).toBe('test-place-3f9a-server');
+    });
+
+    it('refuses --context when a multiplayer test has several clients', async () => {
+      const conn = await connectPlaytestAsync();
+      const { ws } = await performRegisterHandshake(
+        conn.port,
+        'test-place-3f9a-client-player2',
+        {
+          instanceId: 'test-place-3f9a',
+          context: 'client',
+          playerName: 'Player2',
+        }
+      );
+      openClients.push(ws);
+      await new Promise((r) => setTimeout(r, 50));
+
+      await expect(
+        conn.resolveSessionAsync('test-place', 'client')
+      ).rejects.toThrow(/several client sessions/);
+      await expect(
+        conn.resolveSessionAsync('test-place-3f9a-cl')
+      ).rejects.toThrow(/'test-place-3f9a-cl' matches several sessions/);
+      const session = await conn.resolveSessionAsync(
+        'test-place-3f9a-client-player2',
+        'client'
+      );
+      expect(session.info.playerName).toBe('Player2');
+    });
+
+    it('filters listed sessions by target and context', async () => {
+      const conn = await connectPlaytestAsync();
+
+      expect(conn.findSessions('test-place').map((s) => s.sessionId)).toEqual([
+        'test-place-3f9a-edit',
+        'test-place-3f9a-server',
+        'test-place-3f9a-client',
+      ]);
+      expect(
+        conn.findSessions(undefined, 'edit').map((s) => s.sessionId)
+      ).toEqual(['test-place-3f9a-edit', 'other-map-77c1-edit']);
+      expect(
+        conn.findSessions('other-map-77c1-edit').map((s) => s.sessionId)
+      ).toEqual(['other-map-77c1-edit']);
+    });
+
+    it('reports a running playtest as the state of its instance', async () => {
+      const conn = await connectPlaytestAsync();
+
+      const byId = new Map(conn.listSessions().map((s) => [s.sessionId, s]));
+      expect(byId.get('test-place-3f9a-edit')?.state).toBe('Play');
+      expect(byId.get('test-place-3f9a-server')?.placeName).toBe(
+        'test-place.rbxl'
+      );
+      expect(byId.get('other-map-77c1-edit')?.state).toBe('Edit');
+    });
+  });
+
   describe('waitForSession', () => {
     it('resolves immediately when sessions already exist', async () => {
       const conn = await BridgeConnection.connectAsync({

package/src/bridge/bridge-connection.ts

@@ -18,19 +18,25 @@ import {
   getDefaultRemoteHost,
 } from './internal/environment-detection.js';
 import { BridgeSession } from './bridge-session.js';
-import type {
-  HostProtocolMessage,
-  ListSessionsRequest,
-  ListInstancesRequest,
+import {
+  HOST_PROTOCOL_VERSION,
+  type HostEnvelope,
+  type HostProtocolMessage,
+  type ListSessionsRequest,
+  type ListInstancesRequest,
 } from './internal/host-protocol.js';
 import type { SessionInfo, SessionContext, InstanceInfo } from './types.js';
 import { SessionNotFoundError, ContextNotFoundError } from './types.js';
-import type { ServerMessage } from '../server/web-socket-protocol.js';
+import { annotateInstanceState } from './internal/instance-state.js';
+import type {
+  PluginMessage,
+  ServerMessage,
+} from '../server/web-socket-protocol.js';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 export interface BridgeConnectionOptions {
   /** Port for the bridge host. Default: 38741. */
   port?: number;
-  /** Max time to wait for initial connection setup. Default: 30_000ms. */
+  /** Max time to wait for the first Studio session to connect. Default: 5_000ms. */
   timeoutMs?: number;
   /** Keep the host alive even when idle. Default: false. */
   keepAlive?: boolean;
@@ -49,6 +55,8 @@ export interface BridgeConnectionOptions {
 const DEFAULT_PORT = 38741;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const IDLE_EXIT_GRACE_MS = 5_000;
+/** How long shutdown waits on relayed actions; a started playtest's request lasts until it ends. */
+const RELAY_DRAIN_TIMEOUT_MS = 10_000;
 
 /**
  * Transport handle that relays messages to a plugin's WebSocket via BridgeHost.
@@ -93,9 +101,12 @@ class HostTransportHandle extends EventEmitter {
 
 export class BridgeConnection extends EventEmitter {
   private _role: 'host' | 'client';
+  private _isRemote = false;
   private _isConnected: boolean = false;
   private _keepAlive: boolean;
   private _hasSettled: boolean = false;
+  private _firstSessionTimeoutMs: number | undefined;
+  private _pendingRelays = new Set<Promise<void>>();
 
   // Host mode internals
   private _host: BridgeHost | undefined;
@@ -105,6 +116,7 @@ export class BridgeConnection extends EventEmitter {
 
   // Client mode internals
   private _client: BridgeClient | undefined;
+  private _clientPort = 0;
 
   // Idle exit
   private _idleTimer: ReturnType<typeof setTimeout> | undefined;
@@ -169,6 +181,7 @@ export class BridgeConnection extends EventEmitter {
             ),
           ]);
 
+          autoConn._isRemote = true;
           return autoConn;
         } catch {
           console.warn(
@@ -186,6 +199,8 @@ export class BridgeConnection extends EventEmitter {
     });
 
     const conn = new BridgeConnection(detection.role, keepAlive);
+    conn._isRemote = parsedRemoteHost !== undefined;
+    conn._firstSessionTimeoutMs = options?.timeoutMs;
     OutputHelper.verbose(
       `[bridge] Role: ${detection.role}, port: ${detection.port}`
     );
@@ -225,7 +240,9 @@ export class BridgeConnection extends EventEmitter {
     return conn;
   }
 
-  async disconnectAsync(): Promise<void> {
+  async disconnectAsync(
+    options: { relayDrainTimeoutMs?: number } = {}
+  ): Promise<void> {
     if (!this._isConnected) {
       return;
     }
@@ -244,6 +261,24 @@ export class BridgeConnection extends EventEmitter {
     this._isConnected = false;
 
     if (this._role === 'host' && this._host) {
+      // Shutting down drops the plugins, so let actions relayed for clients finish
+      if (this._pendingRelays.size > 0) {
+        OutputHelper.verbose(
+          `[bridge] Waiting for ${this._pendingRelays.size} relayed action(s) before shutting down`
+        );
+        let drainTimer: ReturnType<typeof setTimeout> | undefined;
+        await Promise.race([
+          Promise.allSettled([...this._pendingRelays]),
+          new Promise<void>((resolve) => {
+            drainTimer = setTimeout(
+              resolve,
+              options.relayDrainTimeoutMs ?? RELAY_DRAIN_TIMEOUT_MS
+            );
+          }),
+        ]);
+        clearTimeout(drainTimer);
+      }
+
       for (const handle of this._hostHandles.values()) {
         handle.markDisconnected();
       }
@@ -270,27 +305,64 @@ export class BridgeConnection extends EventEmitter {
     return this._isConnected;
   }
 
+  /**
+   * True when this is a client relaying through a host from an older
+   * studio-bridge, which may not pass on options or actions it predates.
+   */
+  get isHostOutdated(): boolean {
+    return (
+      this._role === 'client' &&
+      (this._client?.hostProtocolVersion ?? 1) < HOST_PROTOCOL_VERSION
+    );
+  }
+
   /** The actual port the bridge is bound to (host) or connected to (client). */
+  /** Whether the bridge host, and so Studio, runs on another machine. */
+  get isRemote(): boolean {
+    return this._isRemote;
+  }
+
   get port(): number {
-    if (this._role === 'host' && this._host) {
+    if (this._host) {
       return this._host.port;
     }
-    return 0;
+    return this._clientPort;
   }
 
   /** List all currently connected Studio sessions. */
   listSessions(): SessionInfo[] {
     if (this._role === 'host' && this._tracker) {
-      return this._tracker.listSessions();
+      return annotateInstanceState(this._tracker.listSessions());
     }
 
     if (this._role === 'client' && this._client) {
-      return this._client.listSessions();
+      return annotateInstanceState(this._client.listSessions());
     }
 
     return [];
   }
 
+  /**
+   * Sessions matching `--target` and `--context`. A target matches a
+   * session id or an instance id exactly, or else as a prefix.
+   */
+  findSessions(target?: string, context?: SessionContext): SessionInfo[] {
+    let sessions = this.listSessions();
+    if (target) {
+      const exact = sessions.find((s) => s.sessionId === target);
+      if (exact && !context) return [exact];
+
+      const instanceIds = exact
+        ? [exact.instanceId]
+        : this._matchInstanceIds(target);
+      sessions = sessions.filter((s) => instanceIds.includes(s.instanceId));
+    }
+    if (context) {
+      sessions = sessions.filter((s) => s.context === context);
+    }
+    return sessions;
+  }
+
   /**
    * List unique Studio instances. Each instance groups 1-3 context sessions
    * that share the same instanceId.
@@ -320,6 +392,31 @@ export class BridgeConnection extends EventEmitter {
     return undefined;
   }
 
+  /**
+   * Instances whose id, or one of whose session ids, is `target`. Falls
+   * back to ids that start with `target` when nothing matches exactly.
+   */
+  private _matchInstanceIds(target: string): string[] {
+    const sessions = this.listSessions();
+    const exact = new Set(
+      sessions
+        .filter((s) => s.instanceId === target || s.sessionId === target)
+        .map((s) => s.instanceId)
+    );
+    if (exact.size > 0) return [...exact];
+
+    return [
+      ...new Set(
+        sessions
+          .filter(
+            (s) =>
+              s.instanceId.startsWith(target) || s.sessionId.startsWith(target)
+          )
+          .map((s) => s.instanceId)
+      ),
+    ];
+  }
+
   /**
    * Resolve a session for command execution. Instance-aware: groups sessions
    * by instanceId and auto-selects context within an instance.
@@ -345,13 +442,50 @@ export class BridgeConnection extends EventEmitter {
 
     if (sessionId) {
       const session = this.getSession(sessionId);
-      if (session) {
+      if (session && (!context || session.info.context === context)) {
         return session;
       }
-      throw new SessionNotFoundError(
-        `Session '${sessionId}' not found`,
-        sessionId
+
+      const prefixed = this.listSessions().filter(
+        (s) =>
+          s.sessionId.startsWith(sessionId) &&
+          (!context || s.context === context)
+      );
+      const onlyPrefixed =
+        prefixed.length === 1 ? this.getSession(prefixed[0].sessionId) : null;
+      if (onlyPrefixed) {
+        return onlyPrefixed;
+      }
+      const namesInstance = prefixed.some((s) =>
+        s.instanceId.startsWith(sessionId)
       );
+      if (!session && prefixed.length > 1 && !namesInstance) {
+        throw new SessionNotFoundError(
+          `'${sessionId}' matches several sessions. Use a longer --target:\n${prefixed
+            .map((s) => `  - ${s.sessionId}`)
+            .join('\n')}`,
+          sessionId
+        );
+      }
+
+      const instanceIds = session
+        ? [session.info.instanceId]
+        : this._matchInstanceIds(sessionId);
+      if (instanceIds.length === 0) {
+        throw new SessionNotFoundError(
+          `Session '${sessionId}' not found`,
+          sessionId
+        );
+      }
+      if (instanceIds.length > 1) {
+        throw new SessionNotFoundError(
+          `'${sessionId}' matches several Studio instances: ${instanceIds.join(
+            ', '
+          )}. Use a longer --target.`,
+          sessionId
+        );
+      }
+      return this._resolveByInstance(instanceIds[0], context);
     }
 
     if (instanceId) {
@@ -368,13 +502,13 @@ export class BridgeConnection extends EventEmitter {
       return this._resolveByInstance(instances[0].instanceId, context);
     }
 
-    // Multiple instances: list session IDs so the user can copy one into --session
+    // Multiple instances: list session IDs so the user can copy one into --target
     const sessionList = this.listSessions()
       .map((s) => `  - ${s.sessionId}: ${s.placeName} (${s.context})`)
       .join('\n');
 
     throw new SessionNotFoundError(
-      `Multiple Studio instances connected. Use --session <id> to select one.\n${sessionList}`
+      `Multiple Studio instances connected. Use --target <id> to select one.\n${sessionList}`
     );
   }
 
@@ -429,7 +563,9 @@ export class BridgeConnection extends EventEmitter {
     OutputHelper.verbose(
       '[bridge] No sessions yet — waiting for plugins to discover us'
     );
-    await this.waitForSessionsToSettleAsync();
+    await this.waitForSessionsToSettleAsync({
+      firstSessionTimeout: this._firstSessionTimeoutMs,
+    });
     this._hasSettled = true;
     const settled = this.listSessions();
     OutputHelper.verbose(
@@ -461,7 +597,7 @@ export class BridgeConnection extends EventEmitter {
 
     const firstTimeout = options?.firstSessionTimeout ?? 5_000;
     const settleMs = options?.settleMs ?? 4_000;
-    const maxMs = options?.maxMs ?? 15_000;
+    const maxMs = options?.maxMs ?? Math.max(15_000, firstTimeout + settleMs);
 
     // Wait for the first session
     try {
@@ -538,7 +674,7 @@ export class BridgeConnection extends EventEmitter {
 
     this._host.on('plugin-connected', (info) => {
       const state = info.state ?? 'Edit';
-      const context = BridgeConnection._deriveContext(state);
+      const context = info.context ?? BridgeConnection._deriveContext(state);
 
       const sessionInfo: SessionInfo = {
         sessionId: info.sessionId,
@@ -548,7 +684,9 @@ export class BridgeConnection extends EventEmitter {
         pluginVersion: info.pluginVersion ?? '',
         capabilities: info.capabilities,
         connectedAt: new Date(),
-        origin: 'user',
+        origin: info.launchId ? 'managed' : 'user',
+        launchId: info.launchId,
+        playerName: info.playerName,
         context,
         instanceId: info.instanceId ?? info.sessionId,
         placeId: 0,
@@ -578,6 +716,7 @@ export class BridgeConnection extends EventEmitter {
             type: 'list-sessions-response',
             requestId: req.requestId,
             sessions: this._tracker!.listSessions(),
+            protocolVersion: HOST_PROTOCOL_VERSION,
           });
         } else if (msg.type === 'list-instances') {
           const req = msg as ListInstancesRequest;
@@ -586,6 +725,10 @@ export class BridgeConnection extends EventEmitter {
             requestId: req.requestId,
             instances: this._tracker!.listInstances(),
           });
+        } else if (msg.type === 'host-envelope') {
+          const relay = this._relayEnvelopeAsync(msg as HostEnvelope, reply);
+          this._pendingRelays.add(relay);
+          void relay.finally(() => this._pendingRelays.delete(relay));
         }
       }
     );
@@ -597,6 +740,49 @@ export class BridgeConnection extends EventEmitter {
     // when sessions are removed (going from >0 to 0).
   }
 
+  private async _relayEnvelopeAsync(
+    envelope: HostEnvelope,
+    reply: (m: HostProtocolMessage) => void
+  ): Promise<void> {
+    const sessionId = envelope.targetSessionId;
+    const handle = this._hostHandles.get(sessionId);
+
+    if (envelope.timeoutMs === undefined) {
+      handle?.sendMessage(envelope.action);
+      return;
+    }
+
+    let result: PluginMessage;
+    if (!handle) {
+      result = {
+        type: 'error',
+        sessionId,
+        payload: {
+          code: 'SESSION_MISMATCH',
+          message: `Session '${sessionId}' is not connected to this host`,
+        },
+      };
+    } else {
+      try {
+        result = await handle.sendActionAsync<PluginMessage>(
+          envelope.action,
+          envelope.timeoutMs
+        );
+      } catch (err) {
+        result = {
+          type: 'error',
+          sessionId,
+          payload: {
+            code: 'INTERNAL_ERROR',
+            message: err instanceof Error ? err.message : String(err),
+          },
+        };
+      }
+    }
+
+    reply({ type: 'host-response', requestId: envelope.requestId, result });
+  }
+
   private async _initClientAsync(
     port: number,
     remoteHost?: string
@@ -621,6 +807,7 @@ export class BridgeConnection extends EventEmitter {
 
     const host = remoteHost ? remoteHost.split(':')[0] : undefined;
     await this._client.connectAsync(port, host);
+    this._clientPort = port;
     this._isConnected = true;
   }
 
@@ -646,7 +833,15 @@ export class BridgeConnection extends EventEmitter {
 
     // 5a: Context specified
     if (context) {
-      const match = sessions.find((s) => s.context === context);
+      const matches = sessions.filter((s) => s.context === context);
+      if (matches.length > 1) {
+        throw new SessionNotFoundError(
+          `Instance '${instanceId}' has several ${context} sessions. Use --target <session id> to pick one:\n${matches
+            .map((s) => `  - ${s.sessionId}`)
+            .join('\n')}`
+        );
+      }
+      const match = matches[0];
       if (match) {
         const session = this.getSession(match.sessionId);
         if (session) {

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

@@ -140,12 +140,13 @@ describe('BridgeSession', () => {
       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((msg as any).payload.timeoutMs).toBe(120_000);
+      expect(timeout).toBe(125_000);
 
       expect(result.success).toBe(true);
     });
 
-    it('uses custom timeout when provided', async () => {
+    it('has the plugin cancel the script at a custom timeout, then waits for its reply', async () => {
       const handle = new MockTransportHandle();
       handle.sendActionAsync.mockResolvedValueOnce({
         type: 'scriptComplete',
@@ -156,8 +157,9 @@ describe('BridgeSession', () => {
       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);
+      const [msg, timeout] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as any).payload.timeoutMs).toBe(5_000);
+      expect(timeout).toBe(10_000);
     });
 
     it('returns error info from error response', async () => {