@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/docker/docker-delegator.ts

@@ -0,0 +1,240 @@
+/**
+ * Transparent Docker delegation for `process run` on Linux environments
+ * without Wine. Detects when Docker is available and delegates the entire
+ * command to the pre-built container image.
+ */
+
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { execa } from 'execa';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { validateCookieAsync } from '@quenty/nevermore-cli-helpers';
+import type { ExecuteScriptOptions } from '../cli/script-executor.js';
+
+const DOCKER_IMAGE_BASE = 'ghcr.io/quenty/nevermore-studio-linux';
+const CHECK_TIMEOUT_MS = 5_000;
+
+/**
+ * Resolves the Docker image to use. Defaults to :latest, but can be
+ * overridden with STUDIO_BRIDGE_DOCKER_TAG (e.g. "canary-feat-my-branch").
+ */
+function resolveDockerImage(): string {
+  const tag = process.env.STUDIO_BRIDGE_DOCKER_TAG ?? 'latest';
+  return `${DOCKER_IMAGE_BASE}:${tag}`;
+}
+
+/**
+ * Returns true if the current environment should delegate to Docker
+ * (Linux without Wine, but with Docker available).
+ */
+export async function shouldDelegateToDockerAsync(): Promise<boolean> {
+  if (os.platform() !== 'linux') {
+    return false;
+  }
+
+  // Check if Wine is available locally
+  try {
+    await execa('wine', ['--version'], { timeout: CHECK_TIMEOUT_MS });
+    return false; // Wine works, use local path
+  } catch {
+    // Wine not available, check Docker
+  }
+
+  try {
+    await execa('docker', ['info'], {
+      timeout: CHECK_TIMEOUT_MS,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delegates script execution to the Docker container. Streams stdio
+ * transparently and propagates the exit code. Does not return — calls
+ * process.exit().
+ */
+export async function delegateToDockerAsync(
+  options: ExecuteScriptOptions
+): Promise<never> {
+  const cookie = process.env.ROBLOSECURITY;
+  if (!cookie) {
+    OutputHelper.error(
+      'ROBLOSECURITY environment variable is required for Docker delegation.'
+    );
+    process.exit(1);
+  }
+
+  const validation = await validateCookieAsync(cookie);
+  if (!validation.valid) {
+    if (validation.reason === 'network_error') {
+      OutputHelper.warn(
+        'Could not validate ROBLOSECURITY cookie (network error). Continuing anyway.'
+      );
+    } else {
+      OutputHelper.error(
+        `ROBLOSECURITY cookie is invalid or expired (HTTP ${validation.status}). Update the cookie and try again.`
+      );
+      process.exit(1);
+    }
+  }
+
+  const image = resolveDockerImage();
+  await ensureImageAsync(image);
+
+  const cwd = process.cwd();
+  const args = await buildDockerRunArgsAsync(options, cwd, cookie, image);
+
+  OutputHelper.verbose(`[StudioBridge] docker run args: ${args.join(' ')}`);
+
+  // Pass ROBLOSECURITY through the docker process's env (referenced by name in
+  // the args via `-e ROBLOSECURITY`) rather than baking the value into argv,
+  // where it would be visible via `ps`.
+  const result = await execa('docker', args, {
+    stdio: 'inherit',
+    reject: false,
+    env: { ...process.env, ROBLOSECURITY: cookie },
+  });
+
+  process.exit(result.exitCode ?? 1);
+}
+
+const STALE_DAYS = 7;
+
+/**
+ * Ensures the Docker image is available locally, pulling if needed.
+ * Warns if the local image is older than STALE_DAYS.
+ */
+async function ensureImageAsync(image: string): Promise<void> {
+  try {
+    const { stdout } = await execa('docker', [
+      'image',
+      'inspect',
+      '--format',
+      '{{.Created}}',
+      image,
+    ]);
+    const created = new Date(stdout.trim());
+    const ageDays = (Date.now() - created.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageDays > STALE_DAYS) {
+      OutputHelper.warn(
+        `Docker image is ${Math.floor(
+          ageDays
+        )} days old. Run 'docker pull ${image}' to update.`
+      );
+    }
+  } catch {
+    OutputHelper.info(`Pulling ${image}...`);
+    await execa('docker', ['pull', image], { stdio: 'inherit' });
+  }
+}
+
+/**
+ * Builds the docker run argument array, writing inline script content
+ * to a temp file if needed.
+ *
+ * The cookie value is NOT placed in the returned argv. Instead `-e
+ * ROBLOSECURITY` (no value) is used so docker reads the value from its own
+ * environment at spawn time, keeping the cookie out of `ps` output. The
+ * caller is responsible for setting ROBLOSECURITY in the spawned docker
+ * process's env. The `cookie` parameter is retained only for validation in
+ * `delegateToDockerAsync`.
+ */
+export async function buildDockerRunArgsAsync(
+  options: ExecuteScriptOptions,
+  cwd: string,
+  _cookie: string,
+  image: string = `${DOCKER_IMAGE_BASE}:latest`
+): Promise<string[]> {
+  const { scriptContent, placePath, timeoutMs, verbose } = options;
+
+  // Write script to a temp file in CWD to avoid shell escaping issues
+  let tmpFile: string | undefined;
+  let scriptFilePath: string;
+
+  if (options.filePath) {
+    scriptFilePath = path.resolve(options.filePath);
+    // Validate file is within CWD
+    if (!scriptFilePath.startsWith(cwd)) {
+      OutputHelper.error(
+        `Cannot delegate: file ${scriptFilePath} is outside working directory ${cwd}`
+      );
+      process.exit(1);
+    }
+  } else {
+    tmpFile = path.join(cwd, `.studio-bridge-tmp-${process.pid}.lua`);
+    await fs.writeFile(tmpFile, scriptContent, 'utf-8');
+    scriptFilePath = tmpFile;
+
+    // Register cleanup
+    const cleanup = async () => {
+      try {
+        await fs.unlink(tmpFile!);
+      } catch {
+        // Ignore
+      }
+    };
+    process.on('exit', () => {
+      void cleanup();
+    });
+    process.on('SIGINT', () => {
+      void cleanup();
+    });
+    process.on('SIGTERM', () => {
+      void cleanup();
+    });
+  }
+
+  const innerArgs = [
+    'studio-bridge',
+    'linux',
+    'inject-credentials',
+    '&&',
+    'studio-bridge',
+    'process',
+    'run',
+    '--file',
+    scriptFilePath,
+    '--timeout',
+    String(timeoutMs),
+  ];
+
+  if (placePath) {
+    const resolvedPlace = path.resolve(placePath);
+    if (!resolvedPlace.startsWith(cwd)) {
+      OutputHelper.error(
+        `Cannot delegate: place file ${resolvedPlace} is outside working directory ${cwd}`
+      );
+      process.exit(1);
+    }
+    innerArgs.push('--place', resolvedPlace);
+  }
+
+  if (verbose) {
+    innerArgs.push('--verbose');
+  }
+
+  // Docker-level timeout: script timeout + 60s buffer for auth/setup
+  const dockerTimeoutSec = Math.ceil((timeoutMs + 60_000) / 1000);
+
+  return [
+    'run',
+    '--rm',
+    '--init',
+    '--stop-timeout',
+    String(dockerTimeoutSec),
+    '-e',
+    'ROBLOSECURITY',
+    '-v',
+    `${cwd}:${cwd}`,
+    '-w',
+    cwd,
+    image,
+    'bash',
+    '-c',
+    innerArgs.join(' '),
+  ];
+}

package/src/index.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import * as barrel from './index.js';
+
+describe('index barrel exports', () => {
+  it('exports existing StudioBridge class', () => {
+    expect(barrel.StudioBridge).toBeDefined();
+  });
+
+  it('exports BridgeConnection class', () => {
+    expect(barrel.BridgeConnection).toBeDefined();
+  });
+
+  it('exports BridgeSession class', () => {
+    expect(barrel.BridgeSession).toBeDefined();
+  });
+
+  it('exports error classes', () => {
+    expect(barrel.SessionNotFoundError).toBeDefined();
+    expect(barrel.ActionTimeoutError).toBeDefined();
+    expect(barrel.SessionDisconnectedError).toBeDefined();
+    expect(barrel.CapabilityNotSupportedError).toBeDefined();
+    expect(barrel.ContextNotFoundError).toBeDefined();
+    expect(barrel.HostUnreachableError).toBeDefined();
+  });
+
+  it('exports protocol encoding/decoding functions', () => {
+    expect(barrel.encodeMessage).toBeDefined();
+    expect(barrel.decodePluginMessage).toBeDefined();
+    expect(barrel.decodeServerMessage).toBeDefined();
+  });
+
+  it('exports studio process utilities', () => {
+    expect(barrel.findStudioPathAsync).toBeDefined();
+    expect(barrel.findPluginsFolder).toBeDefined();
+    expect(barrel.launchStudioAsync).toBeDefined();
+    expect(barrel.injectPluginAsync).toBeDefined();
+  });
+
+  it('exports plugin discovery', () => {
+    expect(barrel.isPersistentPluginInstalled).toBeDefined();
+  });
+
+  it('exports command handler functions', () => {
+    expect(barrel.listSessionsHandlerAsync).toBeDefined();
+    expect(barrel.serveHandlerAsync).toBeDefined();
+    expect(barrel.installPluginHandlerAsync).toBeDefined();
+    expect(barrel.uninstallPluginHandlerAsync).toBeDefined();
+    expect(barrel.queryStateHandlerAsync).toBeDefined();
+    expect(barrel.queryLogsHandlerAsync).toBeDefined();
+    expect(barrel.captureScreenshotHandlerAsync).toBeDefined();
+    expect(barrel.queryDataModelHandlerAsync).toBeDefined();
+    expect(barrel.execHandlerAsync).toBeDefined();
+    expect(barrel.runHandlerAsync).toBeDefined();
+    expect(barrel.launchHandlerAsync).toBeDefined();
+    expect(barrel.connectHandlerAsync).toBeDefined();
+    expect(barrel.disconnectHandler).toBeDefined();
+  });
+});

package/src/index.ts

@@ -19,6 +19,44 @@ export type {
 } from './server/studio-bridge-server.js';
 export type { OutputLevel } from './server/web-socket-protocol.js';
 
+// Bridge network layer (persistent sessions)
+export {
+  BridgeConnection,
+  BridgeSession,
+  SessionNotFoundError,
+  ActionTimeoutError,
+  SessionDisconnectedError,
+  CapabilityNotSupportedError,
+  ContextNotFoundError,
+  HostUnreachableError,
+} from './bridge/index.js';
+
+export type {
+  BridgeConnectionOptions,
+  SessionInfo,
+  InstanceInfo,
+  SessionContext,
+  SessionOrigin,
+  ExecResult,
+  StateResult,
+  ScreenshotResult,
+  LogsResult,
+  DataModelResult,
+  LogEntry,
+  LogOptions,
+  QueryDataModelOptions,
+  LogFollowOptions,
+} from './bridge/index.js';
+
+// Protocol types
+export type {
+  Capability,
+  StudioState,
+  DataModelInstance,
+  ErrorCode,
+  SerializedValue,
+} from './server/web-socket-protocol.js';
+
 // Lower-level exports for advanced usage / testing
 export {
   findStudioPathAsync,
@@ -26,17 +64,80 @@ export {
   launchStudioAsync,
 } from './process/studio-process-manager.js';
 export { injectPluginAsync } from './plugin/plugin-injector.js';
+export { isPersistentPluginInstalled } from './plugin/plugin-discovery.js';
 export {
   encodeMessage,
   decodePluginMessage,
+  decodeServerMessage,
 } from './server/web-socket-protocol.js';
 export type {
   PluginMessage,
   ServerMessage,
-  HelloMessage,
-  OutputMessage,
   ScriptCompleteMessage,
-  WelcomeMessage,
   ExecuteMessage,
   ShutdownMessage,
+  // plugin -> server
+  RegisterMessage,
+  StateResultMessage,
+  ScreenshotResultMessage,
+  DataModelResultMessage,
+  LogsResultMessage,
+  StateChangeMessage,
+  HeartbeatMessage,
+  PluginErrorMessage,
+  // server -> plugin
+  QueryStateMessage,
+  CaptureScreenshotMessage,
+  QueryDataModelMessage,
+  QueryLogsMessage,
+  ServerErrorMessage,
+  // dynamic action registration
+  RegisterActionMessage,
+  RegisterActionResultMessage,
 } from './server/web-socket-protocol.js';
+
+// Command handlers
+export {
+  listSessionsHandlerAsync,
+  serveHandlerAsync,
+  installPluginHandlerAsync,
+  uninstallPluginHandlerAsync,
+  queryStateHandlerAsync,
+  queryLogsHandlerAsync,
+  captureScreenshotHandlerAsync,
+  queryDataModelHandlerAsync,
+  execHandlerAsync,
+  runHandlerAsync,
+  launchHandlerAsync,
+  connectHandlerAsync,
+  disconnectHandler,
+} from './commands/index.js';
+
+export type {
+  SessionsResult,
+  ServeOptions,
+  ServeResult,
+  InstallPluginResult,
+  UninstallPluginResult,
+  QueryOptions,
+  QueryResult,
+  DataModelNode,
+  RunOptions,
+  RunResult,
+  LaunchOptions,
+  LaunchResult,
+  ConnectOptions,
+  ConnectResult,
+  DisconnectResult,
+} from './commands/index.js';
+
+// Command option/result types that conflict with bridge types are aliased
+export type {
+  StateResult as CommandStateResult,
+  LogsResult as CommandLogsResult,
+  LogsOptions as CommandLogsOptions,
+  ScreenshotResult as CommandScreenshotResult,
+  ScreenshotOptions as CommandScreenshotOptions,
+  ExecOptions as CommandExecOptions,
+  ExecResult as CommandExecResult,
+} from './commands/index.js';

package/src/linux/README.md

@@ -0,0 +1,130 @@
+# Linux/Wine Support for studio-bridge
+
+Run Roblox Studio headlessly on Linux via Wine 11, Xvfb, and Mesa llvmpipe. This enables AI agents and CI pipelines to launch Studio in devcontainers and GitHub Actions without a physical display or GPU.
+
+## Prerequisites
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Wine | 11.0+ | Windows compatibility layer |
+| Xvfb | any | Virtual X11 framebuffer |
+| openbox | any | Window manager (required for modal dialogs) |
+| x86_64-w64-mingw32-gcc | any | Cross-compiler for write-cred.exe |
+| unzip | any | Extract Studio packages |
+
+All can be installed via `studio-bridge linux setup --install-deps` on Debian/Ubuntu.
+
+## Quick Start
+
+```bash
+# One-time setup: install deps, download Studio, patch shaders, write FFlags
+studio-bridge linux setup --install-deps
+
+# Inject authentication (reads $ROBLOSECURITY env var)
+studio-bridge linux inject-credentials
+
+# Verify everything is ready
+studio-bridge linux status
+
+# Launch Studio and execute code through the bridge
+studio-bridge exec 'print("Hello from Linux!")'
+```
+
+## Architecture
+
+```
+linux-config.ts             Path resolution + constants (STUDIO_DIR, WINEPREFIX, DISPLAY)
+linux-wine-env.ts           Wine env vars (DISPLAY, Mesa overrides, WINEDEBUG)
+linux-prerequisites.ts      Check/install system deps
+linux-display-manager.ts    Start/stop Xvfb + openbox
+linux-version-resolver.ts   Fetch Studio version from CDN
+linux-studio-installer.ts   Download 34 zip packages, extract, write AppSettings.xml
+linux-shader-patcher.ts     Binary-patch #version 150 → #version 420
+linux-fflags.ts             Write ClientAppSettings.json (D3D11 renderer flags)
+linux-credential-writer.ts  Compile write-cred.c, inject 3 credentials via Wine
+write-cred.c                Bundled C source for Windows Credential Manager writes
+```
+
+The process manager (`src/process/studio-process-manager.ts`) uses lazy `import()` for all Linux modules — zero overhead on Windows/macOS.
+
+## How It Works
+
+### Rendering: D3D11 via WineD3D
+
+Studio must use the D3D11 renderer, not OpenGL. Wine's OpenGL/EGL backend has a bug where `wglSwapBuffers` always targets the same EGL surface regardless of HWND, which breaks DockWidget rendering (Explorer, Properties, Toolbox all stay black).
+
+WineD3D translates D3D11 calls to OpenGL internally but manages per-window swapchains correctly. The FFlags force this path:
+
+```json
+{
+  "FFlagDebugGraphicsPreferD3D11": true,
+  "FFlagDebugGraphicsDisableVulkan": true,
+  "FFlagDebugGraphicsDisableD3D11FL10": true,
+  "FFlagDebugGraphicsDisableOpenGL": true
+}
+```
+
+### Shader Patching
+
+Studio's GLSL shader pack declares `#version 150` but uses `unpackHalf2x16()`, which requires GLSL 4.20+. NVIDIA/AMD drivers are lenient about this; Mesa's llvmpipe is strict and rejects the shaders.
+
+The fix is a binary patch: replace all `#version 150` with `#version 420` in `shaders/shaders_glsl3.pack`. Both strings are exactly 12 bytes, so the patch is safe and in-place.
+
+### Authentication
+
+Studio expects three entries in Windows Credential Manager:
+
+1. `https://www.roblox.com:RobloxStudioAuthuserid` → numeric user ID
+2. `https://www.roblox.com:RobloxStudioAuthCookies` → `.ROBLOSECURITY` (cookie name)
+3. `https://www.roblox.com:RobloxStudioAuth.ROBLOSECURITY{userId}` → the cookie value
+
+The `linux inject-credentials` command:
+1. Resolves the cookie via `getRobloxCookieAsync()` (env var → Wine cred store → interactive prompt)
+2. Fetches the user ID from `users.roblox.com/v1/users/authenticated`
+3. Compiles `write-cred.c` with MinGW (one-time)
+4. Runs `wine write-cred.exe` three times to inject all entries
+
+On first launch, Studio exchanges the cookie for OAuth2 tokens. Subsequent launches use the refresh token, so the original cookie can expire.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STUDIO_DIR` | `~/roblox-studio` | Studio installation directory |
+| `WINEPREFIX` | `~/.wine` | Wine prefix directory |
+| `DISPLAY` | `:99` | X11 display number |
+| `ROBLOSECURITY` | — | .ROBLOSECURITY cookie for auth |
+
+## CLI Commands
+
+### `studio-bridge linux setup`
+
+Install Wine dependencies and Roblox Studio.
+
+| Flag | Description |
+|------|-------------|
+| `--install-deps` | Install system deps via apt-get (requires sudo) |
+| `--version <hash>` | Studio version hash (default: latest from CDN) |
+| `--studio-dir <path>` | Override installation directory |
+| `--skip-shaders` | Skip shader patching |
+| `--force` | Force reinstall even if same version exists |
+
+### `studio-bridge linux inject-credentials`
+
+Inject .ROBLOSECURITY cookie into Wine Credential Manager.
+
+| Flag | Description |
+|------|-------------|
+| `--cookie <value>` | Explicit cookie value |
+| `--cookie -` | Read cookie from stdin |
+| _(none)_ | Falls back to `$ROBLOSECURITY` or interactive prompt |
+
+### `studio-bridge linux status`
+
+Read-only health check. Reports on prerequisites, display, Studio installation, FFlags, shaders, and authentication. Exits with code 1 if any issues found.
+
+## Resource Requirements
+
+- **Disk**: ~813MB for Studio installation + ~450MB download cache
+- **RAM**: ~450MB–800MB at runtime. 16GB recommended for the host; 8GB may OOM.
+- **CPU**: No GPU required — Mesa llvmpipe does software rendering.

package/src/linux/index.ts

@@ -0,0 +1,25 @@
+export {
+  resolveLinuxConfig,
+  ROBLOX_CDN_BASE,
+  ROBLOX_USERS_API,
+  STUDIO_PACKAGES,
+} from './linux-config.js';
+export type { LinuxStudioConfig } from './linux-config.js';
+export { buildWineEnv } from './linux-wine-env.js';
+export {
+  checkPrerequisites,
+  allPrerequisitesMet,
+  installDependenciesAsync,
+} from './linux-prerequisites.js';
+export {
+  ensureDisplayAsync,
+  ensureWindowManagerAsync,
+  isXvfbRunning,
+  isOpenboxRunning,
+} from './linux-display-manager.js';
+export { resolveStudioVersionAsync } from './linux-version-resolver.js';
+export { installStudioAsync } from './linux-studio-installer.js';
+export { patchShadersAsync } from './linux-shader-patcher.js';
+export { writeFflagsAsync } from './linux-fflags.js';
+export { injectCredentialsAsync } from './linux-credential-writer.js';
+export { launchStudioLinuxAsync } from './linux-studio-launcher.js';

package/src/linux/linux-config.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolveLinuxConfig, STUDIO_PACKAGES } from './linux-config.js';
+
+describe('resolveLinuxConfig', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns HOME-based defaults when no env vars set', () => {
+    delete process.env.STUDIO_DIR;
+    delete process.env.WINEPREFIX;
+    delete process.env.DISPLAY;
+    process.env.HOME = '/home/testuser';
+
+    const config = resolveLinuxConfig();
+    expect(config.studioDir).toContain('roblox-studio');
+    expect(config.winePrefix).toContain('.wine');
+    expect(config.display).toBe(':99');
+    expect(config.studioExe).toMatch(/RobloxStudioBeta\.exe$/);
+    expect(config.clientSettingsPath).toContain('ClientAppSettings.json');
+    expect(config.pluginsDir).toMatch(/Plugins$/);
+    expect(config.writeCredExe).toMatch(/write-cred\.exe$/);
+  });
+
+  it('respects STUDIO_DIR env var', () => {
+    process.env.STUDIO_DIR = '/opt/studio';
+
+    const config = resolveLinuxConfig();
+    expect(config.studioDir).toBe('/opt/studio');
+    expect(config.studioExe).toBe('/opt/studio/RobloxStudioBeta.exe');
+    expect(config.pluginsDir).toBe('/opt/studio/Plugins');
+  });
+
+  it('respects WINEPREFIX env var', () => {
+    process.env.WINEPREFIX = '/tmp/test-wine';
+
+    const config = resolveLinuxConfig();
+    expect(config.winePrefix).toBe('/tmp/test-wine');
+  });
+
+  it('respects DISPLAY env var', () => {
+    process.env.DISPLAY = ':42';
+
+    const config = resolveLinuxConfig();
+    expect(config.display).toBe(':42');
+  });
+});
+
+describe('STUDIO_PACKAGES', () => {
+  it('has 34 package entries', () => {
+    expect(Object.keys(STUDIO_PACKAGES)).toHaveLength(34);
+  });
+
+  it('includes critical packages', () => {
+    expect(STUDIO_PACKAGES).toHaveProperty('RobloxStudio.zip');
+    expect(STUDIO_PACKAGES).toHaveProperty('shaders.zip');
+    expect(STUDIO_PACKAGES).toHaveProperty('Libraries.zip');
+    expect(STUDIO_PACKAGES).toHaveProperty('content-fonts.zip');
+  });
+
+  it('maps shaders.zip to shaders/ directory', () => {
+    expect(STUDIO_PACKAGES['shaders.zip']).toBe('shaders/');
+  });
+});