@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/commands/console/exec/exec.ts

@@ -0,0 +1,130 @@
+/**
+ * `console exec` — execute Luau code in a connected Studio session.
+ *
+ * Accepts inline code (positional), a file path (`--file`), or stdin.
+ * This unifies the old `exec` and `run` commands.
+ */
+
+import * as fs from 'fs/promises';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+
+export interface ExecOptions {
+  scriptContent: string;
+  timeout?: number;
+}
+
+export interface ExecResult {
+  success: boolean;
+  output: string[];
+  error?: string;
+  summary: string;
+}
+
+export interface RunOptions {
+  scriptPath: string;
+  timeout?: number;
+}
+
+export interface RunResult {
+  success: boolean;
+  output: string[];
+  error?: string;
+  summary: string;
+}
+
+interface ConsoleExecArgs {
+  code?: string;
+  file?: string;
+  timeout?: number;
+}
+
+/**
+ * Execute inline Luau code in a connected Studio session.
+ */
+export async function execHandlerAsync(
+  session: BridgeSession,
+  options: ExecOptions
+): Promise<ExecResult> {
+  const result = await session.execAsync(
+    options.scriptContent,
+    options.timeout
+  );
+
+  const output = (result.output ?? []).map((entry) =>
+    typeof entry === 'string' ? entry : entry.body
+  );
+
+  return {
+    success: result.success,
+    output,
+    error: result.error,
+    summary: result.success
+      ? 'Script executed successfully'
+      : `Script failed: ${result.error}`,
+  };
+}
+
+/**
+ * Read a Luau script file and execute it in a connected Studio session.
+ */
+export async function runHandlerAsync(
+  session: BridgeSession,
+  options: RunOptions
+): Promise<RunResult> {
+  const scriptContent = await fs.readFile(options.scriptPath, 'utf-8');
+  const result = await session.execAsync(scriptContent, options.timeout);
+
+  const output = (result.output ?? []).map((entry) =>
+    typeof entry === 'string' ? entry : entry.body
+  );
+
+  return {
+    success: result.success,
+    output,
+    error: result.error,
+    summary: result.success
+      ? `Script ${options.scriptPath} executed successfully`
+      : `Script ${options.scriptPath} failed: ${result.error}`,
+  };
+}
+
+export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
+  group: 'console',
+  name: 'exec',
+  description: 'Execute Luau code in a connected Studio session',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'session',
+  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',
+    }),
+    timeout: arg.option({
+      description: 'Execution timeout in milliseconds',
+      type: 'number',
+    }),
+  },
+  cli: {
+    format: (result) => {
+      const lines = result.output.join('\n');
+      if (result.error) return lines + (lines ? '\n' : '') + result.error;
+      return lines || result.summary;
+    },
+  },
+  handler: async (session, args) => {
+    const { scriptContent } = await resolveScriptContentAsync(args);
+
+    return execHandlerAsync(session, {
+      scriptContent,
+      timeout: args.timeout,
+    });
+  },
+});

package/src/commands/console/exec/execute.luau

@@ -0,0 +1,202 @@
+--[[
+	Execute action handler for the studio-bridge plugin.
+
+	Compiles and runs Luau code received from the server, returning a
+	scriptComplete response on success or an error response on failure.
+
+	Supports:
+	  - requestId correlation: if present in the request, echoed in all
+	    response messages (scriptComplete and output).
+	  - Distinct error codes: SCRIPT_LOAD_ERROR, SCRIPT_RUNTIME_ERROR.
+	  - Sequential queueing: concurrent execute requests are processed
+	    one at a time in FIFO order.
+
+	This module has no Roblox dependencies and is testable under Lune.
+]]
+
+local ExecuteAction = {}
+
+-- ---------------------------------------------------------------------------
+-- Internal queue for sequential execution
+-- ---------------------------------------------------------------------------
+
+local _queue: { { payload: { [string]: any }, requestId: string?, sessionId: string, sendMessage: ((msg: { [string]: any }) -> ())? } } =
+	{}
+local _processing = false
+
+-- ---------------------------------------------------------------------------
+-- Core execution logic
+-- ---------------------------------------------------------------------------
+
+-- Handle an execute request by compiling and running the provided code.
+-- Captures print/warn output by temporarily intercepting the globals.
+function ExecuteAction._handleExecute(
+	payload: { [string]: any },
+	requestId: string?,
+	sessionId: string,
+	sendMessage: ((msg: { [string]: any }) -> ())?
+): { [string]: any }?
+	local code = payload and (payload.script or payload.code)
+
+	-- Normalize requestId: treat empty string as absent (v1 compatibility)
+	local effectiveRequestId: string? = nil
+	if requestId ~= nil and requestId ~= "" then
+		effectiveRequestId = requestId
+	end
+
+	-- Helper to build response messages with optional requestId
+	local function buildResponse(responsePayload: { [string]: any }): { [string]: any }
+		local msg: { [string]: any } = {
+			type = "scriptComplete",
+			sessionId = sessionId,
+			payload = responsePayload,
+		}
+		if effectiveRequestId then
+			msg.requestId = effectiveRequestId
+		end
+		return msg
+	end
+
+	-- Helper to send or return the result
+	local function sendResult(responsePayload: { [string]: any }): { [string]: any }?
+		if sendMessage then
+			sendMessage(buildResponse(responsePayload))
+			return nil
+		end
+		return responsePayload
+	end
+
+	if not code or type(code) ~= "string" then
+		return sendResult({ success = false, error = "Missing code in execute request", code = "SCRIPT_LOAD_ERROR" })
+	end
+
+	local compileOk, fnOrErr = pcall(loadstring, code)
+	if not compileOk then
+		return sendResult({ success = false, error = tostring(fnOrErr), code = "SCRIPT_LOAD_ERROR" })
+	end
+	if not fnOrErr then
+		return sendResult({ success = false, error = "Failed to compile script", code = "SCRIPT_LOAD_ERROR" })
+	end
+
+	local fn = fnOrErr
+
+	-- Capture output by temporarily intercepting print/warn in the global
+	-- environment. Local variable shadowing doesn't work because loadstring'd
+	-- code accesses the global environment, not this module's locals.
+	local captured: { { level: string, body: string, timestamp: number } } = {}
+	local env = getfenv(fn)
+	local originalPrint = env.print
+	local originalWarn = env.warn
+
+	env.print = function(...)
+		local parts = {}
+		for i = 1, select("#", ...) do
+			parts[i] = tostring(select(i, ...))
+		end
+		local body = table.concat(parts, "\t")
+		table.insert(captured, { level = "Print", body = body, timestamp = os.clock() })
+		originalPrint(...)
+	end
+
+	env.warn = function(...)
+		local parts = {}
+		for i = 1, select("#", ...) do
+			parts[i] = tostring(select(i, ...))
+		end
+		local body = table.concat(parts, "\t")
+		table.insert(captured, { level = "Warning", body = body, timestamp = os.clock() })
+		originalWarn(...)
+	end
+
+	local success, runtimeError = pcall(fn)
+
+	-- Restore originals
+	env.print = originalPrint
+	env.warn = originalWarn
+
+	if not success then
+		return sendResult({ success = false, error = tostring(runtimeError), code = "SCRIPT_RUNTIME_ERROR", output = captured })
+	end
+
+	return sendResult({ success = true, output = captured })
+end
+
+-- ---------------------------------------------------------------------------
+-- Queue processing
+-- ---------------------------------------------------------------------------
+
+local function _processQueue()
+	if _processing then
+		return
+	end
+	_processing = true
+
+	while #_queue > 0 do
+		local item = table.remove(_queue, 1)
+		ExecuteAction._handleExecute(item.payload, item.requestId, item.sessionId, item.sendMessage)
+	end
+
+	_processing = false
+end
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+-- Register this handler with the ActionRouter.
+function ExecuteAction.register(router: any, sendMessage: ((msg: { [string]: any }) -> ())?)
+	router:setResponseType("execute", "scriptComplete")
+	router:register("execute", function(payload: { [string]: any }, requestId: string, sessionId: string)
+		if sendMessage then
+			-- Queue the request for sequential processing
+			table.insert(_queue, {
+				payload = payload,
+				requestId = requestId,
+				sessionId = sessionId,
+				sendMessage = sendMessage,
+			})
+			_processQueue()
+			-- Return nil so the ActionRouter does not generate a response
+			return nil
+		else
+			-- Direct mode (no sendMessage): return payload for ActionRouter wrapping
+			return ExecuteAction._handleExecute(payload, requestId, sessionId, nil)
+		end
+	end)
+end
+
+-- Handle an execute request directly (for testing without ActionRouter).
+function ExecuteAction.handleExecute(
+	payload: { [string]: any },
+	requestId: string?,
+	sessionId: string
+): { [string]: any }?
+	return ExecuteAction._handleExecute(payload, requestId, sessionId, nil)
+end
+
+-- Reset the internal queue state (for testing).
+function ExecuteAction._resetQueue()
+	_queue = {}
+	_processing = false
+end
+
+function ExecuteAction.teardown()
+	for _, item in _queue do
+		if item.sendMessage then
+			item.sendMessage({
+				type = "scriptComplete",
+				sessionId = item.sessionId,
+				requestId = item.requestId,
+				payload = {
+					success = false,
+					error = "Action re-registered, request cancelled",
+					code = "ACTION_REPLACED",
+				},
+			})
+		end
+	end
+	_queue = {}
+	_processing = false
+end
+
+return ExecuteAction

package/src/commands/console/logs/logs.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Unit tests for the logs command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { queryLogsHandlerAsync } from './logs.js';
+
+function createMockSession(logsResult: {
+  entries: Array<{ level: string; body: string; timestamp: number }>;
+  total: number;
+  bufferCapacity: number;
+}) {
+  return {
+    queryLogsAsync: vi.fn().mockResolvedValue(logsResult),
+  } as any;
+}
+
+describe('queryLogsHandlerAsync', () => {
+  it('returns log entries with summary', async () => {
+    const session = createMockSession({
+      entries: [
+        { level: 'Print', body: 'Hello world', timestamp: 1000 },
+        { level: 'Warning', body: 'Watch out', timestamp: 2000 },
+      ],
+      total: 42,
+      bufferCapacity: 1000,
+    });
+
+    const result = await queryLogsHandlerAsync(session);
+
+    expect(result.entries).toHaveLength(2);
+    expect(result.total).toBe(42);
+    expect(result.bufferCapacity).toBe(1000);
+    expect(result.summary).toBe('2 entries (42 total in buffer)');
+  });
+
+  it('passes default options to session', async () => {
+    const session = createMockSession({
+      entries: [],
+      total: 0,
+      bufferCapacity: 1000,
+    });
+
+    await queryLogsHandlerAsync(session);
+
+    expect(session.queryLogsAsync).toHaveBeenCalledWith({
+      count: 50,
+      direction: 'tail',
+      levels: undefined,
+      includeInternal: undefined,
+    });
+  });
+
+  it('passes custom options to session', async () => {
+    const session = createMockSession({
+      entries: [],
+      total: 0,
+      bufferCapacity: 500,
+    });
+
+    await queryLogsHandlerAsync(session, {
+      count: 100,
+      direction: 'head',
+      levels: ['Error', 'Warning'],
+      includeInternal: true,
+    });
+
+    expect(session.queryLogsAsync).toHaveBeenCalledWith({
+      count: 100,
+      direction: 'head',
+      levels: ['Error', 'Warning'],
+      includeInternal: true,
+    });
+  });
+
+  it('handles empty entries', async () => {
+    const session = createMockSession({
+      entries: [],
+      total: 0,
+      bufferCapacity: 1000,
+    });
+
+    const result = await queryLogsHandlerAsync(session);
+
+    expect(result.entries).toEqual([]);
+    expect(result.total).toBe(0);
+    expect(result.summary).toBe('0 entries (0 total in buffer)');
+  });
+
+  it('handles entries with all log levels', async () => {
+    const entries = [
+      { level: 'Print', body: 'info message', timestamp: 1000 },
+      { level: 'Info', body: 'info message', timestamp: 2000 },
+      { level: 'Warning', body: 'warning message', timestamp: 3000 },
+      { level: 'Error', body: 'error message', timestamp: 4000 },
+    ];
+    const session = createMockSession({
+      entries,
+      total: 4,
+      bufferCapacity: 1000,
+    });
+
+    const result = await queryLogsHandlerAsync(session);
+
+    expect(result.entries).toHaveLength(4);
+    expect(result.entries[0].level).toBe('Print');
+    expect(result.entries[1].level).toBe('Info');
+    expect(result.entries[2].level).toBe('Warning');
+    expect(result.entries[3].level).toBe('Error');
+  });
+
+  it('propagates errors from session', async () => {
+    const session = {
+      queryLogsAsync: vi.fn().mockRejectedValue(new Error('Connection lost')),
+    } as any;
+
+    await expect(queryLogsHandlerAsync(session)).rejects.toThrow(
+      'Connection lost'
+    );
+  });
+
+  it('handles missing fields gracefully', async () => {
+    const session = {
+      queryLogsAsync: vi.fn().mockResolvedValue({
+        entries: undefined,
+        total: undefined,
+        bufferCapacity: undefined,
+      }),
+    } as any;
+
+    const result = await queryLogsHandlerAsync(session);
+
+    expect(result.entries).toEqual([]);
+    expect(result.total).toBe(0);
+    expect(result.bufferCapacity).toBe(0);
+    expect(result.summary).toBe('0 entries (0 total in buffer)');
+  });
+});

package/src/commands/console/logs/logs.ts

@@ -0,0 +1,115 @@
+/**
+ * `console logs` — retrieve buffered log history from a connected
+ * Studio session's ring buffer.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type {
+  LogEntry,
+  LogsResult as BridgeLogsResult,
+} from '../../../bridge/index.js';
+import type { OutputLevel } from '../../../server/web-socket-protocol.js';
+
+export interface LogsResult {
+  entries: LogEntry[];
+  total: number;
+  bufferCapacity: number;
+  summary: string;
+}
+
+export interface LogsOptions {
+  count?: number;
+  direction?: 'head' | 'tail';
+  levels?: OutputLevel[];
+  includeInternal?: boolean;
+}
+
+export async function queryLogsHandlerAsync(
+  session: BridgeSession,
+  options: LogsOptions = {}
+): Promise<LogsResult> {
+  const result: BridgeLogsResult = await session.queryLogsAsync({
+    count: options.count ?? 50,
+    direction: options.direction ?? 'tail',
+    levels: options.levels,
+    includeInternal: options.includeInternal,
+  });
+
+  return {
+    entries: result.entries ?? [],
+    total: result.total ?? 0,
+    bufferCapacity: result.bufferCapacity ?? 0,
+    summary: `${(result.entries ?? []).length} entries (${
+      result.total ?? 0
+    } total in buffer)`,
+  };
+}
+
+function colorizeLevel(level: OutputLevel): string {
+  switch (level) {
+    case 'Error':
+      return OutputHelper.formatError(level);
+    case 'Warning':
+      return OutputHelper.formatWarning(level);
+    default:
+      return level;
+  }
+}
+
+export function formatLogsText(result: LogsResult): string {
+  if (result.entries.length === 0) return result.summary;
+  const lines = result.entries.map((e) => {
+    const ts = OutputHelper.formatDim(
+      new Date(e.timestamp).toLocaleTimeString()
+    );
+    const level = colorizeLevel(e.level);
+    return `[${ts}] [${level}] ${e.body}`;
+  });
+  lines.push(
+    OutputHelper.formatDim(
+      `(${result.entries.length} of ${result.total} entries)`
+    )
+  );
+  return lines.join('\n');
+}
+
+export const logsCommand = defineCommand<LogsOptions, LogsResult>({
+  group: 'console',
+  name: 'logs',
+  description: 'Retrieve buffered log history from Studio',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {
+    count: arg.option({
+      description: 'Number of log entries to return',
+      type: 'number',
+      alias: 'n',
+    }),
+    direction: arg.option({
+      description: 'Read from head (oldest) or tail (newest)',
+      choices: ['head', 'tail'] as const,
+    }),
+    levels: arg.option({
+      description: 'Filter by output level (Print, Warning, Error)',
+      array: true,
+    }),
+    includeInternal: arg.flag({
+      description: 'Include internal/system log messages',
+    }),
+  },
+  cli: {
+    format: formatLogsText,
+  },
+  handler: async (session, args) => {
+    return queryLogsHandlerAsync(session, {
+      count: args.count as number | undefined,
+      direction: args.direction as 'head' | 'tail' | undefined,
+      levels: args.levels as OutputLevel[] | undefined,
+      includeInternal: args.includeInternal as boolean | undefined,
+    });
+  },
+});

package/src/commands/console/logs/query-logs.luau

@@ -0,0 +1,76 @@
+--[[
+	QueryLogs action handler for the studio-bridge plugin.
+
+	Reads from a MessageBuffer instance and returns filtered log entries.
+	Supports direction (head/tail), count, level filtering, and
+	includeInternal (to show/hide [StudioBridge] messages).
+
+	Protocol:
+	  Request:  { type: "queryLogs", payload: { count?, direction?, levels?, includeInternal? } }
+	  Response: { type: "logsResult", payload: { entries, total, bufferCapacity } }
+]]
+
+local QueryLogsAction = {}
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+-- Register this handler with the ActionRouter.
+function QueryLogsAction.register(router: any, _sendMessage: any, logBuffer: any)
+	router:setResponseType("queryLogs", "logsResult")
+	router:register("queryLogs", function(payload: { [string]: any }, _requestId: string, _sessionId: string)
+		local direction = payload.direction or "tail"
+		local count = payload.count or 50
+		local levels = payload.levels -- nil means all levels
+		local includeInternal = payload.includeInternal == true
+
+		-- Get raw entries from the buffer
+		local result = logBuffer:get(direction, nil) -- get all, then filter
+
+		local filtered = {}
+		for _, entry in result.entries do
+			-- Filter by includeInternal
+			if not includeInternal and string.sub(entry.body, 1, 14) == "[StudioBridge]" then
+				continue
+			end
+
+			-- Filter by levels
+			if levels and #levels > 0 then
+				local matched = false
+				for _, level in levels do
+					if entry.level == level then
+						matched = true
+						break
+					end
+				end
+				if not matched then
+					continue
+				end
+			end
+
+			table.insert(filtered, entry)
+		end
+
+		-- Apply direction and count to filtered results
+		local entries = {}
+		if direction == "head" then
+			for i = 1, math.min(count, #filtered) do
+				table.insert(entries, filtered[i])
+			end
+		else
+			local start = math.max(1, #filtered - count + 1)
+			for i = start, #filtered do
+				table.insert(entries, filtered[i])
+			end
+		end
+
+		return {
+			entries = entries,
+			total = result.total,
+			bufferCapacity = result.bufferCapacity,
+		}
+	end)
+end
+
+return QueryLogsAction

package/src/commands/disconnect.test.ts

@@ -0,0 +1,21 @@
+/**
+ * Unit tests for the disconnect command handler.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { disconnectHandler } from './disconnect.js';
+
+describe('disconnectHandler', () => {
+  it('returns a summary message', () => {
+    const result = disconnectHandler();
+
+    expect(result.summary).toBe('Disconnected from session.');
+  });
+
+  it('returns an object with summary field', () => {
+    const result = disconnectHandler();
+
+    expect(result).toHaveProperty('summary');
+    expect(typeof result.summary).toBe('string');
+  });
+});

package/src/commands/disconnect.ts

@@ -0,0 +1,12 @@
+/**
+ * Handler for the `disconnect` command. Signals disconnection from
+ * the active session in terminal mode.
+ */
+
+export interface DisconnectResult {
+  summary: string;
+}
+
+export function disconnectHandler(): DisconnectResult {
+  return { summary: 'Disconnected from session.' };
+}