@quenty/studio-bridge 0.21.0 → 0.22.0

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

@@ -1,76 +1,109 @@
---[[
-	QueryLogs action handler for the studio-bridge plugin.
+--!strict
+--[=[
+	Action that answers `queryLogs` from the plugin's log buffer, filtered by
+	level and by `since` (epoch seconds), then trimmed to `count` entries from
+	the `head` or `tail`. `[StudioBridge]` messages are left out unless
+	`includeInternal` is set. With `groupRepeats`, identical consecutive
+	entries become one with `repeats` and `lastTimestamp`, before `count`
+	applies, so `count` counts the grouped lines.
 
-	Reads from a MessageBuffer instance and returns filtered log entries.
-	Supports direction (head/tail), count, level filtering, and
-	includeInternal (to show/hide [StudioBridge] messages).
+	Request: `{ type: "queryLogs", payload: { count?, direction?, levels?, includeInternal?, since?, groupRepeats? } }`
+	Response: `{ type: "logsResult", payload: { entries, total, bufferCapacity } }`
 
-	Protocol:
-	  Request:  { type: "queryLogs", payload: { count?, direction?, levels?, includeInternal? } }
-	  Response: { type: "logsResult", payload: { entries, total, bufferCapacity } }
-]]
+	@class QueryLogsAction
+]=]
+
+local DEFAULT_COUNT = 50
+local INTERNAL_PREFIX = "[StudioBridge]"
 
 local QueryLogsAction = {}
 
--- ---------------------------------------------------------------------------
--- Public API
--- ---------------------------------------------------------------------------
+type LogEntry = {
+	level: string,
+	body: string,
+	timestamp: number,
+	repeats: number?,
+	lastTimestamp: number?,
+}
 
--- Register this handler with the ActionRouter.
+--[=[
+	Registers the `queryLogs` handler against `logBuffer`.
+]=]
 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
+		local count = payload.count or DEFAULT_COUNT
 
-			-- 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)
+		local snapshot = logBuffer:get(direction, nil)
+		local filtered = QueryLogsAction._filterEntries(
+			snapshot.entries,
+			payload.levels,
+			payload.includeInternal == true,
+			if type(payload.since) == "number" then payload.since else nil
+		)
+		if payload.groupRepeats == true then
+			filtered = QueryLogsAction._groupRepeats(filtered)
 		end
 
-		-- Apply direction and count to filtered results
-		local entries = {}
+		local takeCount = math.min(count, #filtered)
+		local entries: { LogEntry }
 		if direction == "head" then
-			for i = 1, math.min(count, #filtered) do
-				table.insert(entries, filtered[i])
-			end
+			entries = table.move(filtered, 1, takeCount, 1, {})
 		else
-			local start = math.max(1, #filtered - count + 1)
-			for i = start, #filtered do
-				table.insert(entries, filtered[i])
-			end
+			entries = table.move(filtered, #filtered - takeCount + 1, #filtered, 1, {})
 		end
 
 		return {
 			entries = entries,
-			total = result.total,
-			bufferCapacity = result.bufferCapacity,
+			total = snapshot.total,
+			bufferCapacity = snapshot.bufferCapacity,
 		}
 	end)
 end
 
+--[[
+	Collapses runs of entries with the same level and body into the first,
+	with how many there were and when the last was logged.
+]]
+function QueryLogsAction._groupRepeats(entries: { LogEntry }): { LogEntry }
+	local grouped: { LogEntry } = {}
+	local last: LogEntry? = nil
+	for _, entry in entries do
+		if last and last.level == entry.level and last.body == entry.body then
+			last.repeats = (last.repeats or 1) + 1
+			last.lastTimestamp = entry.timestamp
+		else
+			last = table.clone(entry)
+			table.insert(grouped, last :: LogEntry)
+		end
+	end
+	return grouped
+end
+
+function QueryLogsAction._filterEntries(
+	entries: { LogEntry },
+	levels: { string }?,
+	includeInternal: boolean,
+	since: number?
+): { LogEntry }
+	local filtered: { LogEntry } = {}
+	for _, entry in entries do
+		if not includeInternal and string.sub(entry.body, 1, #INTERNAL_PREFIX) == INTERNAL_PREFIX then
+			continue
+		end
+
+		if levels and #levels > 0 and not table.find(levels, entry.level) then
+			continue
+		end
+
+		if since and entry.timestamp < since then
+			continue
+		end
+
+		table.insert(filtered, entry)
+	end
+	return filtered
+end
+
 return QueryLogsAction

package/src/commands/console/logs/query-logs.spec.lua

@@ -0,0 +1,132 @@
+--!strict
+--[[
+	@class query-logs.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local MessageBuffer = require("MessageBuffer")
+local QueryLogsAction = require("query-logs")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(entries: { { level: string, body: string } }): any
+	local router = ActionRouter.new()
+	local logBuffer = MessageBuffer.new(100)
+	for index, entry in entries do
+		logBuffer:Push({ level = entry.level, body = entry.body, timestamp = index })
+	end
+
+	QueryLogsAction.register(router, nil, logBuffer)
+
+	return {
+		query = function(payload: { [string]: any }): any
+			local response = router:Dispatch({ type = "queryLogs", sessionId = "session-1", payload = payload })
+			assert(response, "No response")
+			return response
+		end,
+	}
+end
+
+local function getBodies(response: any): { string }
+	local bodies = {}
+	for _, entry in response.payload.entries do
+		table.insert(bodies, entry.body)
+	end
+	return bodies
+end
+
+local MIXED_ENTRIES = {
+	{ level = "Print", body = "one" },
+	{ level = "Warning", body = "two" },
+	{ level = "Error", body = "three" },
+	{ level = "Print", body = "[StudioBridge] internal" },
+	{ level = "Print", body = "four" },
+}
+
+describe("queryLogs", function()
+	it("should leave out entries logged before since, then apply count", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		local response = controller.query({ since = 2, count = 2, direction = "head" })
+
+		expect(getBodies(response)).toEqual({ "two", "three" })
+	end)
+
+	it("should group repeats before applying count", function()
+		local controller = setup({
+			{ level = "Print", body = "start" },
+			{ level = "Print", body = "tick" },
+			{ level = "Print", body = "tick" },
+			{ level = "Print", body = "tick" },
+			{ level = "Warning", body = "tick" },
+		})
+
+		local response = controller.query({ groupRepeats = true, count = 2 })
+
+		expect(response.payload.entries).toEqual({
+			{ level = "Print", body = "tick", timestamp = 2, repeats = 3, lastTimestamp = 4 },
+			{ level = "Warning", body = "tick", timestamp = 5 },
+		})
+	end)
+
+	it("should answer logsResult with the buffer's total and capacity", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		local response = controller.query({})
+
+		expect(response.type).toEqual("logsResult")
+		expect(response.payload.total).toEqual(5)
+		expect(response.payload.bufferCapacity).toEqual(100)
+	end)
+
+	it("should return the newest entries by default, oldest first", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		expect(getBodies(controller.query({ count = 2 }))).toEqual({ "three", "four" })
+	end)
+
+	it("should return the oldest entries for head", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		expect(getBodies(controller.query({ direction = "head", count = 2 }))).toEqual({ "one", "two" })
+	end)
+
+	it("should keep only the requested levels", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		expect(getBodies(controller.query({ levels = { "Warning", "Error" } }))).toEqual({ "two", "three" })
+	end)
+
+	it("should leave out [StudioBridge] messages unless asked", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		expect(getBodies(controller.query({}))).toEqual({ "one", "two", "three", "four" })
+		expect(getBodies(controller.query({ includeInternal = true }))).toEqual({
+			"one",
+			"two",
+			"three",
+			"[StudioBridge] internal",
+			"four",
+		})
+	end)
+
+	it("should count after filtering", function()
+		local controller = setup(MIXED_ENTRIES)
+
+		expect(getBodies(controller.query({ levels = { "Print" }, count = 1 }))).toEqual({ "four" })
+	end)
+
+	it("should return no entries for an empty buffer", function()
+		local controller = setup({})
+
+		local response = controller.query({})
+
+		expect(response.payload.entries).toEqual({})
+		expect(response.payload.total).toEqual(0)
+	end)
+end)

package/src/commands/explorer/export/export-instances.lua

@@ -0,0 +1,108 @@
+--!strict
+--[=[
+	Action that serializes the instances at the given paths into one binary
+	model (.rbxm) with SerializationService and answers with it as base64.
+
+	Request: `{ type: "exportInstances", payload: { paths: { string } } }`
+	Response: `{ type: "exportInstancesResult", payload: { data, paths } }`
+
+	@class ExportInstancesAction
+]=]
+
+local ExportInstancesAction = {}
+
+--[=[
+	Registers the `exportInstances` handler.
+]=]
+function ExportInstancesAction.register(router: any)
+	router:setResponseType("exportInstances", "exportInstancesResult")
+	router:register(
+		"exportInstances",
+		function(payload: { [string]: any }, _requestId: string, _sessionId: string): { [string]: any }?
+			local paths = payload.paths
+			if type(paths) ~= "table" or #paths == 0 then
+				return {
+					success = false,
+					code = "INVALID_PAYLOAD",
+					message = "exportInstances needs at least one path",
+				}
+			end
+
+			local instances = {}
+			local fullNames = {}
+			for _, path in paths do
+				local instance = ExportInstancesAction._resolveInstance(path)
+				if not instance then
+					return {
+						success = false,
+						code = "INSTANCE_NOT_FOUND",
+						message = `Instance not found at path: {path}`,
+					}
+				end
+				table.insert(instances, instance)
+				table.insert(fullNames, instance:GetFullName())
+			end
+
+			local serializeOk, serialized = pcall(function()
+				return game:GetService("SerializationService"):SerializeInstancesAsync(instances)
+			end)
+			if not serializeOk then
+				return {
+					success = false,
+					code = "SERIALIZE_FAILED",
+					message = `Failed to serialize instances: {serialized}`,
+				}
+			end
+
+			local encodeOk, encoded = pcall(function()
+				return buffer.tostring(game:GetService("EncodingService"):Base64Encode(serialized))
+			end)
+			if not encodeOk then
+				return {
+					success = false,
+					code = "ENCODE_FAILED",
+					message = `Failed to base64 encode data: {encoded}`,
+				}
+			end
+
+			return {
+				data = encoded,
+				paths = fullNames,
+			}
+		end
+	)
+end
+
+--[[
+	Walks `path` down from game, falling back to GetService for top-level names
+	that are not children by that name. A leading "game" is optional.
+]]
+function ExportInstancesAction._resolveInstance(path: string): Instance?
+	local parts = string.split(path, ".")
+	local startIndex = if parts[1] == "game" then 2 else 1
+
+	local current: Instance = game
+	for index = startIndex, #parts do
+		local part = parts[index]
+
+		local ok, child = pcall(current.FindFirstChild, current, part)
+		if ok and child then
+			current = child
+			continue
+		end
+
+		if current ~= game then
+			return nil
+		end
+
+		local serviceOk, service = pcall(game.GetService, game, part)
+		if not (serviceOk and service) then
+			return nil
+		end
+		current = service
+	end
+
+	return current
+end
+
+return ExportInstancesAction

package/src/commands/explorer/export/export-instances.spec.lua

@@ -0,0 +1,87 @@
+--!strict
+--[[
+	@class export-instances.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local ExportInstancesAction = require("export-instances")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local router = ActionRouter.new()
+	ExportInstancesAction.register(router)
+
+	local root = Instance.new("Folder")
+	root.Name = `ExportInstancesSpec{HttpService:GenerateGUID(false)}`
+
+	local value = Instance.new("IntValue")
+	value.Name = "Score"
+	value.Value = 42
+	value.Parent = root
+
+	root.Parent = workspace
+
+	local controller = {
+		root = root,
+		rootPath = `Workspace.{root.Name}`,
+		export = function(payload: { [string]: any }): any
+			return router:Dispatch({ type = "exportInstances", sessionId = "session-1", payload = payload })
+		end,
+		Destroy = function(_self)
+			root:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+describe("exportInstances", function()
+	it("should answer with a binary model that deserializes to the same instances", function()
+		local controller = setup()
+
+		local response = controller.export({ paths = { controller.rootPath } })
+
+		expect(response.type).toEqual("exportInstancesResult")
+		expect(response.payload.paths).toEqual({ controller.root:GetFullName() })
+
+		local decoded = game:GetService("EncodingService"):Base64Decode(buffer.fromstring(response.payload.data))
+		expect(buffer.readstring(decoded, 0, 8)).toEqual("<roblox!")
+
+		local instances = game:GetService("SerializationService"):DeserializeInstancesAsync(decoded)
+		expect(#instances).toEqual(1)
+		expect(instances[1].Name).toEqual(controller.root.Name)
+		expect((instances[1]:FindFirstChild("Score") :: IntValue).Value).toEqual(42)
+
+		controller:Destroy()
+	end)
+
+	it("should fail when a path does not resolve", function()
+		local controller = setup()
+
+		local response = controller.export({ paths = { controller.rootPath, "Workspace.DoesNotExist" } })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("INSTANCE_NOT_FOUND")
+
+		controller:Destroy()
+	end)
+
+	it("should fail without paths", function()
+		local controller = setup()
+
+		local response = controller.export({ paths = {} })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("INVALID_PAYLOAD")
+
+		controller:Destroy()
+	end)
+end)

package/src/commands/explorer/export/export.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect, vi } from 'vitest';
+import { exportInstancesHandlerAsync } from './export.js';
+
+describe('exportInstancesHandlerAsync', () => {
+  it('returns the model with its size and the exported paths', async () => {
+    const data = Buffer.from('<roblox!model').toString('base64');
+    const session = {
+      exportInstancesAsync: vi
+        .fn()
+        .mockResolvedValue({ data, paths: ['Workspace.Map'] }),
+    } as any;
+
+    const result = await exportInstancesHandlerAsync(session, [
+      'Workspace.Map',
+    ]);
+
+    expect(session.exportInstancesAsync).toHaveBeenCalledWith([
+      'Workspace.Map',
+    ]);
+    expect(result).toEqual({
+      data,
+      paths: ['Workspace.Map'],
+      bytes: 13,
+      summary: 'Exported 1 instance(s) (13 bytes): Workspace.Map',
+    });
+  });
+});

package/src/commands/explorer/export/export.ts

@@ -0,0 +1,60 @@
+/**
+ * `explorer export` — serialize instances from a connected Studio session
+ * into a binary model (.rbxm).
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+
+export interface ExportResult {
+  /** The binary model (.rbxm), base64-encoded. */
+  data: string;
+  paths: string[];
+  bytes: number;
+  summary: string;
+}
+
+interface ExportArgs {
+  paths: string[];
+}
+
+export async function exportInstancesHandlerAsync(
+  session: BridgeSession,
+  paths: string[]
+): Promise<ExportResult> {
+  const result = await session.exportInstancesAsync(paths);
+  const bytes = Buffer.from(result.data, 'base64').length;
+
+  return {
+    data: result.data,
+    paths: result.paths,
+    bytes,
+    summary: `Exported ${
+      result.paths.length
+    } instance(s) (${bytes} bytes): ${result.paths.join(', ')}`,
+  };
+}
+
+export const exportCommand = defineCommand<ExportArgs, ExportResult>({
+  group: 'explorer',
+  name: 'export',
+  description:
+    'Save instances from Studio as a binary model (.rbxm). Use -o to write the file.',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {
+    paths: arg.positional({
+      description: 'Dot-separated instance paths (e.g. Workspace.Map)',
+      required: true,
+      array: true,
+    }),
+  },
+  cli: {
+    binaryField: 'data',
+    format: (result) => result.summary,
+  },
+  handler: async (session, args) =>
+    exportInstancesHandlerAsync(session, args.paths),
+});