@quenty/studio-bridge 0.21.1 → 0.22.0

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

@@ -0,0 +1,187 @@
+/**
+ * Finds running Roblox Studio processes and closes them. The plugin API has
+ * no process id, so a bridge session is matched to its process by the place
+ * name Studio shows in the window title, or by the place id a cloud place was
+ * launched with.
+ */
+
+import { execa } from 'execa';
+
+const WINDOW_TITLE_SUFFIX = ' - Roblox Studio';
+const EXIT_POLL_INTERVAL_MS = 250;
+
+export interface RunningStudioProcess {
+  pid: number;
+  windowTitle: string;
+  commandLine?: string;
+}
+
+export interface CloseStudioOptions {
+  force?: boolean;
+  exitTimeoutMs?: number;
+}
+
+export async function listStudioProcessesAsync(): Promise<
+  RunningStudioProcess[]
+> {
+  if (process.platform === 'win32') {
+    const { stdout } = await execa(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        '@(Get-CimInstance Win32_Process -Filter "Name=\'RobloxStudioBeta.exe\'" | ForEach-Object { [pscustomobject]@{ Id = $_.ProcessId; MainWindowTitle = (Get-Process -Id $_.ProcessId -ErrorAction SilentlyContinue).MainWindowTitle; CommandLine = $_.CommandLine } }) | ConvertTo-Json -Compress',
+      ],
+      { reject: false }
+    );
+    return parseWindowsProcessList(stdout);
+  }
+
+  if (process.platform === 'darwin') {
+    const { stdout } = await execa('ps', ['-axo', 'pid=,command='], {
+      reject: false,
+    });
+    return parseMacProcessList(stdout);
+  }
+
+  throw new Error(`Closing Studio is not supported on ${process.platform}`);
+}
+
+export function parseWindowsProcessList(
+  stdout: string
+): RunningStudioProcess[] {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+
+  type Entry = {
+    Id: number;
+    MainWindowTitle: string | null;
+    CommandLine?: string | null;
+  };
+  const parsed = JSON.parse(trimmed) as Entry | Entry[];
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+
+  return entries.map((entry) => ({
+    pid: entry.Id,
+    windowTitle: entry.MainWindowTitle ?? '',
+    commandLine: entry.CommandLine ?? undefined,
+  }));
+}
+
+export function parseMacProcessList(stdout: string): RunningStudioProcess[] {
+  const processes: RunningStudioProcess[] = [];
+  for (const line of stdout.split('\n')) {
+    const match =
+      /^\s*(\d+)\s+(.*RobloxStudio\.app\/Contents\/MacOS\/RobloxStudio.*)$/.exec(
+        line
+      );
+    if (match) {
+      processes.push({
+        pid: Number(match[1]),
+        windowTitle: match[2],
+        commandLine: match[2],
+      });
+    }
+  }
+  return processes;
+}
+
+/**
+ * Processes whose window shows the given place. Studio titles a local file
+ * by its full path and a cloud place by its name on the website, which the
+ * plugin can't see, so with no title match a cloud place is found by the
+ * `placeId` Studio was launched with.
+ */
+export function matchStudioProcesses(
+  processes: RunningStudioProcess[],
+  placeName: string,
+  placeId?: number
+): RunningStudioProcess[] {
+  const byTitle = processes.filter((proc) => {
+    const title = proc.windowTitle.endsWith(WINDOW_TITLE_SUFFIX)
+      ? proc.windowTitle.slice(0, -WINDOW_TITLE_SUFFIX.length)
+      : proc.windowTitle;
+
+    return (
+      title === placeName ||
+      title.endsWith(`\\${placeName}`) ||
+      title.endsWith(`/${placeName}`)
+    );
+  });
+  if (byTitle.length > 0 || !placeId) {
+    return byTitle;
+  }
+  return matchStudioProcessesByPlaceId(processes, placeId);
+}
+
+/** Processes Studio launched with `placeId`, as `process launch` and the website's "Edit in Studio" do. */
+export function matchStudioProcessesByPlaceId(
+  processes: RunningStudioProcess[],
+  placeId: number
+): RunningStudioProcess[] {
+  const launchedPlaceId = new RegExp(`placeId:${placeId}(\\D|$)`);
+  return processes.filter(
+    (proc) => proc.commandLine && launchedPlaceId.test(proc.commandLine)
+  );
+}
+
+/**
+ * Close a Studio process. Without `force` Studio is asked to close its
+ * window, which it can refuse by prompting to save. Resolves whether the
+ * process exited within the timeout.
+ */
+export async function closeStudioProcessAsync(
+  pid: number,
+  options: CloseStudioOptions = {}
+): Promise<boolean> {
+  const { force = false, exitTimeoutMs = 10_000 } = options;
+
+  if (process.platform === 'win32') {
+    if (force) {
+      await execa('taskkill', ['/F', '/T', '/PID', String(pid)], {
+        reject: false,
+      });
+    } else {
+      await execa(
+        'powershell.exe',
+        [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          `(Get-Process -Id ${pid} -ErrorAction SilentlyContinue).CloseMainWindow() | Out-Null`,
+        ],
+        { reject: false }
+      );
+    }
+  } else {
+    try {
+      process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+    } catch {
+      return !isProcessRunning(pid);
+    }
+  }
+
+  return waitForExitAsync(pid, exitTimeoutMs);
+}
+
+export function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+async function waitForExitAsync(
+  pid: number,
+  timeoutMs: number
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, EXIT_POLL_INTERVAL_MS));
+  }
+  return !isProcessRunning(pid);
+}

package/src/process/studio-settings.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { parseBoolSetting } from './studio-settings.js';
+
+describe('parseBoolSetting', () => {
+  const xml = `<Item class="UserSettings"><Properties>
+    <bool name="LoadAllBuiltinPluginsInRunModes">true</bool>
+    <bool name="LoadUserPluginsInRunModes">false</bool>
+  </Properties></Item>`;
+
+  it('reads the named setting, not one whose name contains it', () => {
+    expect(parseBoolSetting(xml, 'LoadUserPluginsInRunModes')).toBe(false);
+    expect(parseBoolSetting(xml, 'LoadAllBuiltinPluginsInRunModes')).toBe(true);
+  });
+
+  it('is undefined for a setting the file does not have', () => {
+    expect(parseBoolSetting(xml, 'Missing')).toBeUndefined();
+  });
+});

package/src/process/studio-settings.ts

@@ -0,0 +1,61 @@
+/**
+ * Reads Studio's own settings from the file it saves them to, for settings a
+ * plugin can't read.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { findPluginsFolder } from './studio-process-manager.js';
+
+/** The XML name of Studio's "Load user plugins on playtest" setting. */
+const LOAD_USER_PLUGINS_ON_PLAYTEST = 'LoadUserPluginsInRunModes';
+
+/**
+ * Whether Studio's "Load user plugins on playtest" setting is on. Without it,
+ * the plugin doesn't load into a playtest's DataModels, so they never connect
+ * to the bridge. Undefined when the setting can't be read, e.g. on macOS,
+ * whose settings file isn't located here.
+ */
+export async function tryReadLoadUserPluginsOnPlaytestAsync(): Promise<
+  boolean | undefined
+> {
+  const settingsPath = findGlobalSettingsPath();
+  if (!settingsPath) {
+    return undefined;
+  }
+
+  let xml: string;
+  try {
+    xml = await fs.readFile(settingsPath, 'utf8');
+  } catch {
+    return undefined;
+  }
+  return parseBoolSetting(xml, LOAD_USER_PLUGINS_ON_PLAYTEST);
+}
+
+/** Reads `<bool name="...">true|false</bool>` from a Studio settings file. */
+export function parseBoolSetting(
+  xml: string,
+  name: string
+): boolean | undefined {
+  const match = new RegExp(
+    `<bool name="${name}">\\s*(true|false)\\s*</bool>`
+  ).exec(xml);
+  return match ? match[1] === 'true' : undefined;
+}
+
+/** Studio keeps its settings beside the plugins folder on Windows and under Wine. */
+function findGlobalSettingsPath(): string | undefined {
+  if (process.platform !== 'win32' && process.platform !== 'linux') {
+    return undefined;
+  }
+  try {
+    const robloxDir =
+      process.platform === 'linux'
+        ? path.posix.dirname(findPluginsFolder())
+        : path.dirname(findPluginsFolder());
+    return path.join(robloxDir, 'GlobalSettings_13.xml');
+  } catch {
+    return undefined;
+  }
+}

package/src/process/studio-window-state.ts

@@ -0,0 +1,65 @@
+/**
+ * Reads whether a Studio window is focused or minimized. The plugin API
+ * cannot see either, so this asks the OS about the process the session's
+ * place is showing in.
+ */
+
+import { execa } from 'execa';
+
+export interface StudioWindowState {
+  focused: boolean;
+  minimized: boolean;
+}
+
+const WINDOW_STATE_SCRIPT = `
+Add-Type -Namespace StudioBridge -Name User32 -MemberDefinition @'
+[DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
+[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+[DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint processId);
+'@
+$process = Get-Process -Id $args[0] -ErrorAction Stop
+$foregroundPid = [uint32]0
+[void][StudioBridge.User32]::GetWindowThreadProcessId([StudioBridge.User32]::GetForegroundWindow(), [ref]$foregroundPid)
+@{
+  minimized = [StudioBridge.User32]::IsIconic($process.MainWindowHandle)
+  focused = ($foregroundPid -eq $process.Id)
+} | ConvertTo-Json -Compress
+`;
+
+/** Undefined where the OS gives no answer, including outside Windows. */
+export async function tryGetStudioWindowStateAsync(
+  pid: number
+): Promise<StudioWindowState | undefined> {
+  if (process.platform !== 'win32') return undefined;
+
+  const { stdout, failed } = await execa(
+    'powershell.exe',
+    [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      `& { ${WINDOW_STATE_SCRIPT} } ${pid}`,
+    ],
+    { reject: false }
+  );
+  if (failed) return undefined;
+
+  return parseWindowState(stdout);
+}
+
+export function parseWindowState(
+  stdout: string
+): StudioWindowState | undefined {
+  try {
+    const parsed = JSON.parse(stdout.trim()) as Partial<StudioWindowState>;
+    if (
+      typeof parsed.focused !== 'boolean' ||
+      typeof parsed.minimized !== 'boolean'
+    ) {
+      return undefined;
+    }
+    return { focused: parsed.focused, minimized: parsed.minimized };
+  } catch {
+    return undefined;
+  }
+}

package/src/server/studio-bridge-server.ts

@@ -29,6 +29,7 @@ import {
   type SerializedReturnValue,
   encodeMessage,
   decodePluginMessage,
+  MAX_MESSAGE_BYTES,
 } from './web-socket-protocol.js';
 import { ActionDispatcher } from './action-dispatcher.js';
 import {
@@ -102,6 +103,8 @@ export interface ExecuteOptions {
   timeoutMs?: number;
   /** Callback for each output message */
   onOutput?: (level: OutputLevel, body: string) => void;
+  /** Passed to the script as `...`. */
+  args?: string[];
 }
 
 export interface StudioBridgeResult {
@@ -110,7 +113,7 @@ export interface StudioBridgeResult {
   /**
    * Everything the script returned, in order, marshalled by the plugin.
    * Absent whenever no `scriptComplete` carrying a return channel arrived —
-   * a timeout, a disconnect, a plugin error, or an older plugin build — which
+   * a timeout, a disconnect, or a plugin error — which
    * is what separates "we never learned what it returned" from `[]`, "it
    * returned nothing".
    */
@@ -320,7 +323,10 @@ export class StudioBridgeServer {
 
       // 1. Start HTTP + WebSocket server (unique path rejects wrong connections at upgrade level)
       this._httpServer = http.createServer();
-      this._wss = new WebSocketServer({ noServer: true });
+      this._wss = new WebSocketServer({
+        noServer: true,
+        maxPayload: MAX_MESSAGE_BYTES,
+      });
       const port = await startHttpAndWsServerAsync(
         this._httpServer,
         this._wss,
@@ -402,7 +408,12 @@ export class StudioBridgeServer {
         encodeMessage({
           type: 'execute',
           sessionId: this._sessionId,
-          payload: { script: options.scriptContent },
+          payload: {
+            script: options.scriptContent,
+            ...(options.args && options.args.length > 0
+              ? { args: options.args }
+              : {}),
+          },
         })
       );
 
@@ -482,7 +493,7 @@ export class StudioBridgeServer {
     const syncResult = await this.performActionAsync<PluginMessage>(
       {
         type: 'syncActions',
-        payload: { actions },
+        payload: { actions, verbose: OutputHelper.isVerbose() },
       },
       10_000
     );

package/src/server/web-socket-protocol.test.ts

@@ -325,6 +325,39 @@ describe('decodePluginMessage', () => {
     });
   });
 
+  describe('exportInstancesResult / importInstancesResult', () => {
+    it('decodes an exported model', () => {
+      const msg = {
+        type: 'exportInstancesResult',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: { data: 'PHJvYmxveCE=', paths: ['Workspace.Map'] },
+      };
+      expect(roundTripPlugin(msg)).toEqual(msg);
+    });
+
+    it('rejects an export without data', () => {
+      expect(
+        roundTripPlugin({
+          type: 'exportInstancesResult',
+          sessionId: 'sess-1',
+          requestId: 'req-1',
+          payload: { paths: ['Workspace.Map'] },
+        })
+      ).toBeNull();
+    });
+
+    it('decodes the imported paths', () => {
+      const msg = {
+        type: 'importInstancesResult',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: { paths: ['Workspace.Map'] },
+      };
+      expect(roundTripPlugin(msg)).toEqual(msg);
+    });
+  });
+
   describe('logsResult', () => {
     it('decodes a valid logsResult', () => {
       const msg = roundTripPlugin({
@@ -660,6 +693,28 @@ describe('encodeMessage / decodeServerMessage', () => {
     });
   });
 
+  describe('exportInstances / importInstances', () => {
+    it('round-trips exportInstances', () => {
+      const msg: ServerMessage = {
+        type: 'exportInstances',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: { paths: ['Workspace.Map', 'Lighting'] },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+
+    it('round-trips importInstances', () => {
+      const msg: ServerMessage = {
+        type: 'importInstances',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: { data: 'PHJvYmxveCE=', parentPath: 'Workspace' },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+  });
+
   describe('queryLogs', () => {
     it('round-trips queryLogs with all options', () => {
       const msg: ServerMessage = {