@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/plugin/playtest-bridge.ts

@@ -0,0 +1,98 @@
+/**
+ * Builds the studio-bridge client the edit session plants into a playtest's
+ * server, for when Studio does not load user plugins into playtests.
+ *
+ * The planted client is an ordinary Script, so it can neither `loadstring`
+ * nor set a ModuleScript's source. Everything it may run is compiled ahead of
+ * time here: each source becomes a ModuleScript returning its function and
+ * the source itself, which the client's router looks up by exact text when
+ * the bridge pushes an action or sends a script (see PrecompiledSources.lua).
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { resolveTemplatePath } from '@quenty/nevermore-template-helpers';
+import { loadActionSourcesAsync } from '../commands/framework/action-loader.js';
+import { getPluginBuildVersionAsync } from './plugin-build-version.js';
+
+/** The `bridge` of a `startPlaytest` request. */
+export interface PlaytestBridge {
+  /** Source of the planted entry Script. */
+  entrySource: string;
+  /** Source of the entry LocalScript planted for the playtest's clients, if any. */
+  clientEntrySource?: string;
+  /** The plugin's Shared modules, by name. */
+  modules: Record<string, string>;
+  /** ModuleScript sources compiled ahead of time, see `wrapPrecompiledSource`. */
+  precompiled: string[];
+}
+
+const templateDir = resolveTemplatePath(
+  import.meta.url,
+  'studio-bridge-plugin'
+);
+
+/**
+ * Builds the bridge to plant, able to run every action plus `scripts`, the
+ * code a caller will send the playtest's server session.
+ */
+export async function buildPlaytestBridgeAsync(
+  scripts: string[] = [],
+  options: { withClient?: boolean } = {}
+): Promise<PlaytestBridge> {
+  const [entrySource, clientEntrySource, modules, actions] = await Promise.all([
+    fs.readFile(
+      path.join(templateDir, 'playtest', 'StudioBridgePlaytest.server.lua'),
+      'utf-8'
+    ),
+    options.withClient
+      ? fs.readFile(
+          path.join(templateDir, 'playtest', 'StudioBridgePlaytest.client.lua'),
+          'utf-8'
+        )
+      : Promise.resolve(undefined),
+    readSharedModulesAsync(),
+    loadActionSourcesAsync(),
+  ]);
+
+  const sources = [...new Set([...actions.map((a) => a.source), ...scripts])];
+  return {
+    entrySource,
+    ...(clientEntrySource ? { clientEntrySource } : {}),
+    modules,
+    precompiled: sources.map(wrapPrecompiledSource),
+  };
+}
+
+async function readSharedModulesAsync(): Promise<Record<string, string>> {
+  const sharedDir = path.join(templateDir, 'src', 'Shared');
+  const version = await getPluginBuildVersionAsync();
+
+  const modules: Record<string, string> = {};
+  for (const fileName of await fs.readdir(sharedDir)) {
+    if (!fileName.endsWith('.lua') || fileName.endsWith('.spec.lua')) {
+      continue;
+    }
+    const source = await fs.readFile(path.join(sharedDir, fileName), 'utf-8');
+    modules[path.basename(fileName, '.lua')] = source.replaceAll(
+      '{{PLUGIN_VERSION}}',
+      version
+    );
+  }
+  return modules;
+}
+
+/**
+ * A ModuleScript source returning `{ fn, source }` for `source`. The function
+ * opens on the first line, so line numbers in errors match `source`. The text
+ * is a long string led by a character that is cut off again, since a long
+ * string drops a leading newline.
+ */
+export function wrapPrecompiledSource(source: string): string {
+  // The string must close at its closer, not inside or straddling `source`
+  let level = '';
+  while (`${source}]${level}]`.indexOf(`]${level}]`) !== source.length) {
+    level += '=';
+  }
+  return `return { fn = function(...) ${source}\nend, source = string.sub([${level}[x${source}]${level}], 2) }`;
+}

package/src/process/studio-launch-registry.test.ts

@@ -0,0 +1,56 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  findStudioLaunch,
+  readStudioLaunchesAsync,
+  recordStudioLaunchAsync,
+} from './studio-launch-registry.js';
+
+describe('studio launch registry', () => {
+  let dir: string;
+  let file: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'launch-registry-'));
+    file = path.join(dir, 'nested', 'launches.json');
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('records launches and reads them back', async () => {
+    await recordStudioLaunchAsync(
+      { pid: 10, cwd: '/game', opened: 'a new Baseplate', launchedAt: 1 },
+      file
+    );
+
+    expect(await readStudioLaunchesAsync(file)).toEqual([
+      { pid: 10, cwd: '/game', opened: 'a new Baseplate', launchedAt: 1 },
+    ]);
+  });
+
+  it('reads a missing or broken registry as empty', async () => {
+    expect(await readStudioLaunchesAsync(file)).toEqual([]);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, 'not json');
+    expect(await readStudioLaunchesAsync(file)).toEqual([]);
+  });
+
+  it('finds a launch by pid, else by when the process started', () => {
+    const records = [
+      { pid: 10, cwd: '/a', opened: 'x', launchedAt: 1_000 },
+      { cwd: '/b', opened: 'y', launchedAt: 60_000 },
+    ];
+
+    expect(findStudioLaunch(records, { pid: 10 })?.cwd).toBe('/a');
+    expect(findStudioLaunch(records, { pid: 99, startedAt: 62_000 })?.cwd).toBe(
+      '/b'
+    );
+    expect(
+      findStudioLaunch(records, { pid: 99, startedAt: 500_000 })
+    ).toBeUndefined();
+  });
+});

package/src/process/studio-launch-registry.ts

@@ -0,0 +1,63 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+
+const LAUNCH_MATCH_WINDOW_MS = 10_000;
+const MAX_RECORDS = 50;
+
+export interface StudioLaunchRecord {
+  pid?: number;
+  cwd: string;
+  opened: string;
+  launchedAt: number;
+}
+
+export function defaultLaunchRegistryPath(): string {
+  return path.join(os.tmpdir(), 'studio-bridge', 'launches.json');
+}
+
+export async function recordStudioLaunchAsync(
+  record: StudioLaunchRecord,
+  registryPath = defaultLaunchRegistryPath()
+): Promise<void> {
+  const records = await readStudioLaunchesAsync(registryPath);
+  records.push(record);
+  await fs.mkdir(path.dirname(registryPath), { recursive: true });
+  await fs.writeFile(
+    registryPath,
+    JSON.stringify(records.slice(-MAX_RECORDS), null, 2)
+  );
+}
+
+export async function readStudioLaunchesAsync(
+  registryPath = defaultLaunchRegistryPath()
+): Promise<StudioLaunchRecord[]> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(registryPath, 'utf-8'));
+    return Array.isArray(parsed)
+      ? parsed.filter(
+          (r): r is StudioLaunchRecord =>
+            r && typeof r.cwd === 'string' && typeof r.launchedAt === 'number'
+        )
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export function findStudioLaunch(
+  records: StudioLaunchRecord[],
+  process: { pid: number; startedAt?: number }
+): StudioLaunchRecord | undefined {
+  const byPid = records.filter((r) => r.pid === process.pid);
+  if (byPid.length > 0) {
+    return byPid[byPid.length - 1];
+  }
+  if (process.startedAt === undefined) {
+    return undefined;
+  }
+  const near = records.filter(
+    (r) => Math.abs(r.launchedAt - process.startedAt!) <= LAUNCH_MATCH_WINDOW_MS
+  );
+  return near.length === 1 ? near[0] : undefined;
+}

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

@@ -14,6 +14,7 @@ export interface RunningStudioProcess {
   pid: number;
   windowTitle: string;
   commandLine?: string;
+  startedAt?: number;
 }
 
 export interface CloseStudioOptions {
@@ -31,7 +32,7 @@ export async function listStudioProcessesAsync(): Promise<
         '-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',
+        "@(Get-CimInstance Win32_Process -Filter \"Name='RobloxStudioBeta.exe'\" | ForEach-Object { [pscustomobject]@{ Id = $_.ProcessId; MainWindowTitle = (Get-Process -Id $_.ProcessId -ErrorAction SilentlyContinue).MainWindowTitle; CommandLine = $_.CommandLine; StartTime = $_.CreationDate.ToUniversalTime().ToString('o') } }) | ConvertTo-Json -Compress",
       ],
       { reject: false }
     );
@@ -39,7 +40,7 @@ export async function listStudioProcessesAsync(): Promise<
   }
 
   if (process.platform === 'darwin') {
-    const { stdout } = await execa('ps', ['-axo', 'pid=,command='], {
+    const { stdout } = await execa('ps', ['-axo', 'pid=,etime=,command='], {
       reject: false,
     });
     return parseMacProcessList(stdout);
@@ -58,35 +59,59 @@ export function parseWindowsProcessList(
     Id: number;
     MainWindowTitle: string | null;
     CommandLine?: string | null;
+    StartTime?: 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,
-  }));
+  return entries.map((entry) => {
+    const startedAt = entry.StartTime ? Date.parse(entry.StartTime) : NaN;
+    return {
+      pid: entry.Id,
+      windowTitle: entry.MainWindowTitle ?? '',
+      commandLine: entry.CommandLine ?? undefined,
+      ...(Number.isFinite(startedAt) ? { startedAt } : {}),
+    };
+  });
 }
 
-export function parseMacProcessList(stdout: string): RunningStudioProcess[] {
+export function parseMacProcessList(
+  stdout: string,
+  now = Date.now()
+): RunningStudioProcess[] {
   const processes: RunningStudioProcess[] = [];
   for (const line of stdout.split('\n')) {
     const match =
-      /^\s*(\d+)\s+(.*RobloxStudio\.app\/Contents\/MacOS\/RobloxStudio.*)$/.exec(
+      /^\s*(\d+)\s+(?:([\d:-]+)\s+)?(.*RobloxStudio\.app\/Contents\/MacOS\/RobloxStudio.*)$/.exec(
         line
       );
     if (match) {
+      const elapsedSec = match[2] ? parseElapsedSeconds(match[2]) : undefined;
       processes.push({
         pid: Number(match[1]),
-        windowTitle: match[2],
-        commandLine: match[2],
+        windowTitle: match[3],
+        commandLine: match[3],
+        ...(elapsedSec !== undefined
+          ? { startedAt: now - elapsedSec * 1000 }
+          : {}),
       });
     }
   }
   return processes;
 }
 
+export function parseElapsedSeconds(etime: string): number | undefined {
+  const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(etime.trim());
+  if (!match) return undefined;
+  const [, days, hours, minutes, seconds] = match;
+  return (
+    Number(days ?? 0) * 86400 +
+    Number(hours ?? 0) * 3600 +
+    Number(minutes) * 60 +
+    Number(seconds)
+  );
+}
+
 /**
  * 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

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { matchProcessByUptime } from './studio-process-identity.js';
+
+describe('matchProcessByUptime', () => {
+  const now = 1_000_000_000;
+  const processes = [
+    { pid: 1, startedAt: now - 300_000 },
+    { pid: 2, startedAt: now - 290_000 },
+    { pid: 3 },
+  ];
+
+  it('picks the process started when the uptime says', () => {
+    expect(
+      matchProcessByUptime(processes, { uptimeSec: 290.4, observedAt: now })
+        ?.pid
+    ).toBe(2);
+  });
+
+  it('allows for the clock starting after the process and drifting with age', () => {
+    expect(
+      matchProcessByUptime([{ pid: 9, startedAt: now - 3_600_000 - 10_000 }], {
+        uptimeSec: 3600,
+        observedAt: now,
+      })?.pid
+    ).toBe(9);
+  });
+
+  it('finds nothing outside the tolerance', () => {
+    expect(
+      matchProcessByUptime(processes, { uptimeSec: 250, observedAt: now })
+    ).toBeUndefined();
+  });
+
+  it('refuses to choose between two processes started together', () => {
+    expect(
+      matchProcessByUptime(
+        [
+          { pid: 1, startedAt: now - 100_000 },
+          { pid: 2, startedAt: now - 100_500 },
+        ],
+        { uptimeSec: 100.2, observedAt: now }
+      )
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,90 @@
+import type { BridgeConnection, SessionInfo } from '../bridge/index.js';
+import type { RunningStudioProcess } from './studio-process-closer.js';
+
+export const UPTIME_TOLERANCE_MS = 3000;
+const UPTIME_DRIFT_RATIO = 0.0025;
+const UPTIME_READ_TIMEOUT_MS = 3000;
+
+export interface UptimeReading {
+  uptimeSec: number;
+  observedAt: number;
+}
+
+export function matchProcessByUptime<
+  T extends Pick<RunningStudioProcess, 'pid' | 'startedAt'>
+>(processes: T[], reading: UptimeReading): T | undefined {
+  const startedAt = reading.observedAt - reading.uptimeSec * 1000;
+  const tolerance =
+    UPTIME_TOLERANCE_MS + reading.uptimeSec * 1000 * UPTIME_DRIFT_RATIO;
+  const candidates = processes
+    .filter((p) => p.startedAt !== undefined)
+    .map((p) => ({ process: p, delta: Math.abs(p.startedAt! - startedAt) }))
+    .sort((a, b) => a.delta - b.delta);
+  const [best, next] = candidates;
+  if (!best || best.delta > tolerance) {
+    return undefined;
+  }
+  if (next && next.delta <= tolerance) {
+    return undefined;
+  }
+  return best.process;
+}
+
+export async function resolveSessionPidsAsync(
+  connection: BridgeConnection,
+  processes: RunningStudioProcess[],
+  instanceIds?: string[]
+): Promise<Map<string, number>> {
+  const pids = new Map<string, number>();
+  if (!processes.some((p) => p.startedAt !== undefined)) {
+    return pids;
+  }
+
+  const byInstance = new Map<string, SessionInfo[]>();
+  for (const session of connection.listSessions()) {
+    if (instanceIds && !instanceIds.includes(session.instanceId)) continue;
+    const list = byInstance.get(session.instanceId) ?? [];
+    list.push(session);
+    byInstance.set(session.instanceId, list);
+  }
+
+  await Promise.all(
+    [...byInstance].map(async ([instanceId, sessions]) => {
+      const ordered = [...sessions].sort(
+        (a, b) => Number(b.context === 'edit') - Number(a.context === 'edit')
+      );
+      for (const info of ordered) {
+        const reading = await _readUptimeAsync(connection, info.sessionId);
+        if (reading) {
+          const match = matchProcessByUptime(processes, reading);
+          if (match) {
+            pids.set(instanceId, match.pid);
+          }
+          return;
+        }
+      }
+    })
+  );
+  return pids;
+}
+
+async function _readUptimeAsync(
+  connection: BridgeConnection,
+  sessionId: string
+): Promise<UptimeReading | undefined> {
+  try {
+    const session = await connection.resolveSessionAsync(sessionId);
+    const sentAt = Date.now();
+    const result = await session.execAsync(
+      'return os.clock()',
+      UPTIME_READ_TIMEOUT_MS
+    );
+    const uptimeSec = Number(result.returnValues?.[0]);
+    if (!result.success || !Number.isFinite(uptimeSec)) {
+      return undefined;
+    }
+    return { uptimeSec, observedAt: (sentAt + Date.now()) / 2 };
+  } catch {
+    return undefined;
+  }
+}

package/src/roblox-mcp/index.ts

@@ -0,0 +1,17 @@
+export {
+  tryListStudiosAsync,
+  tryExecuteLuauAsync,
+  tryCallStudioToolAsync,
+  closeStudioMcpAsync,
+  type StudioMcpTarget,
+  type StudioMcpFailure,
+  type StudioMcpResult,
+  type StudioMcpOptions,
+  type StudioMcpLuauOptions,
+} from './roblox-studio-mcp.js';
+export {
+  getStudioMcpSnapshotAsync,
+  resetStudioMcpSnapshot,
+  type StudioMcpSnapshot,
+  type StudioMcpSnapshotOptions,
+} from './studio-mcp-snapshot.js';

package/src/roblox-mcp/mcp/mcp-stdio-client.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest';
+import { McpStdioClient } from './mcp-stdio-client.js';
+import {
+  createFakeMcpServer,
+  toolText,
+  type FakeHandler,
+} from '../test/fake-mcp-server.js';
+
+const initialize: FakeHandler = (method) =>
+  method === 'initialize'
+    ? {
+        result: {
+          protocolVersion: '2025-06-18',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'RobloxStudio', version: '1.0.0' },
+        },
+      }
+    : undefined;
+
+async function startAsync(handler: FakeHandler, requestTimeoutMs?: number) {
+  const server = createFakeMcpServer(
+    (method, params) => initialize(method, params) ?? handler(method, params)
+  );
+  const client = await McpStdioClient.startAsync('StudioMCP.exe', {
+    spawnProcess: () => server.child,
+    requestTimeoutMs,
+  });
+  return { server, client };
+}
+
+describe('McpStdioClient', () => {
+  it('initializes, then says it is initialized', async () => {
+    const { server, client } = await startAsync(() => undefined);
+
+    expect(client.protocolVersion).toBe('2025-06-18');
+    expect(client.serverInfo?.name).toBe('RobloxStudio');
+    expect(server.requests.map((r) => r.method)).toEqual([
+      'initialize',
+      'notifications/initialized',
+    ]);
+    await client.closeAsync();
+  });
+
+  it('lists tools, repairing a list result without caching hints', async () => {
+    const { client } = await startAsync((method) =>
+      method === 'tools/list'
+        ? {
+            result: {
+              resultType: 'complete',
+              tools: [{ name: 'execute_luau' }],
+            },
+          }
+        : undefined
+    );
+
+    expect(await client.listToolsAsync()).toEqual([{ name: 'execute_luau' }]);
+    await expect(client.requestAsync('tools/list', {})).resolves.toMatchObject({
+      ttlMs: 0,
+      cacheScope: 'private',
+    });
+    await client.closeAsync();
+  });
+
+  it('calls a tool and joins its text content', async () => {
+    const { server, client } = await startAsync((method) =>
+      method === 'tools/call' ? toolText('42') : undefined
+    );
+
+    const result = await client.callToolAsync('execute_luau', { code: 'x' });
+
+    expect(result).toMatchObject({ isError: false, text: '42' });
+    expect(server.requests.at(-1)?.params).toEqual({
+      name: 'execute_luau',
+      arguments: { code: 'x' },
+    });
+    await client.closeAsync();
+  });
+
+  it('reports a tool error as isError rather than throwing', async () => {
+    const { client } = await startAsync(() => toolText('boom', true));
+
+    await expect(client.callToolAsync('execute_luau')).resolves.toMatchObject({
+      isError: true,
+      text: 'boom',
+    });
+    await client.closeAsync();
+  });
+
+  it('rejects a JSON-RPC error with its message', async () => {
+    const { client } = await startAsync(() => ({
+      error: { code: -32602, message: 'bad params' },
+    }));
+
+    await expect(client.requestAsync('tools/call', {})).rejects.toThrow(
+      'tools/call failed: bad params'
+    );
+    await client.closeAsync();
+  });
+
+  it('rejects requests in flight when the server exits, with its stderr', async () => {
+    const { server, client } = await startAsync(() => undefined);
+
+    const pending = client.callToolAsync('execute_luau');
+    server.exit(3, 'Studio went away');
+
+    await expect(pending).rejects.toThrow(
+      "Studio's MCP server exited (code 3): Studio went away"
+    );
+    await expect(client.callToolAsync('execute_luau')).rejects.toThrow(
+      'exited'
+    );
+  });
+
+  it('waits for the server to exit when closed', async () => {
+    const { server, client } = await startAsync(() => undefined);
+
+    await client.closeAsync();
+
+    expect(server.child.killed).toBe(true);
+    expect(client.isRunning).toBe(false);
+    await expect(client.callToolAsync('execute_luau')).rejects.toThrow(
+      'closed'
+    );
+  });
+
+  it('closes a server that already exited without killing it again', async () => {
+    const { server, client } = await startAsync(() => undefined);
+    server.exit(0);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    await client.closeAsync();
+
+    expect(server.child.killed).toBe(false);
+  });
+
+  it('times out a request the server never answers', async () => {
+    const { client } = await startAsync(() => undefined);
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+
+    const pending = expect(
+      client.callToolAsync('execute_luau')
+    ).rejects.toThrow('tools/call timed out after 30000ms');
+    await vi.advanceTimersByTimeAsync(30_000);
+    await pending;
+    vi.useRealTimers();
+    await client.closeAsync();
+  });
+});