feat(studio-bridge): add Linux/Wine support for headless Studio

Adds the linux/ module tree for running Roblox Studio under Wine on
Linux, including virtual display management, shader patching, FFlag
configuration, credential injection, and headless launch. Pre-registers
ExecuteAction in the plugin at boot so execute messages work without
needing registerAction. Accepts empty heartbeat payloads with defaults,
surfaces plugin errors in the script execution listener, and extracts
captured output from scriptComplete responses.

Author: Quenty

.github/workflows/studio-linux-e2e.yml

@@ -0,0 +1,83 @@
+name: studio-linux-e2e
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'tools/studio-bridge/src/linux/**'
+      - 'tools/studio-bridge/src/process/**'
+      - 'tools/studio-bridge/src/commands/linux/**'
+      - 'tools/nevermore-cli-helpers/src/auth/**'
+      - '.github/workflows/studio-linux-e2e.yml'
+
+jobs:
+  studio-linux-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '21'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          cache: true
+
+      - name: Setup registries
+        run: |
+          echo -e "\n//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> .npmrc
+          echo -e "\n//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> ~/.npmrc
+          echo -e "\n//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> .npmrc
+          echo -e "\n//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Setup Aftman
+        uses: ok-nick/setup-aftman@v0.4.2
+        with:
+          version: 'v0.3.0'
+          token: ${{ secrets.GITHUB_TOKEN }}
+          cache: true
+
+      - name: Build all tools
+        run: pnpm -r --filter './tools/**' run build
+
+      - name: Setup Linux environment
+        run: node tools/studio-bridge/dist/src/cli/cli.js linux setup --install-deps
+
+      - name: Verify environment health (pre-auth)
+        run: node tools/studio-bridge/dist/src/cli/cli.js linux status
+
+      - name: Inject authentication
+        if: ${{ env.ROBLOSECURITY != '' }}
+        run: node tools/studio-bridge/dist/src/cli/cli.js linux auth
+        env:
+          ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
+
+      - name: Initialize Wine prefix
+        if: ${{ env.ROBLOSECURITY != '' }}
+        run: |
+          export DISPLAY=:99
+          export WINEPREFIX="$HOME/.wine"
+          export WINEARCH=win64
+          export WINEDEBUG=-all
+          wineboot --init 2>&1 || true
+          echo "Wine prefix initialized"
+        env:
+          ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
+
+      - name: Execute script through Studio bridge
+        if: ${{ env.ROBLOSECURITY != '' }}
+        run: node tools/studio-bridge/dist/src/cli/cli.js process run --verbose --timeout 240000 'print("E2E test passed!")'
+        timeout-minutes: 8
+        env:
+          ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}

docs/testing/testing.md

@@ -204,6 +204,23 @@ When tests fail in CI, the `post-test-results` command parses Jest-lua output an
 
 The resolver code lives in `tools/nevermore-cli/src/utils/sourcemap/` and is shared with the `strip-sourcemap-jest` command.
 
+## Linux headless testing
+
+Studio can run headlessly on Linux via Wine, enabling E2E tests in devcontainers and GitHub Actions without a display or GPU. The `studio-bridge` CLI handles all environment setup:
+
+```bash
+# One-time setup
+studio-bridge linux setup --install-deps
+studio-bridge linux auth  # reads $ROBLOSECURITY env var
+
+# Run tests the same as on Windows/macOS
+nevermore test
+```
+
+Prerequisites (Wine 11, Xvfb, openbox, Mesa llvmpipe) are documented in `tools/studio-bridge/src/linux/README.md`. The `linux setup --install-deps` flag installs everything on Debian/Ubuntu but is opt-in — it never runs sudo automatically.
+
+For CI, set `ROBLOSECURITY` as a repository or Codespace secret. The `.github/workflows/studio-linux-e2e.yml` workflow demonstrates the full flow.
+
 ## CI design principles
 
 - **Workflows should be thin.** All logic lives in `nevermore-cli` commands — GitHub Actions workflows just call them. This keeps CI debuggable locally.

pnpm-lock.yaml

@@ -23,6 +23,7 @@
   ],
   "dependencies": {
     "@quenty/cli-output-helpers": "workspace:*",
+    "inquirer": "^13.2.0",
     "latest-version": "^9.0.0",
     "semver": "^7.6.0"
   },
@@ -31,12 +32,15 @@
     "@types/semver": "^7.5.0",
     "prettier": "2.7.1",
     "typescript": "^5.9.3",
-    "typescript-memoize": "^1.1.1"
+    "typescript-memoize": "^1.1.1",
+    "vitest": "^3.0.0"
   },
   "scripts": {
     "build": "tsc --build",
     "build:watch": "tsc --build --watch",
     "build:clean": "tsc --build --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "preinstall": "npx only-allow pnpm"
   },
   "publishConfig": {

tools/nevermore-cli-helpers/package.json

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { COOKIE_NAME, parseStudioCookieValue } from './cookie-parser.js';
+
+describe('COOKIE_NAME', () => {
+  it('equals .ROBLOSECURITY', () => {
+    expect(COOKIE_NAME).toBe('.ROBLOSECURITY');
+  });
+});
+
+describe('parseStudioCookieValue', () => {
+  it('parses COOK::<value> format with angle brackets', () => {
+    const result = parseStudioCookieValue('COOK::<abc123>');
+    expect(result).toBe('abc123');
+  });
+
+  it('parses value from comma-separated list', () => {
+    const result = parseStudioCookieValue('OTHER::stuff,COOK::<secret>');
+    expect(result).toBe('secret');
+  });
+
+  it('returns undefined for plain text', () => {
+    expect(parseStudioCookieValue('just a string')).toBeUndefined();
+  });
+
+  it('returns undefined for COOK:: without angle brackets', () => {
+    expect(parseStudioCookieValue('COOK::noBrackets')).toBeUndefined();
+  });
+
+  it('returns undefined for empty string', () => {
+    expect(parseStudioCookieValue('')).toBeUndefined();
+  });
+
+  it('handles a realistic cookie value', () => {
+    const cookie = '_|WARNING:-DO-NOT-SHARE|_abc123def456';
+    const result = parseStudioCookieValue(`COOK::<${cookie}>`);
+    expect(result).toBe(cookie);
+  });
+});

tools/nevermore-cli-helpers/src/auth/roblox-auth/cookie-parser.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Cookie auth and place creation for Roblox legacy APIs.
+ * Based on Mantle: https://github.com/blake-mealey/mantle
+ */
+
+import inquirer from 'inquirer';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { COOKIE_NAME } from './cookie-parser.js';
+import { readCookie as readWindowsCookie } from './windows.js';
+import { readCookie as readMacOSCookie } from './macos.js';
+import { readCookie as readLinuxCookie } from './linux.js';
+
+/**
+ * Resolve the .ROBLOSECURITY cookie for legacy Roblox API calls.
+ *
+ * Resolution order (matching Mantle's rbx_cookie crate):
+ * 1. ROBLOSECURITY environment variable
+ * 2. Platform credential store (Windows Credential Manager / macOS HTTPStorages / Wine Credential Manager)
+ * 3. Platform legacy store (Windows Registry / macOS plist)
+ * 4. Interactive prompt
+ */
+export async function getRobloxCookieAsync(): Promise<string> {
+  const envCookie = process.env.ROBLOSECURITY;
+  if (envCookie) {
+    return envCookie;
+  }
+
+  const platformCookie = readPlatformCookie();
+  if (platformCookie) {
+    return platformCookie;
+  }
+
+  // No interactive prompt in non-TTY environments (CI)
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'No .ROBLOSECURITY cookie available (set ROBLOSECURITY env var for CI)'
+    );
+  }
+
+  const { cookie } = await inquirer.prompt([
+    {
+      type: 'password',
+      name: 'cookie',
+      message: 'Enter your .ROBLOSECURITY cookie (from browser or Studio):',
+      mask: '*',
+      validate: (input: string) => input.length > 0 || 'Cookie cannot be empty',
+    },
+  ]);
+
+  return cookie;
+}
+
+function readPlatformCookie(): string | undefined {
+  switch (process.platform) {
+    case 'win32':
+      return readWindowsCookie();
+    case 'darwin':
+      return readMacOSCookie();
+    case 'linux':
+      return readLinuxCookie();
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Make a cookie-authenticated request to Roblox, handling CSRF token exchange.
+ */
+async function fetchWithCsrfAsync(
+  url: string,
+  cookie: string,
+  options: RequestInit = {}
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    Cookie: `${COOKIE_NAME}=${cookie}`,
+    'User-Agent': 'Roblox/WinInet',
+    ...(options.headers as Record<string, string> | undefined),
+  };
+
+  let response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  if (response.status === 403) {
+    const csrfToken = response.headers.get('x-csrf-token');
+    if (csrfToken) {
+      headers['X-CSRF-TOKEN'] = csrfToken;
+      response = await fetch(url, {
+        ...options,
+        headers,
+      });
+    }
+  }
+
+  return response;
+}
+
+/**
+ * Create a new place in a universe using the legacy cookie-authenticated API.
+ * Returns the new place ID.
+ */
+export async function createPlaceInUniverseAsync(
+  cookie: string,
+  universeId: number,
+  placeName: string
+): Promise<number> {
+  OutputHelper.verbose(
+    `Creating place "${placeName}" in universe ${universeId}...`
+  );
+
+  const createResponse = await fetchWithCsrfAsync(
+    `https://apis.roblox.com/universes/v1/user/universes/${universeId}/places`,
+    cookie,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ templatePlaceId: 95206881 }),
+    }
+  );
+
+  if (!createResponse.ok) {
+    const text = await createResponse.text();
+    throw new Error(
+      `Failed to create place: ${createResponse.status} ${createResponse.statusText}: ${text}`
+    );
+  }
+
+  const createData = (await createResponse.json()) as { placeId: number };
+  const placeId = createData.placeId;
+
+  const renameResponse = await fetchWithCsrfAsync(
+    `https://develop.roblox.com/v2/places/${placeId}`,
+    cookie,
+    {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ name: placeName }),
+    }
+  );
+
+  if (!renameResponse.ok) {
+    OutputHelper.warn(
+      `Place created (${placeId}) but rename failed — you can rename it manually.`
+    );
+  }
+
+  OutputHelper.verbose(`Created place "${placeName}" — ID: ${placeId}`);
+  return placeId;
+}
+
+export interface RenamePlaceResult {
+  success: boolean;
+  reason?: 'no_cookie' | 'api_error';
+  status?: number;
+}
+
+/**
+ * Try to rename an existing place via the develop.roblox.com API.
+ */
+export async function tryRenamePlaceAsync(
+  placeId: number,
+  placeName: string
+): Promise<RenamePlaceResult> {
+  let cookie: string;
+  try {
+    cookie = await getRobloxCookieAsync();
+  } catch {
+    return { success: false, reason: 'no_cookie' };
+  }
+
+  const response = await fetchWithCsrfAsync(
+    `https://develop.roblox.com/v2/places/${placeId}`,
+    cookie,
+    {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ name: placeName }),
+    }
+  );
+
+  if (response.ok) {
+    OutputHelper.verbose(`Renamed place ${placeId} to "${placeName}"`);
+    return { success: true };
+  }
+
+  return { success: false, reason: 'api_error', status: response.status };
+}