@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/commands/viewport/screenshot/capture-screenshot.luau

@@ -0,0 +1,247 @@
+--!optimize 2
+--[[
+	CaptureScreenshot action handler for the studio-bridge plugin.
+
+	Captures the Studio viewport using CaptureService, loads the result into
+	an EditableImage to read raw RGBA pixels, encodes as PNG via png-luau,
+	base64-encodes the PNG via EncodingService, and sends it over the WebSocket.
+
+	Protocol:
+	  Request:  { type: "captureScreenshot", payload: { format?: "png" } }
+	  Response: { type: "screenshotResult", payload: { data, format, width, height } }
+]]
+
+-- PNG encoder is injected via router._vendorPng (set by the plugin before
+-- actions are pushed). Falls back gracefully to raw RGBA if unavailable.
+local _png = nil
+local _disposed = false
+
+local CaptureScreenshotAction = {}
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+local function buildResponse(sessionId: string, requestId: string?, payload: { [string]: any }): { [string]: any }
+	local msg: { [string]: any } = {
+		type = "screenshotResult",
+		sessionId = sessionId,
+		payload = payload,
+	}
+	if requestId ~= nil and requestId ~= "" then
+		msg.requestId = requestId
+	end
+	return msg
+end
+
+local function buildError(sessionId: string, requestId: string?, code: string, message: string): { [string]: any }
+	local msg: { [string]: any } = {
+		type = "error",
+		sessionId = sessionId,
+		payload = { code = code, message = message },
+	}
+	if requestId ~= nil and requestId ~= "" then
+		msg.requestId = requestId
+	end
+	return msg
+end
+
+-- ---------------------------------------------------------------------------
+-- Core capture logic (runs in a spawned thread)
+-- ---------------------------------------------------------------------------
+
+local function captureAsync(sendMessage: (msg: { [string]: any }) -> (), requestId: string?, sessionId: string)
+	-- Resolve services (deferred so the module loads in Lune test context)
+	local getServiceOk, captureServiceOrErr, assetServiceOrErr, encodingServiceOrErr = pcall(function()
+		return game:GetService("CaptureService"), game:GetService("AssetService"), game:GetService("EncodingService")
+	end)
+	if not getServiceOk then
+		sendMessage(
+			buildError(sessionId, requestId, "CAPTURE_FAILED", `Required services not available: {captureServiceOrErr}`)
+		)
+		return
+	end
+	local CaptureService = captureServiceOrErr
+	local AssetService = assetServiceOrErr
+	local EncodingService = encodingServiceOrErr
+
+	-- Step 1: Capture the viewport via CaptureService
+	local callerThread = coroutine.running()
+	local contentId: string? = nil
+	local captureOk, captureErr = pcall(function()
+		CaptureService:CaptureScreenshot(function(id)
+			contentId = id
+			task.spawn(callerThread)
+		end)
+	end)
+
+	if not captureOk then
+		sendMessage(buildError(sessionId, requestId, "CAPTURE_FAILED", `CaptureService failed: {captureErr}`))
+		return
+	end
+
+	-- Wait for the callback
+	coroutine.yield()
+
+	if _disposed then return end
+
+	if not contentId or contentId == "" then
+		sendMessage(buildError(sessionId, requestId, "CAPTURE_FAILED", "CaptureService returned no content ID"))
+		return
+	end
+
+	-- Step 2: Load into an EditableImage to read pixels
+	local editableOk, editableImage = pcall(function()
+		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId :: string))
+	end)
+
+	if not editableOk or not editableImage then
+		sendMessage(
+			buildError(
+				sessionId,
+				requestId,
+				"EDITABLE_IMAGE_FAILED",
+				`Failed to create EditableImage from capture: {editableImage or "unknown error"}`
+			)
+		)
+		return
+	end
+
+	-- Step 3: Read all pixels as RGBA buffer
+	-- ReadPixelsBuffer has a 1024x1024 limit. If the screenshot is larger,
+	-- scale it down into a new EditableImage that fits within the limit.
+	local MAX_SIZE = 1024
+	local srcWidth = editableImage.Size.X
+	local srcHeight = editableImage.Size.Y
+	local width = srcWidth
+	local height = srcHeight
+
+	local readTarget = editableImage
+	local scaledImage = nil
+
+	if srcWidth > MAX_SIZE or srcHeight > MAX_SIZE then
+		local scale = math.min(MAX_SIZE / srcWidth, MAX_SIZE / srcHeight)
+		width = math.floor(srcWidth * scale)
+		height = math.floor(srcHeight * scale)
+
+		local scaleOk, scaleResult = pcall(function()
+			local scaled = AssetService:CreateEditableImage({ Size = Vector2.new(width, height) })
+			scaled:DrawImageTransformed(
+				Vector2.new(width / 2, height / 2), -- center position
+				Vector2.new(scale, scale), -- scale
+				0, -- rotation
+				editableImage
+			)
+			return scaled
+		end)
+
+		if scaleOk and scaleResult then
+			scaledImage = scaleResult
+			readTarget = scaleResult
+		else
+			-- If scaling fails, just read the top-left 1024x1024 corner
+			width = math.min(srcWidth, MAX_SIZE)
+			height = math.min(srcHeight, MAX_SIZE)
+		end
+	end
+
+	local pixelsOk, pixelsBuf = pcall(function()
+		return readTarget:ReadPixelsBuffer(Vector2.zero, Vector2.new(width, height))
+	end)
+
+	-- Clean up EditableImages immediately to free memory
+	pcall(function()
+		editableImage:Destroy()
+	end)
+	if scaledImage then
+		pcall(function()
+			scaledImage:Destroy()
+		end)
+	end
+
+	if not pixelsOk or not pixelsBuf then
+		sendMessage(
+			buildError(
+				sessionId,
+				requestId,
+				"PIXEL_READ_FAILED",
+				`Failed to read pixels: {pixelsBuf or "unknown error"}`
+			)
+		)
+		return
+	end
+
+	-- Step 4: Encode as PNG (if available) or raw RGBA, then base64
+	local dataBuf = pixelsBuf
+	local format = "rgba"
+
+	if _png then
+		local pngOk, pngBuf = pcall(_png.encode, pixelsBuf, { width = width, height = height })
+		if pngOk and pngBuf then
+			dataBuf = pngBuf
+			format = "png"
+		end
+	end
+
+	local encodeOk, encoded = pcall(function()
+		return EncodingService:Base64Encode(dataBuf)
+	end)
+	if not encodeOk or not encoded then
+		sendMessage(
+			buildError(
+				sessionId,
+				requestId,
+				"ENCODE_FAILED",
+				`Failed to base64 encode data: {encoded or "unknown error"}`
+			)
+		)
+		return
+	end
+
+	-- Step 5: Send the result
+	sendMessage(buildResponse(sessionId, requestId, {
+		data = encoded,
+		format = format,
+		width = width,
+		height = height,
+	}))
+end
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+function CaptureScreenshotAction.register(router: any, sendMessage: ((msg: { [string]: any }) -> ())?)
+	_disposed = false
+	router:setResponseType("captureScreenshot", "screenshotResult")
+	-- Capture the PNG encoder from the router's shared deps (set by the plugin)
+	_png = router._vendorPng or nil
+
+	router:register("captureScreenshot", function(_payload: { [string]: any }, requestId: string, sessionId: string): { [string]: any }?
+		if not sendMessage then
+			return {
+				code = "CAPABILITY_NOT_SUPPORTED",
+				message = "Screenshot capture requires a sendMessage callback",
+			}
+		end
+
+		-- Run asynchronously since CaptureService uses a callback.
+		-- pcall guards against Lune test context where task is not available.
+		local spawnOk = pcall(function()
+			task.spawn(captureAsync, sendMessage, requestId, sessionId)
+		end)
+		if not spawnOk then
+			-- Fallback: call directly (will fail on GetService in Lune)
+			captureAsync(sendMessage, requestId, sessionId)
+		end
+
+		-- Return nil so ActionRouter does not generate a wrapped response
+		return nil
+	end)
+end
+
+function CaptureScreenshotAction.teardown()
+	_disposed = true
+end
+
+return CaptureScreenshotAction

package/src/commands/viewport/screenshot/screenshot.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Unit tests for the screenshot command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { captureScreenshotHandlerAsync } from './screenshot.js';
+import { rgbaToPng } from '../../rgba-to-png.js';
+
+function createMockSession(screenshotResult: {
+  data: string;
+  format: 'png' | 'rgba';
+  width: number;
+  height: number;
+}) {
+  return {
+    captureScreenshotAsync: vi.fn().mockResolvedValue(screenshotResult),
+  } as any;
+}
+
+describe('rgbaToPng', () => {
+  it('produces a valid PNG for a 1x1 red pixel', () => {
+    // 1x1 RGBA: red pixel (255, 0, 0, 255)
+    const rgba = Buffer.from([255, 0, 0, 255]);
+    const png = rgbaToPng(rgba, 1, 1);
+
+    // Check PNG signature
+    expect(png[0]).toBe(137);
+    expect(png[1]).toBe(80); // 'P'
+    expect(png[2]).toBe(78); // 'N'
+    expect(png[3]).toBe(71); // 'G'
+    expect(png.length).toBeGreaterThan(8);
+  });
+
+  it('produces a valid PNG for a 2x2 image', () => {
+    // 2x2 RGBA: 4 pixels * 4 bytes = 16 bytes
+    const rgba = Buffer.alloc(16, 0);
+    // Set all pixels to blue (0, 0, 255, 255)
+    for (let i = 0; i < 4; i++) {
+      rgba[i * 4 + 2] = 255;
+      rgba[i * 4 + 3] = 255;
+    }
+    const png = rgbaToPng(rgba, 2, 2);
+
+    // Check PNG signature
+    expect(png.subarray(0, 4)).toEqual(Buffer.from([137, 80, 78, 71]));
+  });
+
+  it('throws on data length mismatch', () => {
+    const rgba = Buffer.alloc(10); // Wrong size for any dimensions
+    expect(() => rgbaToPng(rgba, 2, 2)).toThrow('data length mismatch');
+  });
+
+  it('round-trips: PNG starts with signature and ends with IEND', () => {
+    const rgba = Buffer.alloc(4 * 4 * 4, 128); // 4x4 gray pixels
+    const png = rgbaToPng(rgba, 4, 4);
+
+    // Signature
+    expect(png.subarray(0, 8)).toEqual(
+      Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+    );
+
+    // IEND chunk at end: length(0) + "IEND" + CRC
+    const iendType = png
+      .subarray(png.length - 8, png.length - 4)
+      .toString('ascii');
+    expect(iendType).toBe('IEND');
+  });
+});
+
+describe('captureScreenshotHandlerAsync', () => {
+  it('returns screenshot result with summary (png format)', async () => {
+    const session = createMockSession({
+      data: 'iVBORw0KGgoAAAANSUhEUg==',
+      format: 'png',
+      width: 1920,
+      height: 1080,
+    });
+
+    const result = await captureScreenshotHandlerAsync(session);
+
+    expect(result.data).toBe('iVBORw0KGgoAAAANSUhEUg==');
+    expect(result.width).toBe(1920);
+    expect(result.height).toBe(1080);
+    expect(result.summary).toBe('Screenshot captured (1920x1080)');
+  });
+
+  it('converts rgba format to png', async () => {
+    // 1x1 red pixel as RGBA
+    const rgbaBase64 = Buffer.from([255, 0, 0, 255]).toString('base64');
+    const session = createMockSession({
+      data: rgbaBase64,
+      format: 'rgba',
+      width: 1,
+      height: 1,
+    });
+
+    const result = await captureScreenshotHandlerAsync(session);
+
+    // Result should be valid PNG base64
+    const pngBuffer = Buffer.from(result.data, 'base64');
+    expect(pngBuffer[0]).toBe(137); // PNG signature
+    expect(pngBuffer[1]).toBe(80);
+    expect(result.width).toBe(1);
+    expect(result.height).toBe(1);
+    expect(result.summary).toBe('Screenshot captured (1x1)');
+  });
+
+  it('calls session.captureScreenshotAsync', async () => {
+    const session = createMockSession({
+      data: 'base64data',
+      format: 'png',
+      width: 800,
+      height: 600,
+    });
+
+    await captureScreenshotHandlerAsync(session);
+
+    expect(session.captureScreenshotAsync).toHaveBeenCalledOnce();
+  });
+
+  it('handles different dimensions', async () => {
+    const session = createMockSession({
+      data: 'abc',
+      format: 'png',
+      width: 3840,
+      height: 2160,
+    });
+
+    const result = await captureScreenshotHandlerAsync(session);
+
+    expect(result.width).toBe(3840);
+    expect(result.height).toBe(2160);
+    expect(result.summary).toContain('3840x2160');
+  });
+
+  it('propagates errors from session', async () => {
+    const session = {
+      captureScreenshotAsync: vi
+        .fn()
+        .mockRejectedValue(new Error('Screenshot failed')),
+    } as any;
+
+    await expect(captureScreenshotHandlerAsync(session)).rejects.toThrow(
+      'Screenshot failed'
+    );
+  });
+
+  it('handles missing fields gracefully', async () => {
+    const session = {
+      captureScreenshotAsync: vi.fn().mockResolvedValue({
+        data: undefined,
+        format: 'png',
+        width: undefined,
+        height: undefined,
+      }),
+    } as any;
+
+    const result = await captureScreenshotHandlerAsync(session);
+
+    expect(result.data).toBe('');
+    expect(result.width).toBe(0);
+    expect(result.height).toBe(0);
+    expect(result.summary).toBe('Screenshot captured (0x0)');
+  });
+
+  it('passes options without affecting capture', async () => {
+    const session = createMockSession({
+      data: 'base64data',
+      format: 'png',
+      width: 1280,
+      height: 720,
+    });
+
+    const result = await captureScreenshotHandlerAsync(session, {
+      output: '/tmp/screenshot.png',
+    });
+
+    expect(result.data).toBe('base64data');
+    expect(session.captureScreenshotAsync).toHaveBeenCalledOnce();
+  });
+});

package/src/commands/viewport/screenshot/screenshot.ts

@@ -0,0 +1,71 @@
+/**
+ * `viewport screenshot` — capture a viewport screenshot from a
+ * connected Studio session.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type { ScreenshotResult as BridgeScreenshotResult } from '../../../bridge/index.js';
+import { rgbaToPng } from '../../rgba-to-png.js';
+import { formatJson } from '@quenty/cli-output-helpers/reporting';
+
+export interface ScreenshotResult {
+  data: string;
+  width: number;
+  height: number;
+  summary: string;
+}
+
+export interface ScreenshotOptions {
+  output?: string;
+}
+
+export async function captureScreenshotHandlerAsync(
+  session: BridgeSession,
+  _options: ScreenshotOptions = {}
+): Promise<ScreenshotResult> {
+  const result: BridgeScreenshotResult = await session.captureScreenshotAsync();
+
+  let pngBase64: string;
+  if (result.format === 'rgba') {
+    const rgbaBuffer = Buffer.from(result.data, 'base64');
+    const pngBuffer = rgbaToPng(rgbaBuffer, result.width, result.height);
+    pngBase64 = pngBuffer.toString('base64');
+  } else {
+    pngBase64 = result.data ?? '';
+  }
+
+  return {
+    data: pngBase64,
+    width: result.width ?? 0,
+    height: result.height ?? 0,
+    summary: `Screenshot captured (${result.width ?? 0}x${result.height ?? 0})`,
+  };
+}
+
+export const screenshotCommand = defineCommand<
+  ScreenshotOptions,
+  ScreenshotResult
+>({
+  group: 'viewport',
+  name: 'screenshot',
+  description: 'Capture a viewport screenshot from Studio',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {},
+  cli: {
+    binaryField: 'data',
+    format: (result) => result.summary,
+    json: (result) =>
+      formatJson(
+        {
+          width: result.width,
+          height: result.height,
+          summary: result.summary,
+        },
+        { pretty: process.stdout.isTTY }
+      ),
+  },
+  handler: async (session) => captureScreenshotHandlerAsync(session),
+});

package/src/docker/docker-delegator.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock execa and fs before importing the module
+vi.mock('execa', () => ({
+  execa: vi.fn(),
+}));
+
+vi.mock('fs/promises', () => ({
+  writeFile: vi.fn().mockResolvedValue(undefined),
+  unlink: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('@quenty/cli-output-helpers', () => ({
+  OutputHelper: {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    verbose: vi.fn(),
+  },
+}));
+
+import { execa } from 'execa';
+import {
+  shouldDelegateToDockerAsync,
+  buildDockerRunArgsAsync,
+} from './docker-delegator.js';
+import type { ExecuteScriptOptions } from '../cli/script-executor.js';
+
+const mockedExeca = vi.mocked(execa);
+
+describe('shouldDelegateToDockerAsync', () => {
+  const originalPlatform = process.platform;
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    Object.defineProperty(process, 'platform', { value: originalPlatform });
+  });
+
+  it('returns false on non-Linux platforms', async () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    expect(await shouldDelegateToDockerAsync()).toBe(false);
+  });
+
+  it('returns false when Wine is available on Linux', async () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    mockedExeca.mockResolvedValueOnce({ exitCode: 0 } as any);
+    expect(await shouldDelegateToDockerAsync()).toBe(false);
+  });
+
+  it('returns true when Wine is missing but Docker is available', async () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    mockedExeca.mockRejectedValueOnce(new Error('wine not found'));
+    mockedExeca.mockResolvedValueOnce({ exitCode: 0 } as any);
+    expect(await shouldDelegateToDockerAsync()).toBe(true);
+  });
+
+  it('returns false when neither Wine nor Docker is available', async () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    mockedExeca.mockRejectedValueOnce(new Error('wine not found'));
+    mockedExeca.mockRejectedValueOnce(new Error('docker not found'));
+    expect(await shouldDelegateToDockerAsync()).toBe(false);
+  });
+});
+
+describe('buildDockerRunArgsAsync', () => {
+  const cwd = '/workspace/project';
+  const cookie = 'test-cookie';
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('builds correct args for inline script', async () => {
+    const options: ExecuteScriptOptions = {
+      scriptContent: 'print("hello")',
+      packageName: 'studio-bridge',
+      timeoutMs: 120_000,
+      verbose: false,
+      showLogs: true,
+    };
+
+    const args = await buildDockerRunArgsAsync(options, cwd, cookie);
+
+    expect(args).toContain('--rm');
+    expect(args).toContain('--init');
+    // Cookie value must NOT appear in argv; docker reads it from its own env
+    expect(args).toContain('ROBLOSECURITY');
+    expect(args).not.toContain(`ROBLOSECURITY=${cookie}`);
+    expect(args.every((a) => !a.includes(cookie))).toBe(true);
+    expect(args).toContain(`${cwd}:${cwd}`);
+    expect(args).toContain(cwd);
+    expect(args).toContain('ghcr.io/quenty/nevermore-studio-linux:latest');
+    // Inner command should include auth then run
+    const bashCmd = args[args.length - 1];
+    expect(bashCmd).toContain('studio-bridge linux inject-credentials');
+    expect(bashCmd).toContain('studio-bridge process run');
+    expect(bashCmd).toContain('--timeout 120000');
+    expect(bashCmd).not.toContain('--verbose');
+  });
+
+  it('passes --verbose through to inner command', async () => {
+    const options: ExecuteScriptOptions = {
+      scriptContent: 'print("hello")',
+      packageName: 'studio-bridge',
+      timeoutMs: 60_000,
+      verbose: true,
+      showLogs: true,
+    };
+
+    const args = await buildDockerRunArgsAsync(options, cwd, cookie);
+    const bashCmd = args[args.length - 1];
+    expect(bashCmd).toContain('--verbose');
+  });
+
+  it('passes --place through when specified', async () => {
+    const options: ExecuteScriptOptions = {
+      scriptContent: 'print("hello")',
+      packageName: 'studio-bridge',
+      placePath: '/workspace/project/test.rbxl',
+      timeoutMs: 120_000,
+      verbose: false,
+      showLogs: true,
+    };
+
+    const args = await buildDockerRunArgsAsync(options, cwd, cookie);
+    const bashCmd = args[args.length - 1];
+    expect(bashCmd).toContain('--place /workspace/project/test.rbxl');
+  });
+
+  it('uses original file path when filePath is set', async () => {
+    const options: ExecuteScriptOptions = {
+      scriptContent: 'print("hello")',
+      packageName: 'studio-bridge',
+      timeoutMs: 120_000,
+      verbose: false,
+      showLogs: true,
+      filePath: '/workspace/project/script.lua',
+    };
+
+    const args = await buildDockerRunArgsAsync(options, cwd, cookie);
+    const bashCmd = args[args.length - 1];
+    expect(bashCmd).toContain('--file /workspace/project/script.lua');
+  });
+
+  it('calculates docker timeout with 60s buffer', async () => {
+    const options: ExecuteScriptOptions = {
+      scriptContent: 'print("hello")',
+      packageName: 'studio-bridge',
+      timeoutMs: 120_000,
+      verbose: false,
+      showLogs: true,
+    };
+
+    const args = await buildDockerRunArgsAsync(options, cwd, cookie);
+    const stopIdx = args.indexOf('--stop-timeout');
+    expect(stopIdx).toBeGreaterThan(-1);
+    expect(args[stopIdx + 1]).toBe('180'); // (120000 + 60000) / 1000
+  });
+});