@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/commands/process/list/list.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Unit tests for the list (sessions) command handler.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { SessionInfo } from '../../../bridge/index.js';
+import { listSessionsHandlerAsync } from './list.js';
+
+function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: 'session-1',
+    placeName: 'TestPlace',
+    state: 'Edit',
+    pluginVersion: '1.0.0',
+    capabilities: ['execute', 'queryState'],
+    connectedAt: new Date(),
+    origin: 'user',
+    context: 'edit',
+    instanceId: 'inst-1',
+    placeId: 123,
+    gameId: 456,
+    ...overrides,
+  };
+}
+
+function createMockConnection(sessions: SessionInfo[]) {
+  return {
+    listSessions: () => sessions,
+    getSession: (id: string) => sessions.find((s) => s.sessionId === id),
+  } as any;
+}
+
+describe('listSessionsHandlerAsync', () => {
+  it('returns empty sessions with helpful message', async () => {
+    const conn = createMockConnection([]);
+    const result = await listSessionsHandlerAsync(conn);
+
+    expect(result.sessions).toEqual([]);
+    expect(result.summary).toContain('No active sessions');
+    expect(result.summary).toContain('studio-bridge plugin');
+  });
+
+  it('returns sessions with count summary', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 's1' }),
+      createSessionInfo({ sessionId: 's2' }),
+    ];
+    const conn = createMockConnection(sessions);
+    const result = await listSessionsHandlerAsync(conn);
+
+    expect(result.sessions).toHaveLength(2);
+    expect(result.summary).toBe('2 session(s) connected.');
+  });
+
+  it('returns single session with correct summary', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'only-one' })];
+    const conn = createMockConnection(sessions);
+    const result = await listSessionsHandlerAsync(conn);
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.summary).toBe('1 session(s) connected.');
+  });
+
+  it('sessions data includes expected fields', async () => {
+    const session = createSessionInfo({
+      sessionId: 'test-id',
+      placeName: 'MyPlace',
+      context: 'server',
+      state: 'Play',
+      origin: 'managed',
+    });
+    const conn = createMockConnection([session]);
+    const result = await listSessionsHandlerAsync(conn);
+
+    const s = result.sessions[0];
+    expect(s.sessionId).toBe('test-id');
+    expect(s.placeName).toBe('MyPlace');
+    expect(s.context).toBe('server');
+    expect(s.state).toBe('Play');
+    expect(s.origin).toBe('managed');
+  });
+});

package/src/commands/process/list/list.ts

@@ -0,0 +1,75 @@
+/**
+ * `process list` — list connected Studio sessions.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  formatTable,
+  type TableColumn,
+} from '@quenty/cli-output-helpers/reporting';
+import type { BridgeConnection } from '../../../bridge/index.js';
+import type { SessionInfo } from '../../../bridge/index.js';
+import type { StudioState } from '../../../server/web-socket-protocol.js';
+import { colorizeState } from '../format-state.js';
+
+export interface SessionsResult {
+  sessions: SessionInfo[];
+  summary: string;
+}
+
+/**
+ * List all connected Studio sessions with a summary message.
+ */
+export async function listSessionsHandlerAsync(
+  connection: BridgeConnection
+): Promise<SessionsResult> {
+  const sessions = connection.listSessions();
+
+  if (sessions.length === 0) {
+    return {
+      sessions: [],
+      summary:
+        'No active sessions. Is Studio running with the studio-bridge plugin?',
+    };
+  }
+
+  return {
+    sessions,
+    summary: `${sessions.length} session(s) connected.`,
+  };
+}
+
+const sessionColumns: TableColumn<SessionInfo>[] = [
+  {
+    header: 'Session',
+    value: (s) => s.sessionId.slice(0, 8),
+    format: (v) => OutputHelper.formatHint(v),
+  },
+  { header: 'Context', value: (s) => s.context },
+  { header: 'Place', value: (s) => s.placeName },
+  {
+    header: 'State',
+    value: (s) => s.state,
+    format: (v) => colorizeState(v as StudioState),
+  },
+];
+
+export function formatSessionsTable(result: SessionsResult): string {
+  if (result.sessions.length === 0) return result.summary;
+  return formatTable(result.sessions, sessionColumns);
+}
+
+export const listCommand = defineCommand({
+  group: 'process',
+  name: 'list',
+  description: 'List connected Studio sessions',
+  category: 'infrastructure',
+  safety: 'read',
+  scope: 'connection',
+  args: {},
+  cli: {
+    format: formatSessionsTable,
+  },
+  handler: async (connection) => listSessionsHandlerAsync(connection),
+});

package/src/commands/process/run/run.ts

@@ -0,0 +1,98 @@
+/**
+ * `process run` -- explicit ephemeral mode: launch Studio, execute code,
+ * then tear down. Wraps the StudioBridgeServer lifecycle with full
+ * reporter output.
+ *
+ * This is standalone (no existing connection needed) and is CLI-only.
+ * MCP does NOT expose this command.
+ */
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
+
+export interface ProcessRunOptions {
+  scriptContent: string;
+  packageName: string;
+  placePath?: string;
+  timeoutMs: number;
+  verbose: boolean;
+  showLogs: boolean;
+  filePath?: string;
+}
+
+export interface ProcessRunResult {
+  success: boolean;
+  summary: string;
+}
+
+interface ProcessRunArgs {
+  code?: string;
+  file?: string;
+  place?: string;
+  timeout?: number;
+}
+
+export async function processRunHandlerAsync(
+  options: ProcessRunOptions
+): Promise<ProcessRunResult> {
+  // Lazy import to avoid pulling in StudioBridgeServer at module load
+  const { executeScriptAsync } = await import(
+    '../../../cli/script-executor.js'
+  );
+
+  // executeScriptAsync calls process.exit internally, so this return
+  // is only reachable in test scenarios where it's mocked.
+  await executeScriptAsync(options);
+
+  return {
+    success: true,
+    summary: 'Script execution completed.',
+  };
+}
+
+export const processRunCommand = defineCommand<
+  ProcessRunArgs,
+  ProcessRunResult
+>({
+  group: 'process',
+  name: 'run',
+  description:
+    'Launch Studio, execute a script, and shut down (ephemeral mode)',
+  category: 'execution',
+  safety: 'none',
+  scope: 'standalone',
+  args: {
+    code: arg.positional({
+      description: 'Inline Luau code to execute',
+      required: false,
+    }),
+    file: arg.option({
+      description: 'Path to a Luau script file to execute',
+      alias: 'f',
+    }),
+    place: arg.option({
+      description: 'Path to a .rbxl place file',
+      alias: 'p',
+    }),
+    timeout: arg.option({
+      description: 'Execution timeout in milliseconds',
+      type: 'number',
+    }),
+  },
+  handler: async (args) => {
+    const { scriptContent, filePath } = await resolveScriptContentAsync(args);
+
+    return processRunHandlerAsync({
+      scriptContent,
+      packageName: 'studio-bridge',
+      placePath: args.place,
+      timeoutMs: args.timeout ?? 120_000,
+      verbose: OutputHelper.isVerbose(),
+      showLogs: true,
+      filePath,
+    });
+  },
+  // No MCP config -- process run is CLI-only
+});

package/src/commands/rgba-to-png.ts

@@ -0,0 +1,98 @@
+/**
+ * Minimal PNG encoder that converts raw RGBA pixel data into a valid PNG file.
+ *
+ * Uses only Node.js built-ins (zlib, Buffer). Produces unfiltered scanlines
+ * (filter byte 0 per row) compressed with deflate — not optimal file size,
+ * but correct and dependency-free.
+ */
+
+import { deflateSync } from 'zlib';
+
+// PNG uses network byte order (big-endian)
+function writeU32BE(buf: Buffer, offset: number, value: number): void {
+  buf[offset] = (value >>> 24) & 0xff;
+  buf[offset + 1] = (value >>> 16) & 0xff;
+  buf[offset + 2] = (value >>> 8) & 0xff;
+  buf[offset + 3] = value & 0xff;
+}
+
+// CRC-32 lookup table (ISO 3309 / ITU-T V.42 polynomial)
+const CRC_TABLE: Uint32Array = new Uint32Array(256);
+for (let n = 0; n < 256; n++) {
+  let c = n;
+  for (let k = 0; k < 8; k++) {
+    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  }
+  CRC_TABLE[n] = c >>> 0;
+}
+
+function crc32(data: Buffer): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < data.length; i++) {
+    crc = CRC_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Build a PNG chunk: length(4) + type(4) + data + crc32(4). */
+function makeChunk(type: string, data: Buffer): Buffer {
+  const typeBytes = Buffer.from(type, 'ascii');
+  const chunk = Buffer.alloc(4 + 4 + data.length + 4);
+  writeU32BE(chunk, 0, data.length);
+  typeBytes.copy(chunk, 4);
+  data.copy(chunk, 8);
+  // CRC covers type + data
+  const crcInput = Buffer.alloc(4 + data.length);
+  typeBytes.copy(crcInput, 0);
+  data.copy(crcInput, 4);
+  writeU32BE(chunk, 8 + data.length, crc32(crcInput));
+  return chunk;
+}
+
+/**
+ * Convert raw RGBA pixel data to a PNG file buffer.
+ *
+ * @param rgba - Raw RGBA bytes (4 bytes per pixel, row-major, top-to-bottom)
+ * @param width - Image width in pixels
+ * @param height - Image height in pixels
+ * @returns A Buffer containing a valid PNG file
+ */
+export function rgbaToPng(rgba: Buffer, width: number, height: number): Buffer {
+  const expectedBytes = width * height * 4;
+  if (rgba.length !== expectedBytes) {
+    throw new Error(
+      `RGBA data length mismatch: expected ${expectedBytes} bytes (${width}x${height}x4), got ${rgba.length}`
+    );
+  }
+
+  // PNG signature
+  const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+  // IHDR: width(4) + height(4) + bitDepth(1) + colorType(1) + compression(1) + filter(1) + interlace(1)
+  const ihdrData = Buffer.alloc(13);
+  writeU32BE(ihdrData, 0, width);
+  writeU32BE(ihdrData, 4, height);
+  ihdrData[8] = 8; // 8 bits per channel
+  ihdrData[9] = 6; // RGBA color type
+  ihdrData[10] = 0; // deflate compression
+  ihdrData[11] = 0; // adaptive filtering
+  ihdrData[12] = 0; // no interlace
+  const ihdr = makeChunk('IHDR', ihdrData);
+
+  // Build raw scanlines: each row gets a filter byte (0 = None) prefix
+  const rowBytes = width * 4;
+  const rawData = Buffer.alloc(height * (1 + rowBytes));
+  for (let y = 0; y < height; y++) {
+    const outOffset = y * (1 + rowBytes);
+    rawData[outOffset] = 0; // filter: None
+    rgba.copy(rawData, outOffset + 1, y * rowBytes, (y + 1) * rowBytes);
+  }
+
+  const compressed = deflateSync(rawData);
+  const idat = makeChunk('IDAT', compressed);
+
+  // IEND: empty chunk
+  const iend = makeChunk('IEND', Buffer.alloc(0));
+
+  return Buffer.concat([signature, ihdr, idat, iend]);
+}

package/src/commands/serve/serve.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Unit tests for the serve command handler.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'events';
+
+// Mock BridgeConnection before importing serve handler
+vi.mock('../../bridge/index.js', () => {
+  return {
+    BridgeConnection: {
+      connectAsync: vi.fn(),
+    },
+  };
+});
+
+import { BridgeConnection } from '../../bridge/index.js';
+import { serveHandlerAsync } from './serve.js';
+
+function createMockConnection(port: number): EventEmitter & {
+  disconnectAsync: ReturnType<typeof vi.fn>;
+  port: number;
+} {
+  const emitter = new EventEmitter();
+  return Object.assign(emitter, {
+    disconnectAsync: vi.fn().mockResolvedValue(undefined),
+    port,
+  });
+}
+
+describe('serveHandlerAsync', () => {
+  let mockConnection: ReturnType<typeof createMockConnection>;
+  const connectAsyncMock = BridgeConnection.connectAsync as ReturnType<
+    typeof vi.fn
+  >;
+
+  beforeEach(() => {
+    mockConnection = createMockConnection(38741);
+    connectAsyncMock.mockResolvedValue(mockConnection);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('calls connectAsync with keepAlive true and correct port', async () => {
+    const promise = serveHandlerAsync({ port: 38741, timeout: 10 });
+    await promise;
+
+    expect(connectAsyncMock).toHaveBeenCalledWith({
+      port: 38741,
+      keepAlive: true,
+    });
+  });
+
+  it('uses default port 38741 when none specified', async () => {
+    const promise = serveHandlerAsync({ timeout: 10 });
+    await promise;
+
+    expect(connectAsyncMock).toHaveBeenCalledWith({
+      port: 38741,
+      keepAlive: true,
+    });
+  });
+
+  it('passes custom port through', async () => {
+    mockConnection = createMockConnection(9999);
+    connectAsyncMock.mockResolvedValue(mockConnection);
+
+    const promise = serveHandlerAsync({ port: 9999, timeout: 10 });
+    await promise;
+
+    expect(connectAsyncMock).toHaveBeenCalledWith({
+      port: 9999,
+      keepAlive: true,
+    });
+  });
+
+  it('throws clear error on EADDRINUSE', async () => {
+    const err = new Error('listen EADDRINUSE: address already in use');
+    (err as NodeJS.ErrnoException).code = 'EADDRINUSE';
+    connectAsyncMock.mockRejectedValue(err);
+
+    await expect(serveHandlerAsync({ port: 38741 })).rejects.toThrow(
+      'Port 38741 is already in use'
+    );
+  });
+
+  it('re-throws non-EADDRINUSE errors', async () => {
+    connectAsyncMock.mockRejectedValue(new Error('some other error'));
+
+    await expect(serveHandlerAsync({ port: 38741 })).rejects.toThrow(
+      'some other error'
+    );
+  });
+
+  it('disconnects after timeout expires', async () => {
+    const result = await serveHandlerAsync({ timeout: 10 });
+
+    expect(mockConnection.disconnectAsync).toHaveBeenCalled();
+    expect(result).toEqual({ port: 38741, event: 'stopped' });
+  });
+
+  it('logs JSON startup when json option is set', async () => {
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    await serveHandlerAsync({ json: true, timeout: 10 });
+
+    const startedCall = consoleSpy.mock.calls.find((call) => {
+      try {
+        const parsed = JSON.parse(call[0] as string);
+        return parsed.event === 'started';
+      } catch {
+        return false;
+      }
+    });
+
+    expect(startedCall).toBeDefined();
+    const parsed = JSON.parse(startedCall![0] as string);
+    expect(parsed.event).toBe('started');
+    expect(parsed.port).toBe(38741);
+
+    consoleSpy.mockRestore();
+  });
+
+  it('logs human-readable startup when json option is not set', async () => {
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    await serveHandlerAsync({ timeout: 10 });
+
+    const startedCall = consoleSpy.mock.calls.find((call) =>
+      (call[0] as string).includes('Bridge host listening')
+    );
+
+    expect(startedCall).toBeDefined();
+
+    consoleSpy.mockRestore();
+  });
+});

package/src/commands/serve/serve.ts

@@ -0,0 +1,161 @@
+/**
+ * `serve` — start a dedicated bridge host process that stays alive,
+ * accepting plugin and client connections.
+ */
+
+import { defineCommand } from '../framework/define-command.js';
+import { arg } from '../framework/arg-builder.js';
+import { BridgeConnection } from '../../bridge/index.js';
+import type { BridgeSession } from '../../bridge/index.js';
+
+export interface ServeOptions {
+  port?: number;
+  json?: boolean;
+  timeout?: number;
+}
+
+export interface ServeResult {
+  port: number;
+  event: string;
+}
+
+/** Blocks until shutdown signal or timeout. */
+export async function serveHandlerAsync(
+  options: ServeOptions = {}
+): Promise<ServeResult> {
+  const port = options.port ?? 38741;
+
+  let connection: BridgeConnection;
+  try {
+    connection = await BridgeConnection.connectAsync({
+      port,
+      keepAlive: true,
+    });
+  } catch (err: unknown) {
+    if (
+      err instanceof Error &&
+      'code' in err &&
+      (err as NodeJS.ErrnoException).code === 'EADDRINUSE'
+    ) {
+      throw new Error(
+        `Port ${port} is already in use. A bridge host is already running. ` +
+          `Connect as a client with any studio-bridge command, or use --port to start on a different port.`
+      );
+    }
+    throw err;
+  }
+
+  // Log startup
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        event: 'started',
+        port: connection.port,
+        timestamp: new Date().toISOString(),
+      })
+    );
+  } else {
+    console.log(`Bridge host listening on port ${connection.port}`);
+  }
+
+  // Set up event listeners for session changes
+  connection.on('session-connected', (session: BridgeSession) => {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          event: 'pluginConnected',
+          sessionId: session.info.sessionId,
+          context: session.info.context,
+          timestamp: new Date().toISOString(),
+        })
+      );
+    } else {
+      console.log(
+        `Plugin connected: ${session.info.sessionId} (${session.info.context})`
+      );
+    }
+  });
+
+  connection.on('session-disconnected', (sessionId: string) => {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          event: 'pluginDisconnected',
+          sessionId,
+          timestamp: new Date().toISOString(),
+        })
+      );
+    } else {
+      console.log(`Plugin disconnected: ${sessionId}`);
+    }
+  });
+
+  // Set up signal handlers
+  const shutdownAsync = async () => {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          event: 'shuttingDown',
+          timestamp: new Date().toISOString(),
+        })
+      );
+    } else {
+      console.log('Shutting down...');
+    }
+    await connection.disconnectAsync();
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          event: 'stopped',
+          timestamp: new Date().toISOString(),
+        })
+      );
+    } else {
+      console.log('Bridge host stopped.');
+    }
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => void shutdownAsync());
+  process.on('SIGINT', () => void shutdownAsync());
+  process.on('SIGHUP', () => {
+    /* ignore -- survive terminal close */
+  });
+
+  // Block until shutdown
+  if (options.timeout) {
+    // With timeout: auto-shutdown after idle period
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, options.timeout);
+    });
+    await connection.disconnectAsync();
+  } else {
+    // No timeout: block forever
+    await new Promise<void>(() => {
+      // Never resolves -- process runs until signal
+    });
+  }
+
+  return { port: connection.port, event: 'stopped' };
+}
+
+export const serveCommand = defineCommand<ServeOptions, ServeResult>({
+  group: null,
+  name: 'serve',
+  description: 'Start the bridge server',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {
+    port: arg.option({
+      description: 'Port to listen on (default: 38741)',
+      type: 'number',
+    }),
+    json: arg.flag({ description: 'Output events as JSON lines' }),
+    timeout: arg.option({
+      description: 'Auto-shutdown after N milliseconds',
+      type: 'number',
+    }),
+  },
+  handler: async (args) => serveHandlerAsync(args),
+});