@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/roblox-mcp/studio/studio-session.ts

@@ -0,0 +1,279 @@
+import type { SessionContext, SessionInfo } from '../../bridge/types.js';
+import type { McpStdioClient } from '../mcp/mcp-stdio-client.js';
+import { matchProcessByUptime } from '../../process/studio-process-identity.js';
+
+export const DATAMODEL_TYPES: Record<SessionContext, string> = {
+  edit: 'Edit',
+  client: 'Client',
+  server: 'Server',
+};
+
+export class StudioNotFoundError extends Error {}
+
+const ASSISTANT_FRAME = /^(?:sabuiltin_[^\s:]+|AssistantCommand):\d+: /;
+
+export function cleanToolError(text: string): string {
+  let cleaned = text;
+  while (ASSISTANT_FRAME.test(cleaned)) {
+    cleaned = cleaned.replace(ASSISTANT_FRAME, '');
+  }
+  return cleaned;
+}
+
+export interface McpStudio {
+  studioId: string;
+  placeName: string;
+}
+
+export interface StudioWindow {
+  pid: number;
+  windowTitle: string;
+  startedAt?: number;
+}
+
+export interface MatchedStudio {
+  studioId: string;
+  placeName: string;
+  placeId?: number;
+  gameId?: number;
+  sessionId?: string;
+  instanceId?: string;
+  pid?: number;
+}
+
+export interface LuauRunResult {
+  success: boolean;
+  result?: string;
+  error?: string;
+}
+
+export async function listMcpStudiosAsync(
+  client: McpStdioClient
+): Promise<McpStudio[]> {
+  const reply = await client.callToolAsync('list_roblox_studios');
+  if (reply.isError) {
+    throw new Error(`Could not list Studios over MCP: ${reply.text}`);
+  }
+  let parsed: { studios?: Array<{ id?: unknown; name?: unknown }> };
+  try {
+    parsed = JSON.parse(reply.text);
+  } catch {
+    throw new Error(`Unexpected Studio list from MCP: ${reply.text}`);
+  }
+  return (parsed.studios ?? [])
+    .filter((s) => typeof s.id === 'string')
+    .map((s) => ({
+      studioId: s.id as string,
+      placeName: typeof s.name === 'string' ? s.name : '',
+    }));
+}
+
+export async function runLuauAsync(
+  client: McpStdioClient,
+  studioId: string,
+  code: string,
+  context: SessionContext = 'edit',
+  timeoutMs?: number
+): Promise<LuauRunResult> {
+  const reply = await client.callToolAsync(
+    'execute_luau',
+    { studio_id: studioId, datamodel_type: DATAMODEL_TYPES[context], code },
+    timeoutMs
+  );
+  return reply.isError
+    ? { success: false, error: cleanToolError(reply.text) }
+    : { success: true, result: reply.text };
+}
+
+export interface MatchStudiosOptions {
+  readPlaceIds?: boolean;
+  studios?: McpStudio[];
+  sessionPids?: Map<string, number>;
+}
+
+export async function matchStudiosAsync(
+  client: McpStdioClient,
+  sessions: SessionInfo[] = [],
+  windows: StudioWindow[] = [],
+  options: MatchStudiosOptions = {}
+): Promise<MatchedStudio[]> {
+  const studios = options.studios ?? (await listMcpStudiosAsync(client));
+  const editSessions = sessions.filter((s) => s.context === 'edit');
+  const nameCount = (name: string) =>
+    studios.filter((s) => s.placeName === name).length;
+  const canTime = windows.some((w) => w.startedAt !== undefined);
+
+  const matched = await Promise.all(
+    studios.map(async (studio): Promise<MatchedStudio> => {
+      const named = editSessions.filter(
+        (s) => s.placeName === studio.placeName
+      );
+      const uniqueByName =
+        named.length === 1 && nameCount(studio.placeName) === 1;
+      const wantProbe =
+        canTime ||
+        (!uniqueByName && (named.length > 0 || options.readPlaceIds !== false));
+      return wantProbe
+        ? {
+            ...studio,
+            ...(await _probeAsync(client, studio.studioId, windows)),
+          }
+        : { ...studio };
+    })
+  );
+
+  const claimed = new Set<string>();
+  const assign = (studio: MatchedStudio, session: SessionInfo) => {
+    claimed.add(session.sessionId);
+    studio.sessionId = session.sessionId;
+    studio.instanceId = session.instanceId;
+    studio.placeId ??= session.placeId;
+    studio.gameId ??= session.gameId;
+  };
+  const unclaimed = () => editSessions.filter((s) => !claimed.has(s.sessionId));
+
+  if (options.sessionPids) {
+    for (const studio of matched) {
+      if (studio.pid === undefined) continue;
+      const byPid = unclaimed().filter(
+        (s) => options.sessionPids!.get(s.instanceId) === studio.pid
+      );
+      if (byPid.length === 1) {
+        assign(studio, byPid[0]);
+      }
+    }
+  }
+
+  for (const studio of matched) {
+    if (studio.sessionId) continue;
+    const named = unclaimed().filter((s) => s.placeName === studio.placeName);
+    const unmatchedSameName = matched.filter(
+      (m) => !m.sessionId && m.placeName === studio.placeName
+    ).length;
+    if (named.length === 1 && unmatchedSameName === 1) {
+      assign(studio, named[0]);
+    }
+  }
+
+  for (const studio of matched) {
+    if (studio.sessionId || !studio.placeId) continue;
+    const byId = unclaimed().filter((s) => s.placeId === studio.placeId);
+    if (byId.length === 1) {
+      assign(studio, byId[0]);
+    }
+  }
+
+  for (const studio of matched) {
+    if (studio.pid !== undefined || nameCount(studio.placeName) !== 1) continue;
+    const window = windows.filter((w) =>
+      _windowShowsPlace(w.windowTitle, studio.placeName)
+    );
+    if (window.length === 1) {
+      studio.pid = window[0].pid;
+    }
+  }
+
+  return matched;
+}
+
+export function resolveStudio(
+  studios: MatchedStudio[],
+  target?: string
+): MatchedStudio {
+  if (target === undefined) {
+    if (studios.length === 1) {
+      return studios[0];
+    }
+    throw new StudioNotFoundError(
+      studios.length === 0
+        ? 'No Studio is connected to its MCP server'
+        : `${studios.length} Studios are open (${_describe(
+            studios
+          )}). Pick one with --target.`
+    );
+  }
+
+  const exact = studios.filter(
+    (s) =>
+      s.studioId === target ||
+      s.sessionId === target ||
+      s.instanceId === target ||
+      String(s.pid) === target
+  );
+  if (exact.length === 1) {
+    return exact[0];
+  }
+
+  const lowered = target.toLowerCase();
+  const loose = studios.filter(
+    (s) =>
+      s.studioId.startsWith(target) ||
+      s.sessionId?.startsWith(target) ||
+      s.instanceId?.startsWith(target) ||
+      s.placeName.toLowerCase() === lowered
+  );
+  if (loose.length === 1) {
+    return loose[0];
+  }
+
+  throw new StudioNotFoundError(
+    loose.length > 1
+      ? `'${target}' matches ${loose.length} Studios (${_describe(
+          loose
+        )}). Use a longer id.`
+      : `No Studio matches '${target}'. Open: ${_describe(studios) || 'none'}`
+  );
+}
+
+const PROBE_LUAU =
+  'return tostring(os.clock()) .. "," .. tostring(game.PlaceId) .. "," .. tostring(game.GameId)';
+
+async function _probeAsync(
+  client: McpStdioClient,
+  studioId: string,
+  windows: StudioWindow[]
+): Promise<Partial<MatchedStudio>> {
+  for (const context of ['edit', 'server', 'client'] as const) {
+    const sentAt = Date.now();
+    const run = await runLuauAsync(client, studioId, PROBE_LUAU, context);
+    const match = run.success
+      ? /^([\d.]+),(\d+),(\d+)$/.exec(run.result ?? '')
+      : null;
+    if (!match) {
+      if (run.success || !/not available/i.test(run.error ?? '')) {
+        return {};
+      }
+      continue;
+    }
+    const reading = {
+      uptimeSec: Number(match[1]),
+      observedAt: (sentAt + Date.now()) / 2,
+    };
+    const window = matchProcessByUptime(windows, reading);
+    return {
+      placeId: Number(match[2]),
+      gameId: Number(match[3]),
+      ...(window ? { pid: window.pid } : {}),
+    };
+  }
+  return {};
+}
+
+function _windowShowsPlace(title: string, placeName: string): boolean {
+  if (!placeName) {
+    return false;
+  }
+  const shown = title.replace(/ - Roblox Studio$/, '');
+  return (
+    shown === placeName ||
+    shown.endsWith(`\\${placeName}`) ||
+    shown.endsWith(`/${placeName}`) ||
+    shown.replace(/\.rbxlx?$/, '').endsWith(placeName)
+  );
+}
+
+function _describe(studios: MatchedStudio[]): string {
+  return studios
+    .map((s) => `${s.sessionId ?? s.studioId} '${s.placeName}'`)
+    .join(', ');
+}

package/src/roblox-mcp/studio-mcp-locator.test.ts

@@ -0,0 +1,186 @@
+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 {
+  findStudioMcpLaunchAsync,
+  parseContentFolder,
+} from './studio-mcp-locator.js';
+
+describe('findStudioMcpLaunchAsync', () => {
+  let localAppData: string;
+  let versionsDir: string;
+
+  beforeEach(async () => {
+    localAppData = await fs.mkdtemp(path.join(os.tmpdir(), 'studio-mcp-'));
+    versionsDir = path.join(localAppData, 'Roblox', 'Versions');
+    await fs.mkdir(versionsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(localAppData, { recursive: true, force: true });
+  });
+
+  async function makeVersionAsync(
+    name: string,
+    files: string[],
+    mtime: Date
+  ): Promise<string> {
+    const dir = path.join(versionsDir, name);
+    await fs.mkdir(path.join(dir, 'content'), { recursive: true });
+    for (const file of files) {
+      await fs.writeFile(path.join(dir, file), '');
+    }
+    await fs.utimes(dir, mtime, mtime);
+    return dir;
+  }
+
+  it('uses the version folder the registry content folder is in', async () => {
+    const dir = await makeVersionAsync(
+      'version-current',
+      ['RobloxStudioBeta.exe', 'StudioMCP.exe'],
+      new Date(2026, 0, 1)
+    );
+    await makeVersionAsync(
+      'version-newer',
+      ['RobloxStudioBeta.exe', 'StudioMCP.exe'],
+      new Date(2026, 5, 1)
+    );
+
+    const { command: found } = await findStudioMcpLaunchAsync({
+      platform: 'win32',
+      localAppData,
+      readContentFolderAsync: async () => path.join(dir, 'content') + path.sep,
+    });
+
+    expect(found).toBe(path.join(dir, 'StudioMCP.exe'));
+  });
+
+  it('skips a registry folder that only holds a lingering StudioMCP.exe', async () => {
+    const stale = await makeVersionAsync(
+      'version-stale',
+      ['StudioMCP.exe'],
+      new Date(2026, 5, 1)
+    );
+    const current = await makeVersionAsync(
+      'version-current',
+      ['RobloxStudioBeta.exe', 'StudioMCP.exe'],
+      new Date(2026, 0, 1)
+    );
+
+    const { command: found } = await findStudioMcpLaunchAsync({
+      platform: 'win32',
+      localAppData,
+      readContentFolderAsync: async () => path.join(stale, 'content'),
+    });
+
+    expect(found).toBe(path.join(current, 'StudioMCP.exe'));
+  });
+
+  it('falls back to the newest folder holding both executables', async () => {
+    await makeVersionAsync(
+      'version-old',
+      ['RobloxStudioBeta.exe', 'StudioMCP.exe'],
+      new Date(2026, 0, 1)
+    );
+    const newest = await makeVersionAsync(
+      'version-new',
+      ['RobloxStudioBeta.exe', 'StudioMCP.exe'],
+      new Date(2026, 3, 1)
+    );
+    await makeVersionAsync(
+      'version-newest-stale',
+      ['StudioMCP.exe'],
+      new Date(2026, 6, 1)
+    );
+
+    const { command: found } = await findStudioMcpLaunchAsync({
+      platform: 'win32',
+      localAppData,
+      readContentFolderAsync: async () => undefined,
+    });
+
+    expect(found).toBe(path.join(newest, 'StudioMCP.exe'));
+  });
+
+  it('says so when no folder holds both executables', async () => {
+    await makeVersionAsync(
+      'version-stale',
+      ['StudioMCP.exe'],
+      new Date(2026, 0, 1)
+    );
+
+    await expect(
+      findStudioMcpLaunchAsync({
+        platform: 'win32',
+        localAppData,
+        readContentFolderAsync: async () => undefined,
+      })
+    ).rejects.toThrow('No StudioMCP.exe found next to RobloxStudioBeta.exe');
+  });
+
+  it('finds StudioMCP in the macOS app bundle', async () => {
+    const exe = path.join(localAppData, 'StudioMCP');
+    await fs.writeFile(exe, '');
+
+    const launch = await findStudioMcpLaunchAsync({
+      platform: 'darwin',
+      macCandidates: [path.join(localAppData, 'missing'), exe],
+    });
+
+    expect(launch).toEqual({ command: exe, args: [] });
+  });
+
+  it('runs the Linux StudioMCP.exe under wine with its environment', async () => {
+    await fs.writeFile(path.join(localAppData, 'StudioMCP.exe'), '');
+    const env = { WINEPREFIX: '/wine' };
+
+    const launch = await findStudioMcpLaunchAsync({
+      platform: 'linux',
+      linuxStudioDir: localAppData,
+      linuxEnv: env,
+    });
+
+    expect(launch).toEqual({
+      command: 'wine',
+      args: [path.join(localAppData, 'StudioMCP.exe')],
+      env,
+    });
+  });
+
+  it('says so when the Linux Studio has no StudioMCP.exe', async () => {
+    await expect(
+      findStudioMcpLaunchAsync({
+        platform: 'linux',
+        linuxStudioDir: localAppData,
+        linuxEnv: {},
+      })
+    ).rejects.toThrow('No StudioMCP.exe in');
+  });
+
+  it('refuses a platform Studio does not run on', async () => {
+    await expect(
+      findStudioMcpLaunchAsync({ platform: 'freebsd' })
+    ).rejects.toThrow('not available on freebsd');
+  });
+});
+
+describe('parseContentFolder', () => {
+  it('reads the value out of reg query output', () => {
+    expect(
+      parseContentFolder(
+        '\r\nHKEY_CURRENT_USER\\Software\\Roblox\\RobloxStudio\r\n    ContentFolder    REG_SZ    C:\\Users\\a b\\AppData\\Local\\Roblox\\Versions\\version-1\\content\\\r\n\r\n'
+      )
+    ).toBe(
+      'C:\\Users\\a b\\AppData\\Local\\Roblox\\Versions\\version-1\\content\\'
+    );
+  });
+
+  it('returns undefined when the value is missing', () => {
+    expect(
+      parseContentFolder(
+        'ERROR: The system was unable to find the specified registry key or value.'
+      )
+    ).toBeUndefined();
+  });
+});

package/src/roblox-mcp/studio-mcp-locator.ts

@@ -0,0 +1,180 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { execa } from 'execa';
+
+const STUDIO_EXE = 'RobloxStudioBeta.exe';
+const MCP_EXE = 'StudioMCP.exe';
+
+export class StudioMcpUnsupportedError extends Error {}
+
+export interface StudioMcpLaunch {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
+export interface StudioMcpLocatorOptions {
+  platform?: NodeJS.Platform;
+  localAppData?: string;
+  readContentFolderAsync?: () => Promise<string | undefined>;
+  macCandidates?: string[];
+  linuxStudioDir?: string;
+  linuxEnv?: Record<string, string>;
+}
+
+export async function findStudioMcpLaunchAsync(
+  options: StudioMcpLocatorOptions = {}
+): Promise<StudioMcpLaunch> {
+  const platform = options.platform ?? process.platform;
+  if (platform === 'win32') {
+    return { command: await _findWindowsAsync(options), args: [] };
+  }
+  if (platform === 'darwin') {
+    return { command: await _findMacAsync(options), args: [] };
+  }
+  if (platform === 'linux') {
+    return _findLinuxAsync(options);
+  }
+  throw new StudioMcpUnsupportedError(
+    `Studio's MCP server is not available on ${platform}`
+  );
+}
+
+export async function readStudioContentFolderAsync(): Promise<
+  string | undefined
+> {
+  const { stdout } = await execa(
+    'reg',
+    ['query', 'HKCU\\Software\\Roblox\\RobloxStudio', '/v', 'ContentFolder'],
+    { reject: false }
+  );
+  return parseContentFolder(stdout);
+}
+
+export function parseContentFolder(regOutput: string): string | undefined {
+  const match = /ContentFolder\s+REG_(?:EXPAND_)?SZ\s+(.+)$/m.exec(regOutput);
+  return match?.[1].trim() || undefined;
+}
+
+async function _findWindowsAsync(
+  options: StudioMcpLocatorOptions
+): Promise<string> {
+  const readContentFolderAsync =
+    options.readContentFolderAsync ?? readStudioContentFolderAsync;
+  const contentFolder = await readContentFolderAsync();
+  if (contentFolder) {
+    const versionDir = path.resolve(contentFolder, '..');
+    if (await _isStudioVersionDirAsync(versionDir)) {
+      return path.join(versionDir, MCP_EXE);
+    }
+  }
+
+  const localAppData = options.localAppData ?? process.env.LOCALAPPDATA;
+  if (!localAppData) {
+    throw new Error('LOCALAPPDATA is not set, so Studio cannot be found');
+  }
+  const versionsDir = path.join(localAppData, 'Roblox', 'Versions');
+  for (const versionDir of await _listVersionDirsNewestFirstAsync(
+    versionsDir
+  )) {
+    if (await _isStudioVersionDirAsync(versionDir)) {
+      return path.join(versionDir, MCP_EXE);
+    }
+  }
+
+  throw new Error(
+    `No ${MCP_EXE} found next to ${STUDIO_EXE} under ${versionsDir}. Is Roblox Studio installed and up to date?`
+  );
+}
+
+async function _findMacAsync(
+  options: StudioMcpLocatorOptions
+): Promise<string> {
+  const candidates = options.macCandidates ?? [
+    '/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP',
+    path.join(
+      os.homedir(),
+      'Applications/RobloxStudio.app/Contents/MacOS/StudioMCP'
+    ),
+  ];
+  for (const candidate of candidates) {
+    if (await _isFileAsync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `No StudioMCP found in Roblox Studio's app bundle (${candidates.join(
+      ', '
+    )})`
+  );
+}
+
+async function _findLinuxAsync(
+  options: StudioMcpLocatorOptions
+): Promise<StudioMcpLaunch> {
+  let studioDir = options.linuxStudioDir;
+  let env = options.linuxEnv;
+  if (studioDir === undefined) {
+    const { resolveLinuxConfig } = await import('../linux/linux-config.js');
+    const { buildWineEnv } = await import('../linux/linux-wine-env.js');
+    const config = resolveLinuxConfig();
+    studioDir = config.studioDir;
+    env ??= buildWineEnv(config);
+  }
+
+  const exe = path.join(studioDir, MCP_EXE);
+  if (!(await _isFileAsync(exe))) {
+    throw new Error(
+      `No ${MCP_EXE} in ${studioDir}. Run "studio-bridge linux setup" with a Studio that ships it.`
+    );
+  }
+  return { command: 'wine', args: [exe], env };
+}
+
+async function _isStudioVersionDirAsync(dir: string): Promise<boolean> {
+  const [hasStudio, hasMcp] = await Promise.all([
+    _isFileAsync(path.join(dir, STUDIO_EXE)),
+    _isFileAsync(path.join(dir, MCP_EXE)),
+  ]);
+  return hasStudio && hasMcp;
+}
+
+async function _listVersionDirsNewestFirstAsync(
+  versionsDir: string
+): Promise<string[]> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(versionsDir);
+  } catch {
+    return [];
+  }
+
+  const dirs = await Promise.all(
+    entries
+      .filter((entry) => entry.startsWith('version-'))
+      .map(async (entry) => {
+        const dir = path.join(versionsDir, entry);
+        try {
+          const stat = await fs.stat(dir);
+          return stat.isDirectory()
+            ? { dir, mtimeMs: stat.mtimeMs }
+            : undefined;
+        } catch {
+          return undefined;
+        }
+      })
+  );
+  return dirs
+    .filter((d): d is { dir: string; mtimeMs: number } => d !== undefined)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .map((d) => d.dir);
+}
+
+async function _isFileAsync(file: string): Promise<boolean> {
+  try {
+    return (await fs.stat(file)).isFile();
+  } catch {
+    return false;
+  }
+}