@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/linux/linux-env-guard.ts

@@ -0,0 +1,38 @@
+/**
+ * Environment guard for `linux *` subcommands.
+ *
+ * These commands require Wine and related tools that are only available inside
+ * the Docker image or a properly configured Linux box.  This guard lets them
+ * fail early with a helpful message instead of crashing mid-way.
+ */
+
+import * as os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Checks if the current environment can run linux/* commands.
+ * Returns an error message if not, or undefined if OK.
+ */
+export async function checkLinuxEnvironmentAsync(): Promise<
+  string | undefined
+> {
+  if (os.platform() !== 'linux') {
+    return "linux commands require a Linux environment. On Windows/macOS, Studio runs natively — use 'studio-bridge process run' instead.";
+  }
+
+  try {
+    await execFileAsync('which', ['wine']);
+  } catch {
+    return (
+      'Wine is not installed. These commands require Wine and related tools.\n\n' +
+      "To run scripts, use 'studio-bridge process run' which auto-delegates to Docker.\n" +
+      'To set up a full Wine environment, run inside the Docker image:\n' +
+      '  docker run --rm -it ghcr.io/quenty/nevermore-studio-linux:latest bash'
+    );
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,78 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { writeFflagsAsync } from './linux-fflags.js';
+import type { LinuxStudioConfig } from './linux-config.js';
+
+describe('writeFflagsAsync', () => {
+  let tmpDir: string;
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  function makeConfig(): LinuxStudioConfig {
+    const clientSettingsPath = path.join(
+      tmpDir,
+      'ClientSettings',
+      'ClientAppSettings.json'
+    );
+    return {
+      studioDir: tmpDir,
+      winePrefix: '/tmp/fake-wine',
+      display: ':99',
+      studioExe: path.join(tmpDir, 'RobloxStudioBeta.exe'),
+      clientSettingsPath,
+      shadersDir: path.join(tmpDir, 'shaders'),
+      pluginsDir: path.join(tmpDir, 'Plugins'),
+      writeCredExe: path.join(tmpDir, 'write-cred.exe'),
+    };
+  }
+
+  it('writes valid JSON with all 5 required FFlags', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fflags-test-'));
+    const config = makeConfig();
+
+    await writeFflagsAsync(config);
+
+    const content = JSON.parse(
+      await fs.readFile(config.clientSettingsPath, 'utf-8')
+    );
+    expect(content.FFlagDebugGraphicsPreferD3D11).toBe(true);
+    expect(content.FFlagDebugGraphicsDisableVulkan).toBe(true);
+    expect(content.FFlagDebugGraphicsDisableD3D11FL10).toBe(true);
+    expect(content.FFlagDebugGraphicsDisableOpenGL).toBe(true);
+    expect(content.FIntStudioLowMemoryThresholdPercentage).toBe(0);
+  });
+
+  it('creates parent directories', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fflags-test-'));
+    const config = makeConfig();
+
+    // Directory shouldn't exist yet
+    await expect(
+      fs.access(path.dirname(config.clientSettingsPath))
+    ).rejects.toThrow();
+
+    await writeFflagsAsync(config);
+
+    // Now it should
+    await fs.access(path.dirname(config.clientSettingsPath));
+  });
+
+  it('merges extra flags without dropping defaults', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fflags-test-'));
+    const config = makeConfig();
+
+    await writeFflagsAsync(config, { FIntCustomFlag: 42 });
+
+    const content = JSON.parse(
+      await fs.readFile(config.clientSettingsPath, 'utf-8')
+    );
+    expect(content.FIntCustomFlag).toBe(42);
+    expect(content.FFlagDebugGraphicsPreferD3D11).toBe(true);
+  });
+});

package/src/linux/linux-fflags.ts

@@ -0,0 +1,48 @@
+/**
+ * Write the FFlags required for Studio to render correctly under Wine/Mesa.
+ *
+ * Key flags:
+ * - FFlagDebugGraphicsPreferD3D11: Use D3D11 via WineD3D (avoids Wine's
+ *   EGL swapchain bug that breaks DockWidgets in OpenGL mode)
+ * - FFlagDebugGraphicsDisableVulkan/OpenGL/D3D11FL10: Prevent fallback
+ *   to renderers that don't work under Wine
+ * - FIntStudioLowMemoryThresholdPercentage: Disable OOM warning dialog
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { LinuxStudioConfig } from './linux-config.js';
+
+const DEFAULT_FFLAGS: Record<string, boolean | number> = {
+  FFlagDebugGraphicsPreferD3D11: true,
+  FFlagDebugGraphicsDisableVulkan: true,
+  FFlagDebugGraphicsDisableD3D11FL10: true,
+  FFlagDebugGraphicsDisableOpenGL: true,
+  FIntStudioLowMemoryThresholdPercentage: 0,
+};
+
+/**
+ * Write ClientAppSettings.json with the FFlags needed for Wine rendering.
+ * Merges with any existing flags to avoid clobbering user customizations.
+ */
+export async function writeFflagsAsync(
+  config: LinuxStudioConfig,
+  extraFlags?: Record<string, boolean | number>
+): Promise<void> {
+  const settingsDir = path.dirname(config.clientSettingsPath);
+  await fs.mkdir(settingsDir, { recursive: true });
+
+  // Merge defaults + extras
+  const flags = { ...DEFAULT_FFLAGS, ...extraFlags };
+
+  await fs.writeFile(
+    config.clientSettingsPath,
+    JSON.stringify(flags, null, 2) + '\n',
+    'utf-8'
+  );
+
+  OutputHelper.verbose(
+    `Wrote ${Object.keys(flags).length} FFlags to ${config.clientSettingsPath}`
+  );
+}

package/src/linux/linux-prerequisites.ts

@@ -0,0 +1,152 @@
+/**
+ * Check system prerequisites for running Studio under Wine on Linux.
+ */
+
+import { execSync } from 'child_process';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+
+export interface PrerequisiteResult {
+  name: string;
+  available: boolean;
+  version?: string;
+  hint?: string;
+}
+
+const PREREQUISITES: Array<{
+  name: string;
+  command: string;
+  hint: string;
+}> = [
+  {
+    name: 'wine',
+    command: 'wine --version',
+    hint: 'Install Wine 11+: https://wiki.winehq.org/Download',
+  },
+  {
+    name: 'Xvfb',
+    command: 'Xvfb -help 2>&1 | head -1',
+    hint: 'apt-get install xvfb',
+  },
+  {
+    name: 'openbox',
+    command: 'openbox --version',
+    hint: 'apt-get install openbox',
+  },
+  {
+    name: 'x86_64-w64-mingw32-gcc',
+    command: 'x86_64-w64-mingw32-gcc --version',
+    hint: 'apt-get install gcc-mingw-w64-x86-64',
+  },
+  {
+    name: 'unzip',
+    command: 'unzip -v 2>&1 | head -1',
+    hint: 'apt-get install unzip',
+  },
+];
+
+/**
+ * Check all required tools are present. Returns an array of results
+ * including version strings where parseable.
+ */
+export function checkPrerequisites(): PrerequisiteResult[] {
+  return PREREQUISITES.map(({ name, command, hint }) => {
+    try {
+      const output = execSync(command, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+
+      const version = extractVersion(output);
+      return { name, available: true, version };
+    } catch {
+      return { name, available: false, hint };
+    }
+  });
+}
+
+/**
+ * Returns true if all prerequisites are satisfied.
+ */
+export function allPrerequisitesMet(): boolean {
+  return checkPrerequisites().every((r) => r.available);
+}
+
+function extractVersion(output: string): string | undefined {
+  const match = output.match(/(\d+\.\d+[\w.-]*)/);
+  return match?.[1];
+}
+
+/**
+ * Install missing system dependencies. Requires sudo.
+ * Only runs on Debian/Ubuntu (apt-get).
+ */
+export async function installDependenciesAsync(): Promise<void> {
+  const { execa } = await import('execa');
+
+  await execa('sudo', ['dpkg', '--add-architecture', 'i386'], {
+    stdio: 'inherit',
+  });
+
+  // Try WineHQ repo first for latest builds, fall back to distro packages
+  let useWineHQ = false;
+  try {
+    await execa('sudo', ['mkdir', '-pm755', '/etc/apt/keyrings'], {
+      stdio: 'inherit',
+    });
+    await execa(
+      'sudo',
+      [
+        'curl',
+        '-sL',
+        'https://dl.winehq.org/wine-builds/winehq.key',
+        '-o',
+        '/etc/apt/keyrings/winehq-archive.key',
+      ],
+      { stdio: 'inherit' }
+    );
+
+    let codename = 'noble';
+    try {
+      codename = execSync('lsb_release -cs', { encoding: 'utf-8' }).trim();
+    } catch {
+      // Fall back to noble (Ubuntu 24.04)
+    }
+
+    await execa(
+      'sudo',
+      [
+        'curl',
+        '-sfL',
+        `https://dl.winehq.org/wine-builds/ubuntu/dists/${codename}/winehq-${codename}.sources`,
+        '-o',
+        `/etc/apt/sources.list.d/winehq-${codename}.sources`,
+      ],
+      { stdio: 'inherit' }
+    );
+    useWineHQ = true;
+  } catch {
+    OutputHelper.warn(
+      'WineHQ repo not available for this distro, using system packages'
+    );
+  }
+
+  await execa('sudo', ['apt-get', 'update'], { stdio: 'inherit' });
+
+  const winePackage = useWineHQ ? 'winehq-stable' : 'wine';
+  await execa(
+    'sudo',
+    [
+      'apt-get',
+      'install',
+      '-y',
+      winePackage,
+      'xvfb',
+      'mesa-utils',
+      'openbox',
+      'gcc-mingw-w64-x86-64',
+      'unzip',
+    ],
+    { stdio: 'inherit' }
+  );
+}

package/src/linux/linux-shader-patcher.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { patchShadersAsync } from './linux-shader-patcher.js';
+import type { LinuxStudioConfig } from './linux-config.js';
+
+describe('patchShadersAsync', () => {
+  let tmpDir: string;
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  function makeConfig(): LinuxStudioConfig {
+    return {
+      studioDir: tmpDir,
+      winePrefix: '/tmp/fake-wine',
+      display: ':99',
+      studioExe: path.join(tmpDir, 'RobloxStudioBeta.exe'),
+      clientSettingsPath: path.join(
+        tmpDir,
+        'ClientSettings',
+        'ClientAppSettings.json'
+      ),
+      shadersDir: path.join(tmpDir, 'shaders'),
+      pluginsDir: path.join(tmpDir, 'Plugins'),
+      writeCredExe: path.join(tmpDir, 'write-cred.exe'),
+    };
+  }
+
+  async function writeFakeShaderPack(content: Buffer): Promise<void> {
+    const dir = path.join(tmpDir, 'shaders');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'shaders_glsl3.pack'), content);
+  }
+
+  it('replaces #version 150 with #version 420', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'shader-test-'));
+    const config = makeConfig();
+
+    // Create a fake shader pack with two occurrences
+    const data = Buffer.from('header#version 150middle#version 150tail');
+    await writeFakeShaderPack(data);
+
+    const count = await patchShadersAsync(config);
+    expect(count).toBe(2);
+
+    const patched = await fs.readFile(
+      path.join(config.shadersDir, 'shaders_glsl3.pack')
+    );
+    expect(patched.toString()).toBe('header#version 420middle#version 420tail');
+  });
+
+  it('returns 0 on second run (idempotent)', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'shader-test-'));
+    const config = makeConfig();
+
+    await writeFakeShaderPack(Buffer.from('data#version 150end'));
+
+    await patchShadersAsync(config);
+    const count = await patchShadersAsync(config);
+    expect(count).toBe(0);
+  });
+
+  it('throws if shader pack not found', async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'shader-test-'));
+    const config = makeConfig();
+
+    await expect(patchShadersAsync(config)).rejects.toThrow(
+      'Shader pack not found'
+    );
+  });
+});

package/src/linux/linux-shader-patcher.ts

@@ -0,0 +1,56 @@
+/**
+ * Binary-patch GLSL shaders from #version 150 to #version 420.
+ *
+ * Mesa's llvmpipe strictly enforces the GLSL spec — shaders using
+ * unpackHalf2x16() (GLSL 4.20+) but declaring #version 150 are rejected.
+ * Both version strings are exactly 12 bytes, so the patch is a safe
+ * in-place replacement.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { LinuxStudioConfig } from './linux-config.js';
+
+const SHADER_PACK_NAME = 'shaders_glsl3.pack';
+const OLD_VERSION = Buffer.from('#version 150');
+const NEW_VERSION = Buffer.from('#version 420');
+
+/**
+ * Patch the GLSL3 shader pack in-place, replacing all occurrences of
+ * `#version 150` with `#version 420`.
+ *
+ * Returns the number of replacements made.
+ */
+export async function patchShadersAsync(
+  config: LinuxStudioConfig
+): Promise<number> {
+  const shaderPath = path.join(config.shadersDir, SHADER_PACK_NAME);
+
+  let data: Buffer;
+  try {
+    data = await fs.readFile(shaderPath);
+  } catch {
+    throw new Error(`Shader pack not found: ${shaderPath}`);
+  }
+
+  let count = 0;
+  let offset = 0;
+
+  while (true) {
+    const idx = data.indexOf(OLD_VERSION, offset);
+    if (idx === -1) break;
+    NEW_VERSION.copy(data, idx);
+    count++;
+    offset = idx + NEW_VERSION.length;
+  }
+
+  if (count === 0) {
+    OutputHelper.verbose('Shaders already patched (no #version 150 found).');
+    return 0;
+  }
+
+  await fs.writeFile(shaderPath, data);
+  OutputHelper.info(`Patched ${count} shaders (#version 150 → #version 420).`);
+  return count;
+}

package/src/linux/linux-studio-installer.ts

@@ -0,0 +1,113 @@
+/**
+ * Download and install Roblox Studio from CDN zip packages.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  ROBLOX_CDN_BASE,
+  STUDIO_PACKAGES,
+  type LinuxStudioConfig,
+} from './linux-config.js';
+import { writeInstalledVersionAsync } from './linux-version-resolver.js';
+
+const DOWNLOAD_DIR = '/tmp/roblox-pkgs';
+
+/**
+ * Download all Studio packages from CDN and extract them to studioDir.
+ * Writes AppSettings.xml on completion.
+ */
+export async function installStudioAsync(
+  config: LinuxStudioConfig,
+  version: string
+): Promise<void> {
+  const { studioDir } = config;
+
+  // Clean existing install
+  await fs.rm(studioDir, { recursive: true, force: true });
+  await fs.mkdir(studioDir, { recursive: true });
+
+  // Ensure download cache exists
+  await fs.mkdir(DOWNLOAD_DIR, { recursive: true });
+
+  const packageNames = Object.keys(STUDIO_PACKAGES);
+  OutputHelper.info(`Downloading ${packageNames.length} packages...`);
+
+  // Download packages (sequential to avoid rate limiting)
+  for (const pkg of packageNames) {
+    await downloadPackageAsync(version, pkg);
+  }
+
+  OutputHelper.info('Extracting packages...');
+
+  // Extract each package to its target directory
+  for (const [pkg, subdir] of Object.entries(STUDIO_PACKAGES)) {
+    const target = path.join(studioDir, subdir);
+    await fs.mkdir(target, { recursive: true });
+
+    const zipPath = path.join(DOWNLOAD_DIR, pkg);
+    try {
+      execSync(
+        `unzip -qo ${JSON.stringify(zipPath)} -d ${JSON.stringify(target)}`,
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 60000,
+        }
+      );
+    } catch {
+      OutputHelper.warn(`Failed to extract ${pkg} (non-fatal)`);
+    }
+  }
+
+  // Write AppSettings.xml
+  const appSettings = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<Settings>',
+    '        <ContentFolder>content</ContentFolder>',
+    '        <BaseUrl>http://www.roblox.com</BaseUrl>',
+    '</Settings>',
+  ].join('\n');
+  await fs.writeFile(
+    path.join(studioDir, 'AppSettings.xml'),
+    appSettings,
+    'utf-8'
+  );
+
+  // Record installed version
+  await writeInstalledVersionAsync(studioDir, version);
+
+  OutputHelper.info('Studio installation complete.');
+}
+
+async function downloadPackageAsync(
+  version: string,
+  pkg: string
+): Promise<void> {
+  const dest = path.join(DOWNLOAD_DIR, pkg);
+
+  // Skip if already downloaded
+  try {
+    const stat = await fs.stat(dest);
+    if (stat.size > 0) {
+      OutputHelper.verbose(`Cached: ${pkg}`);
+      return;
+    }
+  } catch {
+    // File doesn't exist, download it
+  }
+
+  const url = `${ROBLOX_CDN_BASE}/${version}-${pkg}`;
+  OutputHelper.verbose(`Downloading ${pkg}...`);
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download ${pkg}: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(dest, buffer);
+}

package/src/linux/linux-studio-launcher.ts

@@ -0,0 +1,90 @@
+/**
+ * Linux-specific Studio launch via Wine. Called by the process manager
+ * when `process.platform === 'linux'`.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { resolveLinuxConfig } from './linux-config.js';
+import { buildWineEnv } from './linux-wine-env.js';
+import {
+  ensureDisplayAsync,
+  ensureWindowManagerAsync,
+} from './linux-display-manager.js';
+import type { StudioProcess } from '../process/studio-process-manager.js';
+
+/**
+ * Launch Studio under Wine with proper display and environment setup.
+ */
+export async function launchStudioLinuxAsync(
+  studioExe: string,
+  placePath: string
+): Promise<StudioProcess> {
+  const config = resolveLinuxConfig();
+
+  // Ensure virtual display is running
+  await ensureDisplayAsync(config);
+  await ensureWindowManagerAsync(config);
+
+  const env = buildWineEnv(config);
+  OutputHelper.verbose(`[StudioBridge] wine ${studioExe} "${placePath}"`);
+
+  // Write Wine stderr to a log file so we can diagnose launch failures.
+  const logPath = path.join(os.tmpdir(), 'studio-bridge-wine.log');
+  const logFd = fs.openSync(logPath, 'w');
+  OutputHelper.verbose(`[StudioBridge] Wine log: ${logPath}`);
+
+  const proc = spawn('wine', [studioExe, placePath], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env,
+  });
+
+  // Close our copy of the fd — the child owns it now
+  fs.closeSync(logFd);
+
+  // Detect early process exit (crash or failure to start)
+  proc.on('exit', (code, signal) => {
+    OutputHelper.verbose(
+      `[StudioBridge] Wine process exited (code=${code}, signal=${signal})`
+    );
+  });
+
+  // Allow our Node process to exit without waiting for Studio
+  proc.unref();
+
+  // Tail the Wine log in verbose mode so diagnostics appear
+  const tailProc = spawn('tail', ['-f', logPath], {
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  tailProc.stdout?.on('data', (chunk: Buffer) => {
+    const lines = chunk.toString('utf-8').trim().split('\n');
+    for (const line of lines) {
+      if (line) {
+        OutputHelper.verbose(`[Wine] ${line}`);
+      }
+    }
+  });
+  tailProc.unref();
+
+  let killed = false;
+  const killAsync = async () => {
+    if (killed) return;
+    killed = true;
+    try {
+      tailProc.kill('SIGTERM');
+    } catch {
+      // Best effort
+    }
+    try {
+      proc.kill('SIGTERM');
+    } catch {
+      // Best effort
+    }
+  };
+
+  return { process: proc, killAsync };
+}