@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/linux/linux-version-resolver.ts

@@ -0,0 +1,74 @@
+/**
+ * Resolve the latest Roblox Studio version hash from the CDN.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+
+const CLIENT_SETTINGS_URL =
+  'https://clientsettingscdn.roblox.com/v2/client-version/WindowsStudio64';
+
+interface ClientVersionResponse {
+  version: string;
+  clientVersionUpload: string;
+  bootstrapperVersion: string;
+}
+
+/**
+ * Fetch the current Studio version string from the Roblox client settings API.
+ * Returns a version hash like "version-e095049f34844c41".
+ */
+export async function resolveStudioVersionAsync(
+  explicitVersion?: string
+): Promise<string> {
+  if (explicitVersion) {
+    return explicitVersion;
+  }
+
+  OutputHelper.verbose(
+    'Fetching latest Studio version from client settings...'
+  );
+
+  const response = await fetch(CLIENT_SETTINGS_URL);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch Studio version: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const data = (await response.json()) as ClientVersionResponse;
+  const version = data.clientVersionUpload;
+  if (!version.startsWith('version-')) {
+    throw new Error(`Unexpected version format: ${version}`);
+  }
+
+  OutputHelper.verbose(`Latest Studio version: ${version} (${data.version})`);
+  return version;
+}
+
+/**
+ * Read the installed version from a .studio-version marker file.
+ * Returns undefined if no version is installed.
+ */
+export async function readInstalledVersionAsync(
+  studioDir: string
+): Promise<string | undefined> {
+  const versionFile = path.join(studioDir, '.studio-version');
+  try {
+    return (await fs.readFile(versionFile, 'utf-8')).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write the installed version to a .studio-version marker file.
+ */
+export async function writeInstalledVersionAsync(
+  studioDir: string,
+  version: string
+): Promise<void> {
+  const versionFile = path.join(studioDir, '.studio-version');
+  await fs.writeFile(versionFile, version + '\n', 'utf-8');
+}

package/src/linux/linux-wine-env.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { buildWineEnv } from './linux-wine-env.js';
+import type { LinuxStudioConfig } from './linux-config.js';
+
+function makeConfig(overrides?: Partial<LinuxStudioConfig>): LinuxStudioConfig {
+  return {
+    studioDir: '/home/test/roblox-studio',
+    winePrefix: '/home/test/.wine',
+    display: ':99',
+    studioExe: '/home/test/roblox-studio/RobloxStudioBeta.exe',
+    clientSettingsPath:
+      '/home/test/roblox-studio/ClientSettings/ClientAppSettings.json',
+    shadersDir: '/home/test/roblox-studio/shaders',
+    pluginsDir: '/home/test/roblox-studio/Plugins',
+    writeCredExe: '/home/test/roblox-studio/write-cred.exe',
+    ...overrides,
+  };
+}
+
+describe('buildWineEnv', () => {
+  it('includes DISPLAY from config', () => {
+    const env = buildWineEnv(makeConfig({ display: ':42' }));
+    expect(env.DISPLAY).toBe(':42');
+  });
+
+  it('includes WINEPREFIX from config', () => {
+    const env = buildWineEnv(makeConfig({ winePrefix: '/tmp/wine' }));
+    expect(env.WINEPREFIX).toBe('/tmp/wine');
+  });
+
+  it('sets WINEARCH to win64', () => {
+    const env = buildWineEnv(makeConfig());
+    expect(env.WINEARCH).toBe('win64');
+  });
+
+  it('suppresses Wine debug output', () => {
+    const env = buildWineEnv(makeConfig());
+    expect(env.WINEDEBUG).toBe('-all');
+  });
+
+  it('suppresses Mono/Gecko install dialogs', () => {
+    const env = buildWineEnv(makeConfig());
+    expect(env.WINEDLLOVERRIDES).toBe('mscoree=d;mshtml=d');
+  });
+
+  it('sets Mesa GL version overrides', () => {
+    const env = buildWineEnv(makeConfig());
+    expect(env.MESA_GL_VERSION_OVERRIDE).toBe('4.5');
+    expect(env.MESA_GLSL_VERSION_OVERRIDE).toBe('450');
+  });
+
+  it('preserves PATH from process.env', () => {
+    const env = buildWineEnv(makeConfig());
+    expect(env.PATH).toBe(process.env.PATH);
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * Assemble the environment variables needed to run Wine processes
+ * with the correct display, Mesa overrides, and prefix.
+ */
+
+import type { LinuxStudioConfig } from './linux-config.js';
+
+/**
+ * Build a complete env dictionary for running `wine` subprocesses.
+ * Merges with process.env so the child inherits PATH, HOME, etc.
+ */
+export function buildWineEnv(
+  config: LinuxStudioConfig
+): Record<string, string> {
+  return {
+    ...stripUndefined(process.env),
+    DISPLAY: config.display,
+    WINEPREFIX: config.winePrefix,
+    WINEARCH: 'win64',
+    WINEDEBUG: process.env.WINEDEBUG ?? '-all',
+    // Suppress Mono/Gecko install dialogs that block headless runs
+    WINEDLLOVERRIDES: 'mscoree=d;mshtml=d',
+    // Mesa llvmpipe needs these overrides so Wine's WineD3D layer
+    // sees GL 4.5 / GLSL 4.50 (required for the patched shaders)
+    MESA_GL_VERSION_OVERRIDE: '4.5',
+    MESA_GLSL_VERSION_OVERRIDE: '450',
+  };
+}
+
+function stripUndefined(env: NodeJS.ProcessEnv): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/src/linux/write-cred.c

@@ -0,0 +1,48 @@
+#include <windows.h>
+#include <wincred.h>
+#include <stdio.h>
+#include <string.h>
+
+/**
+ * Write one or more credentials to the Windows Credential Manager.
+ * Accepts pairs of arguments: <target> <value> [<target> <value> ...]
+ * This batching avoids repeated Wine process startup overhead.
+ */
+int main(int argc, char *argv[]) {
+    if (argc < 3 || (argc - 1) % 2 != 0) {
+        printf("Usage: write-cred.exe <target> <value> [<target> <value> ...]\n");
+        printf("Example: write-cred.exe \"target1\" \"val1\" \"target2\" \"val2\"\n");
+        return 1;
+    }
+
+    int pairs = (argc - 1) / 2;
+    int failures = 0;
+
+    for (int i = 0; i < pairs; i++) {
+        const char *target = argv[1 + i * 2];
+        const char *value = argv[2 + i * 2];
+
+        int tlen = MultiByteToWideChar(CP_UTF8, 0, target, -1, NULL, 0);
+        WCHAR *wtarget = (WCHAR *)malloc(tlen * sizeof(WCHAR));
+        MultiByteToWideChar(CP_UTF8, 0, target, -1, wtarget, tlen);
+
+        CREDENTIALW cred;
+        memset(&cred, 0, sizeof(cred));
+        cred.Type = CRED_TYPE_GENERIC;
+        cred.TargetName = wtarget;
+        cred.CredentialBlobSize = (DWORD)strlen(value);
+        cred.CredentialBlob = (BYTE *)value;
+        cred.Persist = CRED_PERSIST_LOCAL_MACHINE;
+
+        if (!CredWriteW(&cred, 0)) {
+            printf("CredWriteW failed for '%s': %lu\n", target, GetLastError());
+            failures++;
+        } else {
+            printf("Credential written: target='%s', value_len=%d\n", target, (int)strlen(value));
+        }
+
+        free(wtarget);
+    }
+
+    return failures > 0 ? 1 : 0;
+}

package/src/plugin/persistent-plugin-installer.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for the persistent plugin installer.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const {
+  mockGetPersistentPluginPath,
+  mockRojoBuildAsync,
+  mockCleanupAsync,
+  mockResolvePath,
+  mockCreateDirectoryContentsAsync,
+  mockMkdir,
+  mockCopyFile,
+  mockRename,
+  mockUnlink,
+} = vi.hoisted(() => ({
+  mockGetPersistentPluginPath: vi.fn(
+    () => '/mock/plugins/folder/StudioBridgePersistentPlugin.rbxm'
+  ),
+  mockRojoBuildAsync: vi.fn().mockResolvedValue(undefined),
+  mockCleanupAsync: vi.fn().mockResolvedValue(undefined),
+  mockResolvePath: vi.fn((rel: string) => `/tmp/mock-build-dir/${rel}`),
+  mockCreateDirectoryContentsAsync: vi.fn().mockResolvedValue(undefined),
+  mockMkdir: vi.fn().mockResolvedValue(undefined),
+  mockCopyFile: vi.fn().mockResolvedValue(undefined),
+  mockRename: vi.fn().mockResolvedValue(undefined),
+  mockUnlink: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../process/studio-process-manager.js', () => ({
+  findPluginsFolder: vi.fn(() => '/mock/plugins/folder'),
+}));
+
+vi.mock('./plugin-discovery.js', () => ({
+  getPersistentPluginPath: mockGetPersistentPluginPath,
+}));
+
+vi.mock('@quenty/nevermore-template-helpers', () => ({
+  BuildContext: {
+    createAsync: vi.fn().mockResolvedValue({
+      buildDir: '/tmp/mock-build-dir',
+      resolvePath: mockResolvePath,
+      rojoBuildAsync: mockRojoBuildAsync,
+      cleanupAsync: mockCleanupAsync,
+    }),
+  },
+  TemplateHelper: {
+    createDirectoryContentsAsync: mockCreateDirectoryContentsAsync,
+  },
+  resolveTemplatePath: vi.fn(() => '/mock/templates/studio-bridge-plugin'),
+}));
+
+vi.mock('fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('fs/promises')>();
+  return {
+    ...actual,
+    mkdir: mockMkdir,
+    copyFile: mockCopyFile,
+    rename: mockRename,
+    unlink: mockUnlink,
+  };
+});
+
+import {
+  installPersistentPluginAsync,
+  uninstallPersistentPluginAsync,
+} from './persistent-plugin-installer.js';
+
+describe('persistent-plugin-installer', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRojoBuildAsync.mockResolvedValue(undefined);
+    mockCreateDirectoryContentsAsync.mockResolvedValue(undefined);
+    mockCleanupAsync.mockResolvedValue(undefined);
+    mockMkdir.mockResolvedValue(undefined);
+    mockCopyFile.mockResolvedValue(undefined);
+    mockRename.mockResolvedValue(undefined);
+    mockUnlink.mockResolvedValue(undefined);
+  });
+
+  describe('installPersistentPluginAsync', () => {
+    it('builds plugin and atomically renames into the plugins folder', async () => {
+      const result = await installPersistentPluginAsync();
+
+      expect(result).toBe(
+        '/mock/plugins/folder/StudioBridgePersistentPlugin.rbxm'
+      );
+      expect(mockCreateDirectoryContentsAsync).toHaveBeenCalled();
+      // rojo builds into the temp dir, not the plugins folder.
+      expect(mockRojoBuildAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          output: '/tmp/mock-build-dir/StudioBridgePersistentPlugin.rbxm',
+        })
+      );
+      // copyFile -> rename pattern keeps Studio's polling watcher from
+      // observing a partially-written .rbxm.
+      expect(mockCopyFile).toHaveBeenCalledTimes(1);
+      expect(mockRename).toHaveBeenCalledTimes(1);
+      const [renameSrc, renameDest] = mockRename.mock.calls[0];
+      expect(renameDest).toBe(
+        '/mock/plugins/folder/StudioBridgePersistentPlugin.rbxm'
+      );
+      // Staging file lives in the destination filesystem.
+      expect(renameSrc).toMatch(
+        /^\/mock\/plugins\/folder\/\.StudioBridgePersistentPlugin\.rbxm\.tmp-/
+      );
+    });
+
+    it('cleans up build context on error', async () => {
+      mockCreateDirectoryContentsAsync.mockRejectedValueOnce(
+        new Error('template error')
+      );
+
+      await expect(installPersistentPluginAsync()).rejects.toThrow(
+        'template error'
+      );
+      expect(mockCleanupAsync).toHaveBeenCalled();
+    });
+
+    it('cleans up build context on success', async () => {
+      await installPersistentPluginAsync();
+      expect(mockCleanupAsync).toHaveBeenCalled();
+    });
+
+    it('removes staging file when rename fails', async () => {
+      mockRename.mockRejectedValueOnce(new Error('rename failed'));
+
+      await expect(installPersistentPluginAsync()).rejects.toThrow(
+        'rename failed'
+      );
+      expect(mockUnlink).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /^\/mock\/plugins\/folder\/\.StudioBridgePersistentPlugin\.rbxm\.tmp-/
+        )
+      );
+    });
+  });
+
+  describe('uninstallPersistentPluginAsync', () => {
+    it('removes the plugin file when installed', async () => {
+      await uninstallPersistentPluginAsync();
+
+      expect(mockUnlink).toHaveBeenCalledWith(
+        '/mock/plugins/folder/StudioBridgePersistentPlugin.rbxm'
+      );
+    });
+
+    it('throws a friendly error when the plugin is not installed', async () => {
+      const enoent = Object.assign(new Error('ENOENT'), {
+        code: 'ENOENT',
+      });
+      mockUnlink.mockRejectedValueOnce(enoent);
+
+      await expect(uninstallPersistentPluginAsync()).rejects.toThrow(
+        'Persistent plugin is not installed'
+      );
+    });
+
+    it('propagates non-ENOENT errors', async () => {
+      mockUnlink.mockRejectedValueOnce(
+        Object.assign(new Error('EACCES'), { code: 'EACCES' })
+      );
+
+      await expect(uninstallPersistentPluginAsync()).rejects.toThrow('EACCES');
+    });
+  });
+});

package/src/plugin/persistent-plugin-installer.ts

@@ -0,0 +1,90 @@
+/**
+ * Builds and installs (or uninstalls) the persistent Studio Bridge plugin
+ * into Roblox Studio's plugins folder using rojo.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import {
+  BuildContext,
+  TemplateHelper,
+  resolveTemplatePath,
+} from '@quenty/nevermore-template-helpers';
+import { findPluginsFolder } from '../process/studio-process-manager.js';
+import { getPersistentPluginPath } from './plugin-discovery.js';
+
+const templateDir = resolveTemplatePath(
+  import.meta.url,
+  'studio-bridge-plugin'
+);
+
+const PERSISTENT_PLUGIN_FILENAME = 'StudioBridgePersistentPlugin.rbxm';
+
+/**
+ * Build the persistent plugin template via rojo and atomically install the
+ * resulting `.rbxm` into the Studio plugins folder.
+ *
+ * The build runs inside the BuildContext's temp dir; the file is then
+ * copied to a temp name in the plugins folder and renamed into place so
+ * Studio's polling watcher never observes a partially-written .rbxm.
+ *
+ * @returns The absolute path to the installed plugin file.
+ */
+export async function installPersistentPluginAsync(): Promise<string> {
+  const buildContext = await BuildContext.createAsync({
+    prefix: 'studio-bridge-persistent-plugin-',
+  });
+
+  try {
+    await TemplateHelper.createDirectoryContentsAsync(
+      templateDir,
+      buildContext.buildDir,
+      {},
+      false
+    );
+
+    const builtPath = buildContext.resolvePath(PERSISTENT_PLUGIN_FILENAME);
+    await buildContext.rojoBuildAsync({
+      projectPath: buildContext.resolvePath('default.project.json'),
+      output: builtPath,
+    });
+
+    const pluginsFolder = findPluginsFolder();
+    await fs.mkdir(pluginsFolder, { recursive: true });
+
+    const finalPath = path.join(pluginsFolder, PERSISTENT_PLUGIN_FILENAME);
+    // Stage in the destination filesystem so the rename is atomic.
+    const stagingPath = path.join(
+      pluginsFolder,
+      `.${PERSISTENT_PLUGIN_FILENAME}.tmp-${process.pid}`
+    );
+    await fs.copyFile(builtPath, stagingPath);
+    try {
+      await fs.rename(stagingPath, finalPath);
+    } catch (err) {
+      // Best-effort cleanup of the staging file before propagating.
+      await fs.unlink(stagingPath).catch(() => {});
+      throw err;
+    }
+
+    return finalPath;
+  } finally {
+    await buildContext.cleanupAsync();
+  }
+}
+
+/**
+ * Remove the persistent plugin file from the Studio plugins folder.
+ * Throws if the plugin is not installed.
+ */
+export async function uninstallPersistentPluginAsync(): Promise<void> {
+  const pluginPath = getPersistentPluginPath();
+  try {
+    await fs.unlink(pluginPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error('Persistent plugin is not installed. Nothing to remove.');
+    }
+    throw err;
+  }
+}

package/src/plugin/plugin-discovery.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Unit tests for plugin discovery utilities.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as path from 'path';
+
+// Mock dependencies before importing the module under test
+vi.mock('../process/studio-process-manager.js', () => ({
+  findPluginsFolder: vi.fn(() => '/mock/plugins/folder'),
+}));
+
+vi.mock('fs', () => ({
+  existsSync: vi.fn(() => false),
+}));
+
+import { existsSync } from 'fs';
+import {
+  getPersistentPluginPath,
+  isPersistentPluginInstalled,
+} from './plugin-discovery.js';
+
+const mockedExistsSync = vi.mocked(existsSync);
+
+describe('plugin-discovery', () => {
+  let originalCI: string | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    originalCI = process.env.CI;
+    delete process.env.CI;
+  });
+
+  afterEach(() => {
+    if (originalCI === undefined) {
+      delete process.env.CI;
+    } else {
+      process.env.CI = originalCI;
+    }
+  });
+
+  describe('getPersistentPluginPath', () => {
+    it('returns path combining plugins folder and filename', () => {
+      const result = getPersistentPluginPath();
+      expect(result).toBe(
+        path.join('/mock/plugins/folder', 'StudioBridgePersistentPlugin.rbxm')
+      );
+    });
+  });
+
+  describe('isPersistentPluginInstalled', () => {
+    it('returns true when the plugin file exists', () => {
+      mockedExistsSync.mockReturnValue(true);
+      expect(isPersistentPluginInstalled()).toBe(true);
+    });
+
+    it('returns false when the plugin file does not exist', () => {
+      mockedExistsSync.mockReturnValue(false);
+      expect(isPersistentPluginInstalled()).toBe(false);
+    });
+
+    it('returns false in CI environment regardless of file existence', () => {
+      process.env.CI = 'true';
+      mockedExistsSync.mockReturnValue(true);
+      expect(isPersistentPluginInstalled()).toBe(false);
+      // existsSync should not even be called in CI
+      expect(mockedExistsSync).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/plugin/plugin-discovery.ts

@@ -0,0 +1,21 @@
+/**
+ * Utilities for detecting whether the persistent Studio Bridge plugin
+ * is installed in the Roblox Studio plugins folder.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { findPluginsFolder } from '../process/studio-process-manager.js';
+
+const PERSISTENT_PLUGIN_FILENAME = 'StudioBridgePersistentPlugin.rbxm';
+
+export function getPersistentPluginPath(): string {
+  return path.join(findPluginsFolder(), PERSISTENT_PLUGIN_FILENAME);
+}
+
+export function isPersistentPluginInstalled(): boolean {
+  if (process.env.CI === 'true') {
+    return false;
+  }
+  return fs.existsSync(getPersistentPluginPath());
+}

package/src/plugin/plugin-injector.ts

@@ -43,7 +43,7 @@ export async function injectPluginAsync(
     await TemplateHelper.createDirectoryContentsAsync(
       templateDir,
       buildContext.buildDir,
-      { PORT: String(port), SESSION_ID: sessionId },
+      { PORT: String(port), SESSION_ID: sessionId, EPHEMERAL: 'true' },
       false
     );
 

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

@@ -31,8 +31,29 @@ describe('findPluginsFolder', () => {
     expect(result).toMatch(/Roblox[/\\]Plugins$/);
   });
 
-  it('throws on unsupported platform', () => {
+  it('returns correct Linux path using WINEPREFIX', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    process.env.WINEPREFIX = '/home/test/.wine';
+    process.env.USER = 'testuser';
+
+    const result = findPluginsFolder();
+    expect(result).toMatch(/Plugins$/);
+    expect(result).toContain('/home/test/.wine/drive_c/users/testuser');
+    expect(result).toContain('Roblox');
+  });
+
+  it('returns correct Linux path with default Wine prefix', () => {
     Object.defineProperty(process, 'platform', { value: 'linux' });
+    delete process.env.WINEPREFIX;
+
+    const result = findPluginsFolder();
+    expect(result).toMatch(/Plugins$/);
+    expect(result).toContain('.wine');
+    expect(result).toContain('Roblox');
+  });
+
+  it('throws on unsupported platform', () => {
+    Object.defineProperty(process, 'platform', { value: 'freebsd' });
 
     expect(() => findPluginsFolder()).toThrow('Unsupported platform');
   });