@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/commands/process/info/info.test.ts

@@ -3,74 +3,228 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { queryStateHandlerAsync } from './info.js';
-
-function createMockSession(stateResult: {
-  state: string;
-  placeId: number;
-  placeName: string;
-  gameId: number;
-}) {
+
+vi.mock('../../../process/studio-process-closer.js', async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import('../../../process/studio-process-closer.js')
+  >();
+  return {
+    ...actual,
+    listStudioProcessesAsync: vi.fn(async () => [
+      { pid: 42, windowTitle: 'C:/places/TestPlace - Roblox Studio' },
+    ]),
+  };
+});
+
+vi.mock('../../../process/studio-window-state.js', () => ({
+  tryGetStudioWindowStateAsync: vi.fn(async () => ({
+    focused: true,
+    minimized: false,
+  })),
+}));
+
+vi.mock('../../../plugin/plugin-build-version.js', () => ({
+  getPluginBuildVersionAsync: async () => 'abc123',
+}));
+
+import {
+  describePlaytest,
+  formatStateText,
+  queryStateHandlerAsync,
+} from './info.js';
+
+function sessionInfo(
+  sessionId: string,
+  context: 'edit' | 'server' | 'client',
+  overrides: Record<string, unknown> = {}
+) {
   return {
-    queryStateAsync: vi.fn().mockResolvedValue(stateResult),
+    sessionId,
+    instanceId: 'test-place-3f9a',
+    context,
+    origin: 'user',
+    placeName: 'TestPlace',
+    pluginVersion: 'abc123',
+    connectedAt: new Date('2026-10-27T18:00:00Z'),
+    ...overrides,
   } as any;
 }
 
-describe('queryStateHandlerAsync', () => {
-  it('returns state result with summary', async () => {
-    const session = createMockSession({
+function createMockSession(
+  stateResult: Record<string, unknown>,
+  infoOverrides: Record<string, unknown> = {}
+) {
+  return {
+    info: sessionInfo('test-place-3f9a-edit', 'edit', infoOverrides),
+    queryStateAsync: vi.fn().mockResolvedValue({
       state: 'Edit',
       placeId: 12345,
       placeName: 'TestPlace',
       gameId: 67890,
-    });
+      ...stateResult,
+    }),
+  } as any;
+}
+
+function createConnection(sessions: any[]) {
+  return { listSessions: () => sessions } as any;
+}
+
+describe('queryStateHandlerAsync', () => {
+  it('reports the session, place and run mode', async () => {
+    const session = createMockSession({ studioVersion: '0.744.0.7440803' });
 
     const result = await queryStateHandlerAsync(session);
 
-    expect(result.state).toBe('Edit');
-    expect(result.placeId).toBe(12345);
-    expect(result.placeName).toBe('TestPlace');
-    expect(result.gameId).toBe(67890);
-    expect(result.summary).toContain('Edit');
-    expect(result.summary).toContain('TestPlace');
-    expect(result.summary).toContain('12345');
+    expect(result).toMatchObject({
+      sessionId: 'test-place-3f9a-edit',
+      instanceId: 'test-place-3f9a',
+      context: 'edit',
+      origin: 'user',
+      state: 'Edit',
+      placeId: 12345,
+      placeName: 'TestPlace',
+      gameId: 67890,
+      studioVersion: '0.744.0.7440803',
+      connectedAt: '2026-10-27T18:00:00.000Z',
+    });
+    expect(result.summary).toBe('Mode: Edit, Place: TestPlace (12345)');
   });
 
-  it('calls session.queryStateAsync', async () => {
-    const session = createMockSession({
-      state: 'Play',
-      placeId: 100,
-      placeName: 'GamePlace',
-      gameId: 200,
+  it('compares the plugin version with the one the CLI installs', async () => {
+    const current = await queryStateHandlerAsync(createMockSession({}));
+    const stale = await queryStateHandlerAsync(
+      createMockSession({}, { pluginVersion: 'old999' })
+    );
+
+    expect(current.plugin).toEqual({
+      version: 'abc123',
+      expectedVersion: 'abc123',
+      upToDate: true,
     });
+    expect(stale.plugin.upToDate).toBe(false);
+    expect(formatStateText(stale)).toContain(
+      "out of date, expected abc123; run 'studio-bridge plugin install'"
+    );
+  });
 
-    await queryStateHandlerAsync(session);
+  it("reports the playtest running in the session's Studio", async () => {
+    const session = createMockSession({});
+    const connection = createConnection([
+      session.info,
+      sessionInfo('test-place-3f9a-server', 'server'),
+      sessionInfo('test-place-3f9a-client', 'client', {
+        playerName: 'Player1',
+      }),
+    ]);
 
-    expect(session.queryStateAsync).toHaveBeenCalledOnce();
+    const result = await queryStateHandlerAsync(session, connection);
+
+    expect(result.playtest).toEqual({
+      mode: 'play',
+      playerCount: undefined,
+      sessions: [
+        {
+          sessionId: 'test-place-3f9a-server',
+          context: 'server',
+          playerName: undefined,
+        },
+        {
+          sessionId: 'test-place-3f9a-client',
+          context: 'client',
+          playerName: 'Player1',
+        },
+      ],
+    });
+    expect(formatStateText(result)).toContain(
+      'Playtest: running (play mode): test-place-3f9a-server, test-place-3f9a-client'
+    );
   });
 
-  it('handles different state values correctly', async () => {
-    for (const state of ['Edit', 'Play', 'Paused', 'Run', 'Server', 'Client']) {
-      const session = createMockSession({
-        state,
-        placeId: 1,
-        placeName: 'Place',
-        gameId: 2,
-      });
-
-      const result = await queryStateHandlerAsync(session);
-      expect(result.state).toBe(state);
-      expect(result.summary).toContain(state);
-    }
+  it("finds a playtest's window by its DataModel's name, not the edit window", async () => {
+    const session = createMockSession(
+      { state: 'Server', placeName: 'TestPlace' },
+      { sessionId: 'test-place-3f9a-server', context: 'server' }
+    );
+    const connection = createConnection([
+      sessionInfo('test-place-3f9a-edit', 'edit'),
+      session.info,
+      sessionInfo('test-place-3f9a-client-player1', 'client'),
+      sessionInfo('test-place-3f9a-client-player2', 'client'),
+    ]);
+
+    const result = await queryStateHandlerAsync(session, connection);
+
+    expect(result.window?.pid).toBe(42);
+
+    session.queryStateAsync.mockResolvedValue({
+      state: 'Server',
+      placeId: 0,
+      placeName: 'Server',
+      gameId: 0,
+    });
+    const unmatched = await queryStateHandlerAsync(session, connection);
+    expect(unmatched.window).toBeUndefined();
   });
 
   it('propagates errors from session', async () => {
-    const session = {
-      queryStateAsync: vi.fn().mockRejectedValue(new Error('Connection lost')),
-    } as any;
+    const session = createMockSession({});
+    session.queryStateAsync.mockRejectedValue(new Error('Connection lost'));
 
     await expect(queryStateHandlerAsync(session)).rejects.toThrow(
       'Connection lost'
     );
   });
+
+  it('reports the window showing the place', async () => {
+    const result = await queryStateHandlerAsync(createMockSession({}));
+
+    expect(result.window).toEqual({ pid: 42, focused: true, minimized: false });
+    expect(formatStateText(result)).toContain(
+      'Window:   pid 42, open, focused'
+    );
+  });
+
+  it('leaves the window out when no window shows the place', async () => {
+    const result = await queryStateHandlerAsync(
+      createMockSession({ placeName: 'Elsewhere' })
+    );
+
+    expect(result.window).toBeUndefined();
+  });
+});
+
+describe('describePlaytest', () => {
+  it('is absent without playtest sessions', () => {
+    expect(
+      describePlaytest(
+        [sessionInfo('test-place-3f9a-edit', 'edit')],
+        'test-place-3f9a'
+      )
+    ).toBeUndefined();
+  });
+
+  it('reports run mode when only the server connected', () => {
+    expect(
+      describePlaytest(
+        [sessionInfo('test-place-3f9a-server', 'server')],
+        'test-place-3f9a'
+      )?.mode
+    ).toBe('run');
+  });
+
+  it('counts the players of a multiplayer test', () => {
+    const playtest = describePlaytest(
+      [
+        sessionInfo('test-place-3f9a-server', 'server'),
+        sessionInfo('test-place-3f9a-client-player1', 'client'),
+        sessionInfo('test-place-3f9a-client-player2', 'client'),
+        sessionInfo('other-1a2b-server', 'server', { instanceId: 'other' }),
+      ],
+      'test-place-3f9a'
+    );
+
+    expect(playtest?.playerCount).toBe(2);
+    expect(playtest?.sessions).toHaveLength(3);
+  });
 });

package/src/commands/process/info/info.ts

@@ -1,48 +1,236 @@
 /**
- * `process info` — query the current Studio state (mode, place info)
- * from a connected session.
+ * `process info` — report on one Studio session: its place and run mode, the
+ * playtest running in its Studio, its window, and whether its plugin is
+ * current.
  */
 
+import { OutputHelper } from '@quenty/cli-output-helpers';
 import { defineCommand } from '../../framework/define-command.js';
-import type { BridgeSession } from '../../../bridge/index.js';
-import type { StudioState } from '../../../bridge/index.js';
+import type {
+  BridgeConnection,
+  BridgeSession,
+  SessionContext,
+  SessionInfo,
+  SessionOrigin,
+  StudioState,
+} from '../../../bridge/index.js';
 import { colorizeState } from '../format-state.js';
+import {
+  listStudioProcessesAsync,
+  matchStudioProcesses,
+} from '../../../process/studio-process-closer.js';
+import { tryGetStudioWindowStateAsync } from '../../../process/studio-window-state.js';
+import { getPluginBuildVersionAsync } from '../../../plugin/plugin-build-version.js';
+
+export interface PlaytestInfo {
+  mode: 'play' | 'run';
+  /** Set for a multiplayer test: how many of its clients are connected. */
+  playerCount?: number;
+  sessions: Array<{
+    sessionId: string;
+    context: SessionContext;
+    playerName?: string;
+  }>;
+}
 
 export interface StateResult {
+  sessionId: string;
+  instanceId: string;
+  context: SessionContext;
+  origin: SessionOrigin;
+  /** The run mode of this session's own DataModel. */
   state: StudioState;
   placeId: number;
   placeName: string;
   gameId: number;
+  /** The camera viewport in pixels. Absent without a camera. */
+  viewportSize?: [number, number];
+  /** Absent from older plugins. */
+  studioVersion?: string;
+  plugin: {
+    version: string;
+    /** The version `studio-bridge plugin install` would install. */
+    expectedVersion: string;
+    upToDate: boolean;
+  };
+  /**
+   * The playtest running in this session's Studio, as seen through the
+   * sessions it opened. Absent when none is running or its sessions are not
+   * connected.
+   */
+  playtest?: PlaytestInfo;
+  /** The Studio window showing the place. Absent when it cannot be told apart. */
+  window?: {
+    pid: number;
+    focused: boolean;
+    minimized: boolean;
+  };
+  connectedAt: string;
   summary: string;
 }
 
 export async function queryStateHandlerAsync(
-  session: BridgeSession
+  session: BridgeSession,
+  connection?: BridgeConnection
 ): Promise<StateResult> {
-  const result = await session.queryStateAsync();
+  // Listed sessions carry the edit session's place name for a playtest
+  const listed = connection
+    ?.listSessions()
+    .find((s) => s.sessionId === session.info.sessionId);
+  const playtest = connection
+    ? describePlaytest(connection.listSessions(), session.info.instanceId)
+    : undefined;
+  // Each process of a multiplayer test has its own window; otherwise a
+  // playtest shows in the edit window
+  const ownWindow =
+    session.info.context !== 'edit' && playtest?.playerCount !== undefined;
+  const [result, expectedVersion] = await Promise.all([
+    session.queryStateAsync(),
+    getPluginBuildVersionAsync(),
+  ]);
+  const window = await tryGetWindowAsync(
+    ownWindow ? [result.placeName] : [result.placeName, listed?.placeName],
+    ownWindow ? undefined : result.placeId
+  );
 
   return {
+    sessionId: session.info.sessionId,
+    instanceId: session.info.instanceId,
+    context: session.info.context,
+    origin: session.info.origin,
     state: result.state,
     placeId: result.placeId,
-    placeName: result.placeName,
+    placeName: listed?.placeName || result.placeName,
     gameId: result.gameId,
+    viewportSize: result.viewportSize,
+    studioVersion: result.studioVersion,
+    plugin: {
+      version: session.info.pluginVersion,
+      expectedVersion,
+      upToDate: session.info.pluginVersion === expectedVersion,
+    },
+    playtest,
+    window,
+    connectedAt: new Date(session.info.connectedAt).toISOString(),
     summary: `Mode: ${result.state}, Place: ${result.placeName} (${result.placeId})`,
   };
 }
 
+/** The playtest of `instanceId`, from the sessions it opened. */
+export function describePlaytest(
+  sessions: SessionInfo[],
+  instanceId: string
+): PlaytestInfo | undefined {
+  const playtestSessions = sessions.filter(
+    (s) => s.instanceId === instanceId && s.context !== 'edit'
+  );
+  if (playtestSessions.length === 0) return undefined;
+
+  const clients = playtestSessions.filter((s) => s.context === 'client');
+  const isMultiplayer = clients.some(
+    (s) => s.sessionId !== `${instanceId}-client`
+  );
+
+  return {
+    mode: clients.length > 0 ? 'play' : 'run',
+    playerCount: isMultiplayer ? clients.length : undefined,
+    sessions: playtestSessions.map((s) => ({
+      sessionId: s.sessionId,
+      context: s.context,
+      playerName: s.playerName,
+    })),
+  };
+}
+
+/**
+ * The Studio window titled with the first of `placeNames` that any window
+ * has, when exactly one does. A multiplayer test's processes title their
+ * windows with their own DataModel's name, and its clients all share one;
+ * a single-process playtest shares the edit window.
+ */
+async function tryGetWindowAsync(
+  placeNames: Array<string | undefined>,
+  placeId?: number
+): Promise<StateResult['window']> {
+  const processes = await listStudioProcessesAsync().catch(() => []);
+  for (const placeName of placeNames) {
+    if (!placeName) continue;
+    const matches = matchStudioProcesses(processes, placeName, placeId);
+    if (matches.length === 0) continue;
+    if (matches.length > 1) return undefined;
+
+    const pid = matches[0].pid;
+    const state = await tryGetStudioWindowStateAsync(pid);
+    return state ? { pid, ...state } : undefined;
+  }
+  return undefined;
+}
+
+function formatAge(isoTime: string): string {
+  const seconds = Math.max(
+    0,
+    Math.round((Date.now() - Date.parse(isoTime)) / 1000)
+  );
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor(
+    (seconds % 3600) / 60
+  )}m ago`;
+}
+
+function formatPlaytest(playtest: PlaytestInfo | undefined): string {
+  if (!playtest) return 'none running';
+  const kind =
+    playtest.playerCount !== undefined
+      ? `multiplayer, ${playtest.playerCount} player${
+          playtest.playerCount === 1 ? '' : 's'
+        }`
+      : `${playtest.mode} mode`;
+  return `running (${kind}): ${playtest.sessions
+    .map((s) => s.sessionId)
+    .join(', ')}`;
+}
+
 export function formatStateText(result: StateResult): string {
-  return [
-    `Mode:    ${colorizeState(result.state)}`,
-    `Place:   ${result.placeName}`,
-    `PlaceId: ${result.placeId}`,
-    `GameId:  ${result.gameId}`,
-  ].join('\n');
+  const lines = [
+    `Session:  ${OutputHelper.formatHint(result.sessionId)} (${
+      result.context
+    }, ${result.origin}, connected ${formatAge(result.connectedAt)})`,
+    `Mode:     ${colorizeState(result.state)}`,
+    `Playtest: ${formatPlaytest(result.playtest)}`,
+    `Place:    ${result.placeName} (PlaceId ${result.placeId}, GameId ${result.gameId})`,
+  ];
+  if (result.viewportSize) {
+    lines.push(`Viewport: ${result.viewportSize[0]}x${result.viewportSize[1]}`);
+  }
+  if (result.window) {
+    const { pid, focused, minimized } = result.window;
+    lines.push(
+      `Window:   pid ${pid}, ${minimized ? 'minimized' : 'open'}, ${
+        focused ? 'focused' : 'not focused'
+      }`
+    );
+  }
+  if (result.studioVersion) {
+    lines.push(`Studio:   ${result.studioVersion}`);
+  }
+  lines.push(
+    `Plugin:   ${result.plugin.version || 'unknown'} ${
+      result.plugin.upToDate
+        ? '(up to date)'
+        : OutputHelper.formatWarning(
+            `(out of date, expected ${result.plugin.expectedVersion}; run 'studio-bridge plugin install')`
+          )
+    }`
+  );
+  return lines.join('\n');
 }
 
 export const infoCommand = defineCommand({
   group: 'process',
   name: 'info',
-  description: 'Query the current Studio state (mode, place info)',
+  description:
+    'Report on a Studio session: mode, playtest, place, window and plugin version',
   category: 'execution',
   safety: 'read',
   scope: 'session',
@@ -50,5 +238,6 @@ export const infoCommand = defineCommand({
   cli: {
     format: formatStateText,
   },
-  handler: async (session) => queryStateHandlerAsync(session),
+  handler: async (session, _args, connection) =>
+    queryStateHandlerAsync(session, connection),
 });

package/src/commands/process/info/query-state.lua

@@ -1,48 +1,61 @@
---[[
-	QueryState action handler for the studio-bridge plugin.
+--!strict
+--[=[
+	Action that answers `queryState` with Studio's run mode, the open place and
+	the Studio version.
 
-	Returns the current Studio run mode, place name, place ID, and game ID.
+	Request: `{ type: "queryState", payload: {} }`
+	Response: `{ type: "stateResult", payload: { state, placeName, placeId, gameId, viewportSize?, studioVersion } }`
 
-	Protocol:
-	  Request:  { type: "queryState", payload: {} }
-	  Response: { type: "stateResult", payload: { state, placeName, placeId, gameId } }
-]]
+	@class QueryStateAction
+]=]
 
 local RunService = game:GetService("RunService")
 
 local QueryStateAction = {}
 
--- ---------------------------------------------------------------------------
--- State detection
--- ---------------------------------------------------------------------------
-
-local function detectState(): string
-	if RunService:IsRunning() then
-		if RunService:IsClient() and not RunService:IsServer() then
-			return "Client"
-		elseif RunService:IsServer() and not RunService:IsClient() then
-			return "Server"
-		else
-			return "Play"
-		end
-	end
-	return "Edit"
-end
-
--- ---------------------------------------------------------------------------
--- Public API
--- ---------------------------------------------------------------------------
-
+--[=[
+	Registers the `queryState` handler.
+]=]
 function QueryStateAction.register(router: any)
 	router:setResponseType("queryState", "stateResult")
 	router:register("queryState", function(_payload: { [string]: any }, _requestId: string, _sessionId: string)
 		return {
-			state = detectState(),
+			state = QueryStateAction._getState(),
 			placeName = game.Name or "Unknown",
 			placeId = game.PlaceId,
 			gameId = game.GameId,
+			viewportSize = QueryStateAction._getViewportSize(),
+			-- selene: allow(undefined_variable)
+			studioVersion = version(),
 		}
 	end)
 end
 
+--[[
+	The camera's viewport in pixels, or nil when the DataModel has no camera.
+]]
+function QueryStateAction._getViewportSize(): { number }?
+	local camera = workspace.CurrentCamera
+	if not camera then
+		return nil
+	end
+	return { camera.ViewportSize.X, camera.ViewportSize.Y }
+end
+
+function QueryStateAction._getState(): string
+	if not RunService:IsRunning() then
+		return "Edit"
+	end
+
+	local isClient = RunService:IsClient()
+	local isServer = RunService:IsServer()
+	if isClient and not isServer then
+		return "Client"
+	elseif isServer and not isClient then
+		return "Server"
+	else
+		return "Play"
+	end
+end
+
 return QueryStateAction

package/src/commands/process/info/query-state.spec.lua

@@ -0,0 +1,39 @@
+--!strict
+--[[
+	@class query-state.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local QueryStateAction = require("query-state")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("queryState", function()
+	it("should answer stateResult with the run mode and the open place", function()
+		local router = ActionRouter.new()
+		QueryStateAction.register(router)
+
+		local response = router:Dispatch({ type = "queryState", sessionId = "session-1", payload = {} })
+		expect(type(response.payload.studioVersion)).toEqual("string")
+		response.payload.studioVersion = nil
+
+		expect(response).toEqual({
+			type = "stateResult",
+			sessionId = "session-1",
+			payload = {
+				state = "Edit",
+				placeName = game.Name,
+				placeId = game.PlaceId,
+				gameId = game.GameId,
+				viewportSize = if workspace.CurrentCamera
+					then { workspace.CurrentCamera.ViewportSize.X, workspace.CurrentCamera.ViewportSize.Y }
+					else nil,
+			},
+		})
+	end)
+end)