@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/commands/console/exec/execute.spec.lua

@@ -0,0 +1,286 @@
+--!strict
+--[[
+	@class execute.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local ExecuteAction = require("execute")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function runScript(code: string): any
+	return ExecuteAction.handleExecute({ script = code }, "req-1", "session-1")
+end
+
+local function setup(useSendMessage: boolean): any
+	local router = ActionRouter.new()
+	local sent = {}
+
+	ExecuteAction.register(
+		router,
+		if useSendMessage
+			then function(message)
+				table.insert(sent, message)
+			end
+			else nil
+	)
+
+	local controller = {
+		router = router,
+		sent = sent,
+		execute = function(payload: { [string]: any }, requestId: string?)
+			return router:Dispatch({
+				type = "execute",
+				sessionId = "session-1",
+				payload = payload,
+				requestId = requestId,
+			})
+		end,
+		Destroy = function(_self)
+			ExecuteAction._resetQueue()
+		end,
+	}
+
+	return controller
+end
+
+describe("ExecuteAction.handleExecute()", function()
+	it("should report success with no return values", function()
+		local result = runScript("local _ = 1")
+
+		expect(result).toEqual({ success = true, output = {}, returnValues = {} })
+	end)
+
+	it("should capture print and warn output in order", function()
+		local result = runScript("print('hello', 1) warn('careful')")
+
+		expect(#result.output).toEqual(2)
+		expect(result.output[1].level).toEqual("Print")
+		expect(result.output[1].body).toEqual("hello 1")
+		expect(result.output[2].level).toEqual("Warning")
+		expect(result.output[2].body).toEqual("careful")
+	end)
+
+	it("should report the compiler's message for code that does not compile", function()
+		local result = runScript("local = ")
+
+		expect(result.success).toEqual(false)
+		expect(result.code).toEqual("SCRIPT_LOAD_ERROR")
+		expect(result.error).never.toEqual("Failed to compile script")
+	end)
+
+	it("should report a runtime error along with the output before it", function()
+		local result = runScript("print('before') error('boom')")
+
+		expect(result.success).toEqual(false)
+		expect(result.code).toEqual("SCRIPT_RUNTIME_ERROR")
+		expect(result.error).toContain("boom")
+		expect(result.output[1].body).toEqual("before")
+		expect(result.returnValues).toBeNil()
+	end)
+
+	it("should reject a request without code", function()
+		local result = ExecuteAction.handleExecute({}, "req-1", "session-1")
+
+		expect(result).toEqual({
+			success = false,
+			error = "Missing code in execute request",
+			code = "SCRIPT_LOAD_ERROR",
+		})
+	end)
+
+	it("should reject code that is not a string", function()
+		local result = ExecuteAction.handleExecute({ script = 5 }, "req-1", "session-1")
+
+		expect(result and result.code).toEqual("SCRIPT_LOAD_ERROR")
+	end)
+
+	it("should accept code under payload.code and prefer payload.script", function()
+		local fromCode = ExecuteAction.handleExecute({ code = "return 'code'" }, "req-1", "session-1")
+		local fromBoth =
+			ExecuteAction.handleExecute({ script = "return 'script'", code = "return 'code'" }, "req-1", "session-1")
+
+		expect(fromCode and fromCode.returnValues).toEqual({ "code" })
+		expect(fromBoth and fromBoth.returnValues).toEqual({ "script" })
+	end)
+
+	it("should capture output from threads the script starts", function()
+		local result = runScript("task.defer(print, 'deferred')")
+
+		expect(result.output[1].body).toEqual("deferred")
+	end)
+
+	it("should capture warnings from threads the script starts", function()
+		local result = runScript("task.defer(warn, 'thread warning')")
+
+		expect(result.output[1].level).toEqual("Warning")
+		expect(result.output[1].body).toEqual("thread warning")
+	end)
+
+	it("should report where a runtime error was thrown", function()
+		local result = runScript("local bomb = {}\nfunction bomb.explode()\n\terror('boom')\nend\nbomb.explode()")
+
+		expect(result.code).toEqual("SCRIPT_RUNTIME_ERROR")
+		expect(result.error).toContain("exec:3: boom")
+		expect(result.traceback).toContain("exec:3")
+		expect(result.traceback).toContain("exec:5")
+		expect(result.traceback).never.toContain("execute:")
+	end)
+
+	it("should pass args to the script as ...", function()
+		local result = ExecuteAction.handleExecute({
+			script = "local name, count = ... return name, tonumber(count), select('#', ...)",
+			args = { "Player1", "3" },
+		}, "req-1", "session-1")
+
+		expect(result.returnValues).toEqual({ "Player1", 3, 2 } :: { any })
+	end)
+
+	it("should cancel a script that outlives its timeout", function()
+		local result = ExecuteAction.handleExecute(
+			{ script = "task.wait(5) print('too late')", timeoutMs = 50 },
+			"req-1",
+			"session-1"
+		)
+
+		expect(result.success).toEqual(false)
+		expect(result.code).toEqual("SCRIPT_TIMEOUT")
+		expect(runScript("return 'next'").returnValues).toEqual({ "next" })
+	end)
+end)
+
+describe("returnValues", function()
+	it("should carry every returned value in order", function()
+		expect(runScript("return 1, 'two', true").returnValues).toEqual({ 1, "two", true } :: { any })
+	end)
+
+	it("should keep nested tables and arrays", function()
+		expect(runScript("return { a = { b = 1 } }, { 1, 2, 3 }").returnValues).toEqual({
+			{ a = { b = 1 } },
+			{ 1, 2, 3 },
+		} :: { any })
+	end)
+
+	it("should turn non-string keys into strings", function()
+		expect(runScript("return { [1] = 'a', [5] = 'b' }").returnValues).toEqual({ { ["1"] = "a", ["5"] = "b" } })
+	end)
+
+	it("should keep a returned nil in its position", function()
+		expect(runScript("return 1, nil, 3").returnValues).toEqual({ 1, { type = "Nil" }, 3 } :: { any })
+	end)
+
+	it("should report a cycle instead of recursing forever", function()
+		local result = runScript("local t = {} t.self = t return t")
+
+		expect(result.returnValues[1].self).toEqual({ type = "Unsupported", typeName = "table", toString = "<cycle>" })
+	end)
+
+	it("should mark non-finite numbers", function()
+		local result = runScript("return math.huge, 0/0")
+
+		expect(result.returnValues[1]).toEqual({ type = "Unsupported", typeName = "number", toString = "inf" })
+		expect(result.returnValues[2].type).toEqual("Unsupported")
+	end)
+
+	it("should mark functions unsupported", function()
+		local result = runScript("return print")
+
+		expect(result.returnValues[1].type).toEqual("Unsupported")
+		expect(result.returnValues[1].typeName).toEqual("function")
+	end)
+
+	it("should serialize Roblox values", function()
+		local result = runScript(
+			"return Vector3.new(1, 2, 3), Color3.new(1, 0, 0), Enum.KeyCode.E, UDim2.new(0.5, 10, 1, 20), workspace"
+		)
+
+		expect(result.returnValues).toEqual({
+			{ type = "Vector3", value = { 1, 2, 3 } },
+			{ type = "Color3", value = { 1, 0, 0 } },
+			{ type = "EnumItem", enum = "KeyCode", name = "E", value = Enum.KeyCode.E.Value },
+			{ type = "UDim2", value = { 0.5, 10, 1, 20 } },
+			{ type = "Instance", className = "Workspace", path = "Workspace" },
+		} :: { any })
+	end)
+end)
+
+describe("ExecuteAction.register()", function()
+	it("should time out a queued script that waited past its timeout without running it", function()
+		local controller = setup(true)
+
+		task.spawn(controller.execute, { script = "task.wait(0.3) return 1" }, "req-1")
+		controller.execute({ script = "print('ran') return 2", timeoutMs = 100 }, "req-2")
+		while #controller.sent < 2 do
+			task.wait()
+		end
+
+		expect(controller.sent[2].requestId).toEqual("req-2")
+		expect(controller.sent[2].payload).toEqual({
+			success = false,
+			error = "Script timed out after 100ms waiting behind other scripts, and never ran",
+			code = "SCRIPT_TIMEOUT",
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should reply through the router as scriptComplete without sendMessage", function()
+		local controller = setup(false)
+
+		local response = controller.execute({ script = "return 1" }, "req-1")
+
+		expect(response and response.type).toEqual("scriptComplete")
+		expect(response and response.requestId).toEqual("req-1")
+		expect(response and response.payload.returnValues).toEqual({ 1 })
+
+		controller:Destroy()
+	end)
+
+	it("should reply through sendMessage and nothing through the router", function()
+		local controller = setup(true)
+
+		local response = controller.execute({ script = "return 1" }, "req-1")
+
+		expect(response).toBeNil()
+		expect(controller.sent).toEqual({
+			{
+				type = "scriptComplete",
+				sessionId = "session-1",
+				requestId = "req-1",
+				payload = { success = true, output = {}, returnValues = { 1 } },
+			},
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should leave requestId out when the request had none", function()
+		local controller = setup(true)
+
+		controller.execute({ script = "return 1" }, nil)
+
+		expect(controller.sent[1].requestId).toBeNil()
+
+		controller:Destroy()
+	end)
+
+	it("should keep answering in order after a failing request", function()
+		local controller = setup(true)
+
+		controller.execute({ script = "return 1" }, "req-1")
+		controller.execute({ script = "error('boom')" }, "req-2")
+		controller.execute({ script = "return 3" }, "req-3")
+
+		expect(#controller.sent).toEqual(3)
+		expect(controller.sent[1].requestId).toEqual("req-1")
+		expect(controller.sent[2].payload.code).toEqual("SCRIPT_RUNTIME_ERROR")
+		expect(controller.sent[3].payload.returnValues).toEqual({ 3 })
+
+		controller:Destroy()
+	end)
+end)

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

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { queryLogsHandlerAsync } from './logs.js';
+import { formatLogsText, parseSince, queryLogsHandlerAsync } from './logs.js';
 
 function createMockSession(logsResult: {
   entries: Array<{ level: string; body: string; timestamp: number }>;
@@ -31,7 +31,7 @@ describe('queryLogsHandlerAsync', () => {
     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)');
+    expect(result.summary).toBe('2 entries (42 in buffer)');
   });
 
   it('passes default options to session', async () => {
@@ -48,6 +48,8 @@ describe('queryLogsHandlerAsync', () => {
       direction: 'tail',
       levels: undefined,
       includeInternal: undefined,
+      since: undefined,
+      groupRepeats: true,
     });
   });
 
@@ -63,6 +65,7 @@ describe('queryLogsHandlerAsync', () => {
       direction: 'head',
       levels: ['Error', 'Warning'],
       includeInternal: true,
+      since: 1793125630,
     });
 
     expect(session.queryLogsAsync).toHaveBeenCalledWith({
@@ -70,6 +73,8 @@ describe('queryLogsHandlerAsync', () => {
       direction: 'head',
       levels: ['Error', 'Warning'],
       includeInternal: true,
+      since: 1793125630,
+      groupRepeats: true,
     });
   });
 
@@ -84,7 +89,7 @@ describe('queryLogsHandlerAsync', () => {
 
     expect(result.entries).toEqual([]);
     expect(result.total).toBe(0);
-    expect(result.summary).toBe('0 entries (0 total in buffer)');
+    expect(result.summary).toBe('0 entries (0 in buffer)');
   });
 
   it('handles entries with all log levels', async () => {
@@ -133,6 +138,73 @@ describe('queryLogsHandlerAsync', () => {
     expect(result.entries).toEqual([]);
     expect(result.total).toBe(0);
     expect(result.bufferCapacity).toBe(0);
-    expect(result.summary).toBe('0 entries (0 total in buffer)');
+    expect(result.summary).toBe('0 entries (0 in buffer)');
+  });
+});
+
+describe('parseSince', () => {
+  const now = Date.parse('2026-10-27T18:00:00Z');
+
+  it('reads a duration back from now', () => {
+    expect(parseSince('30s', now)).toBe(now / 1000 - 30);
+    expect(parseSince('5m', now)).toBe(now / 1000 - 300);
+    expect(parseSince('2h', now)).toBe(now / 1000 - 7200);
+  });
+
+  it('reads a date', () => {
+    expect(parseSince('2026-10-27T17:00:00Z', now)).toBe(now / 1000 - 3600);
+  });
+
+  it('refuses anything else', () => {
+    expect(() => parseSince('yesterday', now)).toThrow(/Can't read --since/);
+  });
+});
+
+describe('repeat grouping', () => {
+  it('is asked of the plugin unless turned off', async () => {
+    const session = createMockSession({
+      entries: [],
+      total: 0,
+      bufferCapacity: 1000,
+    });
+
+    await queryLogsHandlerAsync(session);
+    await queryLogsHandlerAsync(session, { groupRepeats: false });
+
+    expect(session.queryLogsAsync.mock.calls[0][0].groupRepeats).toBe(true);
+    expect(session.queryLogsAsync.mock.calls[1][0].groupRepeats).toBe(false);
+  });
+
+  it('counts each repeat in the summary', async () => {
+    const session = createMockSession({
+      entries: [
+        { level: 'Print', body: 'tick', timestamp: 1, repeats: 3 },
+        { level: 'Print', body: 'done', timestamp: 4 },
+      ],
+      total: 4,
+      bufferCapacity: 1000,
+    } as any);
+
+    expect((await queryLogsHandlerAsync(session)).summary).toBe(
+      '4 entries (4 in buffer)'
+    );
+  });
+});
+
+describe('formatLogsText', () => {
+  it('shows the repeat count and counts every repeat as shown', () => {
+    const text = formatLogsText({
+      entries: [
+        { level: 'Print', body: 'tick', timestamp: 1793125630, repeats: 3 },
+      ],
+      total: 3,
+      bufferCapacity: 1000,
+      summary: '3 entries (3 in buffer)',
+    });
+
+    expect(text).toContain('tick');
+    expect(text).toContain('(x3)');
+    expect(text).toContain('(3 shown, 3 in buffer)');
+    expect(text).toContain(new Date(1793125630 * 1000).toLocaleTimeString());
   });
 });

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

@@ -6,7 +6,7 @@
 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 { BridgeConnection, BridgeSession } from '../../../bridge/index.js';
 import type {
   LogEntry,
   LogsResult as BridgeLogsResult,
@@ -14,9 +14,12 @@ import type {
 import type { OutputLevel } from '../../../server/web-socket-protocol.js';
 
 export interface LogsResult {
+  /** With repeats grouped, a run of identical entries is one with `repeats` and `lastTimestamp`. */
   entries: LogEntry[];
   total: number;
   bufferCapacity: number;
+  /** The cutoff `--since` or `--since-restart` applied, in epoch seconds. */
+  since?: number;
   summary: string;
 }
 
@@ -25,6 +28,89 @@ export interface LogsOptions {
   direction?: 'head' | 'tail';
   levels?: OutputLevel[];
   includeInternal?: boolean;
+  /** Only entries logged at or after this time, in epoch seconds. */
+  since?: number;
+  /** Collapse identical consecutive entries. Defaults to true. */
+  groupRepeats?: boolean;
+}
+
+interface ConsoleLogsArgs {
+  count?: number;
+  direction?: 'head' | 'tail';
+  levels?: OutputLevel[];
+  includeInternal?: boolean;
+  since?: string;
+  sinceRestart?: boolean;
+  groupRepeats?: boolean;
+}
+
+const DURATION_UNITS_SEC: Record<string, number> = {
+  s: 1,
+  m: 60,
+  h: 3600,
+  d: 86400,
+};
+
+/**
+ * The time `--since` names, in epoch seconds: a duration back from `nowMs`
+ * (`30s`, `5m`, `2h`, `1d`) or a date (`2026-10-27T18:00:00`).
+ */
+export function parseSince(value: string, nowMs: number = Date.now()): number {
+  const duration = /^(\d+(?:\.\d+)?)([smhd])$/.exec(value.trim());
+  if (duration) {
+    return nowMs / 1000 - Number(duration[1]) * DURATION_UNITS_SEC[duration[2]];
+  }
+
+  const dateMs = Date.parse(value);
+  if (Number.isNaN(dateMs)) {
+    throw new Error(
+      `Can't read --since '${value}'. Use a duration like 30s, 5m, 2h or 1d, or a date.`
+    );
+  }
+  return dateMs / 1000;
+}
+
+const PLAYTEST_START_SCRIPT =
+  'return DateTime.now().UnixTimestampMillis / 1000 - time()';
+/** The server's DataModel starts running a moment after Edit starts the playtest. */
+const PLAYTEST_START_SLACK_SEC = 2;
+
+/**
+ * The `--since-restart` cutoff for `session`, in epoch seconds: none for a
+ * playtest's own session, whose log began with the playtest, and otherwise a
+ * little before the running playtest's server started.
+ */
+export async function getSinceRestartCutoffAsync(
+  connection: BridgeConnection,
+  session: BridgeSession
+): Promise<number | undefined> {
+  if (session.info.context !== 'edit') {
+    return undefined;
+  }
+
+  const server = connection
+    .listSessions()
+    .find(
+      (info) =>
+        info.instanceId === session.info.instanceId && info.context === 'server'
+    );
+  const serverSession = server && connection.getSession(server.sessionId);
+  if (!serverSession) {
+    throw new Error(
+      `--since-restart needs a running playtest, and '${session.info.instanceId}' has none. Use --since to read back to a time instead.`
+    );
+  }
+
+  const result = await serverSession.execAsync(PLAYTEST_START_SCRIPT, 10_000);
+  const startedAt = result.returnValues?.[0];
+  if (!result.success || typeof startedAt !== 'number') {
+    throw new Error(
+      `Could not read when the playtest started: ${
+        result.error ?? 'no time returned'
+      }`
+    );
+  }
+  return startedAt - PLAYTEST_START_SLACK_SEC;
 }
 
 export async function queryLogsHandlerAsync(
@@ -36,15 +122,19 @@ export async function queryLogsHandlerAsync(
     direction: options.direction ?? 'tail',
     levels: options.levels,
     includeInternal: options.includeInternal,
+    since: options.since,
+    groupRepeats: options.groupRepeats !== false,
   });
 
+  const entries = result.entries ?? [];
+  const shown = entries.reduce((sum, e) => sum + (e.repeats ?? 1), 0);
+
   return {
-    entries: result.entries ?? [],
+    entries,
     total: result.total ?? 0,
     bufferCapacity: result.bufferCapacity ?? 0,
-    summary: `${(result.entries ?? []).length} entries (${
-      result.total ?? 0
-    } total in buffer)`,
+    since: options.since,
+    summary: `${shown} entries (${result.total ?? 0} in buffer)`,
   };
 }
 
@@ -63,20 +153,20 @@ 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()
+      new Date(e.timestamp * 1000).toLocaleTimeString()
     );
     const level = colorizeLevel(e.level);
-    return `[${ts}] [${level}] ${e.body}`;
+    const repeats = e.repeats ? OutputHelper.formatDim(` (x${e.repeats})`) : '';
+    return `[${ts}] [${level}] ${e.body}${repeats}`;
   });
+  const shown = result.entries.reduce((sum, e) => sum + (e.repeats ?? 1), 0);
   lines.push(
-    OutputHelper.formatDim(
-      `(${result.entries.length} of ${result.total} entries)`
-    )
+    OutputHelper.formatDim(`(${shown} shown, ${result.total} in buffer)`)
   );
   return lines.join('\n');
 }
 
-export const logsCommand = defineCommand<LogsOptions, LogsResult>({
+export const logsCommand = defineCommand<ConsoleLogsArgs, LogsResult>({
   group: 'console',
   name: 'logs',
   description: 'Retrieve buffered log history from Studio',
@@ -94,22 +184,47 @@ export const logsCommand = defineCommand<LogsOptions, LogsResult>({
       choices: ['head', 'tail'] as const,
     }),
     levels: arg.option({
-      description: 'Filter by output level (Print, Warning, Error)',
+      description: 'Filter by output level',
       array: true,
+      choices: ['Print', 'Info', 'Warning', 'Error'] as const,
     }),
     includeInternal: arg.flag({
       description: 'Include internal/system log messages',
     }),
+    since: arg.option({
+      description:
+        'Only entries logged since a duration ago (30s, 5m, 2h, 1d) or a date',
+    }),
+    sinceRestart: arg.flag({
+      description: 'Only entries logged since the running playtest started',
+    }),
+    groupRepeats: arg.flag({
+      description:
+        'Collapse identical consecutive entries into one with a repeat count (--no-group-repeats to keep them)',
+      default: true,
+    }),
   },
   cli: {
     format: formatLogsText,
   },
-  handler: async (session, args) => {
+  handler: async (session, args, connection) => {
+    if (args.since && args.sinceRestart) {
+      throw new Error('Use either --since or --since-restart, not both');
+    }
+
+    const since = args.sinceRestart
+      ? await getSinceRestartCutoffAsync(connection, session)
+      : args.since
+      ? parseSince(args.since)
+      : undefined;
+
     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,
+      count: args.count,
+      direction: args.direction,
+      levels: args.levels,
+      includeInternal: args.includeInternal,
+      since,
+      groupRepeats: args.groupRepeats,
     });
   },
 });