@quenty/studio-bridge 0.7.1 → 0.9.0

package/docker/Dockerfile

@@ -0,0 +1,113 @@
+# syntax=docker/dockerfile:1
+FROM ubuntu:24.04
+ARG STUDIO_VERSION
+ARG DEBIAN_FRONTEND=noninteractive
+
+# --- System deps (cached layer, rarely changes) ---
+# Mirrors linux-prerequisites.ts:installDependenciesAsync()
+RUN dpkg --add-architecture i386 \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates curl gnupg software-properties-common \
+        xvfb openbox mesa-utils \
+        gcc-mingw-w64-x86-64 unzip procps \
+    # WineHQ repo for Wine 11+ (same logic as linux-prerequisites.ts:91-128)
+    && mkdir -pm755 /etc/apt/keyrings \
+    && curl -sL https://dl.winehq.org/wine-builds/winehq.key \
+        -o /etc/apt/keyrings/winehq-archive.key \
+    && curl -sfL https://dl.winehq.org/wine-builds/ubuntu/dists/noble/winehq-noble.sources \
+        -o /etc/apt/sources.list.d/winehq-noble.sources \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends winehq-stable \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# --- Node.js 22 LTS + GitHub CLI (needed by setup-aftman action) ---
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends nodejs gh \
+    && corepack enable pnpm \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# --- Image manifest ---
+# Dump the installed apt package list so CI can archive it as a build
+# artifact. Apt deps (winehq-stable, nodejs, gh, etc.) are intentionally
+# not pinned to specific versions — this manifest gives post-hoc
+# visibility into what was actually pulled, so version drift across
+# rebuilds is diagnosable rather than mysterious.
+RUN dpkg-query -W -f='${Package}\t${Version}\t${Architecture}\n' \
+    | sort > /image-manifest-apt.tsv
+
+# --- Aftman binary ---
+RUN curl -fsSL https://github.com/LPGhatguy/aftman/releases/download/v0.3.0/aftman-0.3.0-linux-x86_64.zip \
+        -o /tmp/aftman.zip \
+    && unzip -o /tmp/aftman.zip -d /tmp/aftman \
+    && install -m 755 /tmp/aftman/aftman /usr/local/bin/aftman \
+    && rm -rf /tmp/aftman.zip /tmp/aftman
+
+# --- Non-root user ---
+RUN useradd -m -s /bin/bash studio
+USER studio
+WORKDIR /home/studio
+
+# --- Install Aftman tools (rojo, lune, etc.) ---
+# aftman.toml lives in $HOME so shims can find it from any CWD
+COPY --from=workspace --chown=studio:studio aftman.toml /home/studio/aftman.toml
+RUN mkdir -p /home/studio/.aftman/bin \
+    && aftman install --no-trust-check
+
+# --- Build studio-bridge from source (via named build context "workspace") ---
+COPY --from=workspace --chown=studio:studio package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json /home/studio/build/
+COPY --from=workspace --chown=studio:studio tools/ /home/studio/build/tools/
+WORKDIR /home/studio/build
+RUN pnpm install --frozen-lockfile --filter "@quenty/studio-bridge..." \
+    && pnpm -r --filter "@quenty/studio-bridge..." run build
+
+# --- Run studio-bridge to set up Studio (single source of truth!) ---
+# Invoke cli.js directly — workspace deps are resolved by pnpm in node_modules.
+RUN node tools/studio-bridge/dist/src/cli/cli.js linux setup \
+    ${STUDIO_VERSION:+--studio-version "$STUDIO_VERSION"}
+
+# --- Pre-initialize Wine prefix and compile write-cred.exe ---
+# Doing this at build time saves ~40s per auth invocation at runtime.
+RUN Xvfb :99 -screen 0 1024x768x24 & \
+    sleep 1 \
+    && DISPLAY=:99 WINEPREFIX=/home/studio/.wine WINEARCH=win64 \
+       WINEDEBUG=-all WINEDLLOVERRIDES="mscoree=d;mshtml=d" \
+       wineboot -i \
+    && x86_64-w64-mingw32-gcc \
+       -o /home/studio/roblox-studio/write-cred.exe \
+       tools/studio-bridge/src/linux/write-cred.c \
+       -lcredui -ladvapi32 \
+    && kill %1 || true \
+    && rm -f /tmp/.X99-lock
+
+# --- Install studio-bridge globally for runtime, then clean up ---
+# Use pnpm deploy to create a self-contained copy with resolved workspace deps,
+# then link the binary. This avoids npm registry lookups for workspace packages.
+RUN pnpm --filter "@quenty/studio-bridge" deploy --legacy --prod /home/studio/.studio-bridge \
+    && mkdir -p /home/studio/.npm-global/bin \
+    && ln -s /home/studio/.studio-bridge/dist/src/cli/cli.js /home/studio/.npm-global/bin/studio-bridge \
+    && chmod +x /home/studio/.studio-bridge/dist/src/cli/cli.js \
+    && rm -rf /home/studio/build
+
+# --- Environment (matches linux-wine-env.ts:buildWineEnv) ---
+ENV STUDIO_DIR=/home/studio/roblox-studio \
+    WINEPREFIX=/home/studio/.wine \
+    DISPLAY=:99 \
+    WINEDEBUG=-all \
+    WINEARCH=win64 \
+    WINEDLLOVERRIDES="mscoree=d;mshtml=d" \
+    MESA_GL_VERSION_OVERRIDE=4.5 \
+    MESA_GLSL_VERSION_OVERRIDE=450 \
+    NPM_CONFIG_PREFIX=/home/studio/.npm-global \
+    PATH=/home/studio/.aftman/bin:/home/studio/.npm-global/bin:$PATH
+
+COPY --chown=studio:studio entrypoint.sh /home/studio/entrypoint.sh
+RUN chmod +x /home/studio/entrypoint.sh
+WORKDIR /home/studio
+ENTRYPOINT ["/home/studio/entrypoint.sh"]
+CMD ["bash"]

package/docker/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  studio:
+    build:
+      context: .
+      additional_contexts:
+        workspace: ../../..
+      args:
+        STUDIO_VERSION: ${STUDIO_VERSION:-}
+    image: ghcr.io/quenty/nevermore-studio-linux:${STUDIO_VERSION:-latest}
+    environment:
+      - ROBLOSECURITY=${ROBLOSECURITY:-}
+    volumes:
+      - ../../../:/workspace
+      - wine-prefix:/home/studio/.wine
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+
+volumes:
+  wine-prefix:

package/docker/entrypoint.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Start Xvfb + openbox (mirrors linux-display-manager.ts), then exec user command.
+set -euo pipefail
+
+if ! pgrep -x Xvfb > /dev/null 2>&1; then
+    Xvfb "${DISPLAY:-:99}" -screen 0 1024x768x24 &
+    sleep 0.5
+fi
+
+if ! pgrep -x openbox > /dev/null 2>&1; then
+    DISPLAY="${DISPLAY:-:99}" openbox &
+    sleep 0.5
+fi
+
+# Re-detect network interfaces so Wine sees the runtime network, not the
+# stale build-time config baked in by wineboot -i during docker build.
+wineboot -u > /dev/null 2>&1 || true
+
+exec "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/studio-bridge",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "WebSocket-based bridge for running Luau scripts in Roblox Studio",
   "type": "module",
   "main": "dist/src/index.js",
@@ -15,12 +15,13 @@
     "studio-bridge": "./dist/src/cli/cli.js"
   },
   "dependencies": {
-    "@quenty/cli-output-helpers": "1.10.1",
-    "@quenty/nevermore-cli-helpers": "1.8.1",
-    "@quenty/nevermore-template-helpers": "1.11.1",
+    "@quenty/cli-output-helpers": "1.12.0",
+    "@quenty/nevermore-cli-helpers": "1.10.0",
+    "@quenty/nevermore-template-helpers": "1.13.0",
     "execa": "^9.6.1",
     "ws": "^8.18.0",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^18.11.4",
@@ -35,7 +36,8 @@
     "build:clean": "tsc --build --clean",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:plugin": "lune run templates/studio-bridge-plugin-test/test/test-runner",
     "test:integration": "node dist/test/integration/smoke-test.js"
   },
-  "gitHead": "ab12ae11f52faf00116949383563934b2853b449"
+  "gitHead": "5cba15660c2856169fd0362e1eeeca4c260029c2"
 }

package/src/bridge/bridge-connection-remote.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Unit tests for remote connection support in BridgeConnection --
+ * validates remoteHost parsing, default port behavior, ECONNREFUSED
+ * error handling, and client-only connection mode.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocketServer } from 'ws';
+import { BridgeConnection } from './bridge-connection.js';
+import {
+  encodeHostMessage,
+  decodeHostMessage,
+  type HostProtocolMessage,
+} from './internal/host-protocol.js';
+
+interface MockHost {
+  wss: WebSocketServer;
+  port: number;
+  receivedMessages: HostProtocolMessage[];
+}
+
+/**
+ * Create a mock bridge host WebSocket server that serves on /client
+ * and responds to list-sessions requests (matching the host protocol).
+ */
+async function createMockHostAsync(): Promise<MockHost> {
+  const receivedMessages: HostProtocolMessage[] = [];
+
+  const wss = new WebSocketServer({ port: 0, path: '/client' });
+
+  const port = await new Promise<number>((resolve) => {
+    wss.on('listening', () => {
+      const addr = wss.address();
+      if (typeof addr === 'object' && addr !== null) {
+        resolve(addr.port);
+      }
+    });
+  });
+
+  wss.on('connection', (ws) => {
+    ws.on('message', (raw) => {
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      const msg = decodeHostMessage(data);
+      if (msg) {
+        receivedMessages.push(msg);
+
+        // Auto-respond to list-sessions with empty list
+        if (msg.type === 'list-sessions') {
+          ws.send(
+            encodeHostMessage({
+              type: 'list-sessions-response',
+              requestId: msg.requestId,
+              sessions: [],
+            })
+          );
+        }
+      }
+    });
+  });
+
+  return { wss, port, receivedMessages };
+}
+
+async function closeHostAsync(host: MockHost): Promise<void> {
+  for (const client of host.wss.clients) {
+    client.terminate();
+  }
+  await new Promise<void>((resolve) => {
+    host.wss.close(() => resolve());
+  });
+}
+
+describe('BridgeConnection remote mode', () => {
+  let host: MockHost | undefined;
+  const connections: BridgeConnection[] = [];
+
+  afterEach(async () => {
+    for (const conn of [...connections].reverse()) {
+      await conn.disconnectAsync();
+    }
+    connections.length = 0;
+
+    if (host) {
+      await closeHostAsync(host);
+      host = undefined;
+    }
+  });
+
+  describe('remoteHost parsing', () => {
+    it('connects as client when remoteHost points to a running host', async () => {
+      host = await createMockHostAsync();
+
+      const conn = await BridgeConnection.connectAsync({
+        remoteHost: `localhost:${host.port}`,
+      });
+      connections.push(conn);
+
+      expect(conn.role).toBe('client');
+      expect(conn.isConnected).toBe(true);
+    });
+
+    it('appends default port when no colon in remoteHost', async () => {
+      // We can't easily test against default port 38741,
+      // but we can verify parsing by using port option to override
+      host = await createMockHostAsync();
+
+      // When remoteHost has no colon, port comes from options.port
+      const conn = await BridgeConnection.connectAsync({
+        port: host.port,
+        remoteHost: 'localhost',
+      });
+      connections.push(conn);
+
+      expect(conn.role).toBe('client');
+      expect(conn.isConnected).toBe(true);
+    });
+
+    it('extracts port from remoteHost when colon is present', async () => {
+      host = await createMockHostAsync();
+
+      const conn = await BridgeConnection.connectAsync({
+        remoteHost: `localhost:${host.port}`,
+      });
+      connections.push(conn);
+
+      expect(conn.role).toBe('client');
+      expect(conn.isConnected).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws clear error on ECONNREFUSED for remote host', async () => {
+      await expect(
+        BridgeConnection.connectAsync({
+          remoteHost: 'localhost:19999',
+        })
+      ).rejects.toThrow(/Could not connect to bridge host at localhost:19999/);
+    });
+
+    it('includes helpful suggestion in ECONNREFUSED error', async () => {
+      await expect(
+        BridgeConnection.connectAsync({
+          remoteHost: 'localhost:19998',
+        })
+      ).rejects.toThrow(/studio-bridge serve/);
+    });
+  });
+
+  describe('client-only mode', () => {
+    it('does not become host when remoteHost is specified', async () => {
+      // When remoteHost is set but nothing is listening, it should
+      // NOT fall back to host mode -- it should throw
+      await expect(
+        BridgeConnection.connectAsync({
+          remoteHost: 'localhost:19997',
+        })
+      ).rejects.toThrow();
+    });
+
+    it('remote client can list sessions from host', async () => {
+      host = await createMockHostAsync();
+
+      const conn = await BridgeConnection.connectAsync({
+        remoteHost: `localhost:${host.port}`,
+      });
+      connections.push(conn);
+
+      // No plugins connected, so sessions should be empty
+      const sessions = conn.listSessions();
+      expect(sessions).toEqual([]);
+    });
+  });
+
+  describe('local option', () => {
+    it('local option is accepted without error', async () => {
+      // local: true just skips devcontainer detection -- in a normal
+      // environment it should behave like the default path (try bind)
+      const conn = await BridgeConnection.connectAsync({
+        port: 0,
+        keepAlive: true,
+        local: true,
+      });
+      connections.push(conn);
+
+      // Should work normally in local mode
+      expect(conn.isConnected).toBe(true);
+    });
+  });
+});