@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/commands/explorer/query/query-data-model.lua

@@ -1,111 +1,92 @@
---[[
-	QueryDataModel action handler for the studio-bridge plugin.
-
-	Resolves a dot-separated path to a Roblox Instance and serializes it
-	into a DataModelInstance response with optional properties, attributes,
-	and children up to a specified depth.
-
-	Protocol:
-	  Request:  { type: "queryDataModel", path: "Workspace.SpawnLocation", depth: 1, properties: [], includeAttributes: true }
-	  Response: { type: "dataModelResult", payload: { instance: DataModelInstance } }
-]]
+--!strict
+--[=[
+	Action that resolves a dot-separated path to an Instance and answers with it
+	serialized, along with its properties, attributes, and children down to
+	`depth`.
 
-local QueryDataModelAction = {}
+	Request: `{ type: "queryDataModel", payload: { path, depth?, properties?, includeAttributes? } }`
+	Response: `{ type: "dataModelResult", payload: { instance: DataModelInstance } }`
 
--- ---------------------------------------------------------------------------
--- Property serialization
--- ---------------------------------------------------------------------------
+	@class QueryDataModelAction
+]=]
 
+local COMMON_PROPERTIES = { "Name", "ClassName" }
 local SKIP_PROPERTIES = {
 	Parent = true,
 }
 
-local function serializeValue(value: any): any
-	local t = typeof(value)
+local QueryDataModelAction = {}
 
-	if t == "string" or t == "number" or t == "boolean" then
-		return value
-	elseif t == "nil" then
-		return nil
-	elseif t == "Vector3" then
-		return { type = "Vector3", value = { value.X, value.Y, value.Z } }
-	elseif t == "Vector2" then
-		return { type = "Vector2", value = { value.X, value.Y } }
-	elseif t == "CFrame" then
-		return { type = "CFrame", value = { value:GetComponents() } }
-	elseif t == "Color3" then
-		return { type = "Color3", value = { value.R, value.G, value.B } }
-	elseif t == "UDim2" then
-		return { type = "UDim2", value = { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset } }
-	elseif t == "UDim" then
-		return { type = "UDim", value = { value.Scale, value.Offset } }
-	elseif t == "BrickColor" then
-		return { type = "BrickColor", name = value.Name, value = value.Number }
-	elseif t == "EnumItem" then
-		return { type = "EnumItem", enum = tostring(value.EnumType), name = value.Name, value = value.Value }
-	elseif t == "Instance" then
-		return { type = "Instance", className = value.ClassName, path = value:GetFullName() }
-	else
-		return { type = "Unsupported", typeName = t, toString = tostring(value) }
-	end
+--[=[
+	Registers the `queryDataModel` handler.
+]=]
+function QueryDataModelAction.register(router: any)
+	router:setResponseType("queryDataModel", "dataModelResult")
+	router:register(
+		"queryDataModel",
+		function(payload: { [string]: any }, _requestId: string, _sessionId: string): { [string]: any }?
+			local path = payload.path
+			if type(path) ~= "string" then
+				return nil
+			end
+
+			local instance = QueryDataModelAction._resolveInstance(path)
+			if not instance then
+				return {
+					success = false,
+					code = "INSTANCE_NOT_FOUND",
+					message = `Instance not found at path: {path}`,
+				}
+			end
+
+			return {
+				instance = QueryDataModelAction._serializeInstance(
+					instance,
+					payload.depth or 0,
+					payload.properties,
+					payload.includeAttributes == true
+				),
+			}
+		end
+	)
 end
 
-local function serializeProperties(instance: Instance, propertyFilter: { string }?): { [string]: any }
-	local result = {}
+--[[
+	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 QueryDataModelAction._resolveInstance(path: string): Instance?
+	local parts = string.split(path, ".")
+	local startIndex = if parts[1] == "game" then 2 else 1
 
-	-- If a filter is provided and empty, return no properties
-	if propertyFilter and #propertyFilter == 0 then
-		return result
-	end
+	local current: Instance = game
+	for index = startIndex, #parts do
+		local part = parts[index]
 
-	-- Use API dump approach: read common properties via pcall
-	-- Since Roblox doesn't expose a property list, we read known safe properties
-	-- and any specifically requested ones
-	if propertyFilter then
-		for _, propName in propertyFilter do
-			if not SKIP_PROPERTIES[propName] then
-				local ok, value = pcall(function()
-					return (instance :: any)[propName]
-				end)
-				if ok then
-					result[propName] = serializeValue(value)
-				end
-			end
+		local ok, child = pcall(current.FindFirstChild, current, part)
+		if ok and child then
+			current = child
+			continue
 		end
-	else
-		-- No filter: read common properties
-		local commonProps = { "Name", "ClassName" }
-		for _, propName in commonProps do
-			local ok, value = pcall(function()
-				return (instance :: any)[propName]
-			end)
-			if ok then
-				result[propName] = serializeValue(value)
-			end
-		end
-	end
 
-	return result
-end
+		if current ~= game then
+			return nil
+		end
 
-local function serializeAttributes(instance: Instance): { [string]: any }
-	local result = {}
-	local ok, attrs = pcall(function()
-		return instance:GetAttributes()
-	end)
-	if ok and attrs then
-		for key, value in attrs do
-			result[key] = serializeValue(value)
+		local serviceOk, service = pcall(game.GetService, game, part)
+		if not (serviceOk and service) then
+			return nil
 		end
+		current = service
 	end
-	return result
-end
 
--- ---------------------------------------------------------------------------
--- Instance serialization
--- ---------------------------------------------------------------------------
+	return current
+end
 
-local function serializeInstance(
+--[[
+	A nil filter reads the common properties, an empty one reads none.
+]]
+function QueryDataModelAction._serializeInstance(
 	instance: Instance,
 	depth: number,
 	propertyFilter: { string }?,
@@ -116,15 +97,18 @@ local function serializeInstance(
 		name = instance.Name,
 		className = instance.ClassName,
 		path = instance:GetFullName(),
-		properties = serializeProperties(instance, propertyFilter),
-		attributes = if includeAttributes then serializeAttributes(instance) else {},
+		properties = QueryDataModelAction._serializeProperties(instance, propertyFilter or COMMON_PROPERTIES),
+		attributes = if includeAttributes then QueryDataModelAction._serializeAttributes(instance) else {},
 		childCount = #children,
 	}
 
 	if depth > 0 then
 		local serializedChildren = {}
 		for _, child in children do
-			table.insert(serializedChildren, serializeInstance(child, depth - 1, propertyFilter, includeAttributes))
+			table.insert(
+				serializedChildren,
+				QueryDataModelAction._serializeInstance(child, depth - 1, propertyFilter, includeAttributes)
+			)
 		end
 		node.children = serializedChildren
 	end
@@ -132,75 +116,63 @@ local function serializeInstance(
 	return node
 end
 
--- ---------------------------------------------------------------------------
--- Path resolution
--- ---------------------------------------------------------------------------
-
-local function resolveInstance(path: string): Instance?
-	-- Split path by dots, resolve from game
-	local parts = string.split(path, ".")
-	local startIndex = 1
-
-	-- Skip leading "game" since we start from game
-	if parts[1] == "game" then
-		startIndex = 2
-	end
+function QueryDataModelAction._serializeProperties(instance: Instance, propertyNames: { string }): { [string]: any }
+	local result = {}
+	for _, propertyName in propertyNames do
+		if SKIP_PROPERTIES[propertyName] then
+			continue
+		end
 
-	local current: any = game
-	for i = startIndex, #parts do
-		local part = parts[i]
-		-- Try as a service first (e.g. "Workspace", "ReplicatedStorage")
-		local ok, child = pcall(function()
-			return current:FindFirstChild(part)
+		-- Roblox exposes no property list, so read each name and skip the ones that throw
+		local ok, value = pcall(function()
+			return (instance :: any)[propertyName]
 		end)
-		if not ok or not child then
-			-- Try GetService for top-level services
-			if current == game then
-				local serviceOk, service = pcall(function()
-					return game:GetService(part)
-				end)
-				if serviceOk and service then
-					current = service
-					continue
-				end
-			end
-			return nil
+		if ok then
+			result[propertyName] = QueryDataModelAction._serializeValue(value)
 		end
-		current = child
 	end
-
-	return current
+	return result
 end
 
--- ---------------------------------------------------------------------------
--- Public API
--- ---------------------------------------------------------------------------
-
-function QueryDataModelAction.register(router: any)
-	router:setResponseType("queryDataModel", "dataModelResult")
-	router:register("queryDataModel", function(payload: { [string]: any }, _requestId: string, _sessionId: string)
-		local path = payload.path
-		if not path or type(path) ~= "string" then
-			return nil -- ActionRouter will return UNKNOWN_REQUEST for nil
-		end
+function QueryDataModelAction._serializeAttributes(instance: Instance): { [string]: any }
+	local result = {}
+	local ok, attributes = pcall(instance.GetAttributes, instance)
+	if not ok then
+		return result
+	end
 
-		local depth = payload.depth or 0
-		local propertyFilter = payload.properties -- nil means common props, {} means none
-		local includeAttributes = payload.includeAttributes == true
+	for key, value in attributes do
+		result[key] = QueryDataModelAction._serializeValue(value)
+	end
+	return result
+end
 
-		local instance = resolveInstance(path)
-		if not instance then
-			return {
-				success = false,
-				code = "INSTANCE_NOT_FOUND",
-				message = `Instance not found at path: {path}`,
-			}
-		end
+function QueryDataModelAction._serializeValue(value: any): any
+	local valueType = typeof(value)
 
-		return {
-			instance = serializeInstance(instance, depth, propertyFilter, includeAttributes),
-		}
-	end)
+	if valueType == "nil" or valueType == "string" or valueType == "number" or valueType == "boolean" then
+		return value
+	elseif valueType == "Vector3" then
+		return { type = "Vector3", value = { value.X, value.Y, value.Z } }
+	elseif valueType == "Vector2" then
+		return { type = "Vector2", value = { value.X, value.Y } }
+	elseif valueType == "CFrame" then
+		return { type = "CFrame", value = { value:GetComponents() } }
+	elseif valueType == "Color3" then
+		return { type = "Color3", value = { value.R, value.G, value.B } }
+	elseif valueType == "UDim2" then
+		return { type = "UDim2", value = { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset } }
+	elseif valueType == "UDim" then
+		return { type = "UDim", value = { value.Scale, value.Offset } }
+	elseif valueType == "BrickColor" then
+		return { type = "BrickColor", name = value.Name, value = value.Number }
+	elseif valueType == "EnumItem" then
+		return { type = "EnumItem", enum = tostring(value.EnumType), name = value.Name, value = value.Value }
+	elseif valueType == "Instance" then
+		return { type = "Instance", className = value.ClassName, path = value:GetFullName() }
+	else
+		return { type = "Unsupported", typeName = valueType, toString = tostring(value) }
+	end
 end
 
 return QueryDataModelAction

package/src/commands/explorer/query/query-data-model.spec.lua

@@ -0,0 +1,150 @@
+--!strict
+--[[
+	@class query-data-model.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local QueryDataModelAction = require("query-data-model")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local router = ActionRouter.new()
+	QueryDataModelAction.register(router)
+
+	local root = Instance.new("Folder")
+	root.Name = `QueryDataModelSpec{HttpService:GenerateGUID(false)}`
+	root:SetAttribute("Offset", Vector3.new(1, 2, 3))
+
+	local value = Instance.new("IntValue")
+	value.Name = "Score"
+	value.Value = 42
+	value.Parent = root
+
+	local nested = Instance.new("Folder")
+	nested.Name = "Nested"
+	nested.Parent = value
+
+	root.Parent = workspace
+
+	local controller = {
+		root = root,
+		rootPath = `Workspace.{root.Name}`,
+		query = function(payload: { [string]: any }): any
+			return router:Dispatch({ type = "queryDataModel", sessionId = "session-1", payload = payload })
+		end,
+		Destroy = function(_self)
+			root:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+describe("queryDataModel", function()
+	it("should answer dataModelResult with the instance's common properties", function()
+		local controller = setup()
+
+		local response = controller.query({ path = controller.rootPath })
+
+		expect(response.type).toEqual("dataModelResult")
+		expect(response.payload.instance).toEqual({
+			name = controller.root.Name,
+			className = "Folder",
+			path = controller.root:GetFullName(),
+			properties = { Name = controller.root.Name, ClassName = "Folder" },
+			attributes = {},
+			childCount = 1,
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should accept a leading game", function()
+		local controller = setup()
+
+		local response = controller.query({ path = `game.{controller.rootPath}` })
+
+		expect(response.payload.instance.name).toEqual(controller.root.Name)
+
+		controller:Destroy()
+	end)
+
+	it("should include children down to the requested depth", function()
+		local controller = setup()
+
+		local response = controller.query({ path = controller.rootPath, depth = 1 })
+
+		local children = response.payload.instance.children
+		expect(#children).toEqual(1)
+		expect(children[1].name).toEqual("Score")
+		expect(children[1].childCount).toEqual(1)
+		expect(children[1].children).toBeNil()
+
+		controller:Destroy()
+	end)
+
+	it("should read only the requested properties, skipping Parent and unknown names", function()
+		local controller = setup()
+
+		local response = controller.query({
+			path = `{controller.rootPath}.Score`,
+			properties = { "Value", "Parent", "NotAProperty" },
+		})
+
+		expect(response.payload.instance.properties).toEqual({ Value = 42 })
+
+		controller:Destroy()
+	end)
+
+	it("should read no properties for an empty list", function()
+		local controller = setup()
+
+		local response = controller.query({ path = controller.rootPath, properties = {} })
+
+		expect(response.payload.instance.properties).toEqual({})
+
+		controller:Destroy()
+	end)
+
+	it("should serialize attributes when asked", function()
+		local controller = setup()
+
+		local response = controller.query({ path = controller.rootPath, includeAttributes = true })
+
+		expect(response.payload.instance.attributes).toEqual({
+			Offset = { type = "Vector3", value = { 1, 2, 3 } },
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should answer INSTANCE_NOT_FOUND for a missing path", function()
+		local controller = setup()
+
+		local response = controller.query({ path = `{controller.rootPath}.Missing` })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload).toEqual({
+			code = "INSTANCE_NOT_FOUND",
+			message = `Instance not found at path: {controller.rootPath}.Missing`,
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should send nothing without a path", function()
+		local controller = setup()
+
+		expect(controller.query({})).toBeNil()
+
+		controller:Destroy()
+	end)
+end)

package/src/commands/formatters.test.ts

@@ -74,7 +74,7 @@ describe('logs formatter', () => {
     const text = formatLogsText(result);
     expect(text).toContain('Hello');
     expect(text).toContain('Boom');
-    expect(text).toContain('(2 of 2 entries)');
+    expect(text).toContain('(2 shown, 2 in buffer)');
   });
 
   it('is wired into command definition', () => {
@@ -123,10 +123,16 @@ describe('list formatter', () => {
 describe('info formatter', () => {
   it('formats key-value pairs', () => {
     const result = {
+      sessionId: 'my-place-1a2b-edit',
+      instanceId: 'my-place-1a2b',
+      context: 'edit' as const,
+      origin: 'user' as const,
       state: 'Edit' as const,
       placeName: 'MyPlace',
       placeId: 123,
       gameId: 456,
+      plugin: { version: 'abc', expectedVersion: 'abc', upToDate: true },
+      connectedAt: new Date().toISOString(),
       summary: 'Mode: Edit, Place: MyPlace (123)',
     };
 

package/src/commands/framework/action-loader.test.ts

@@ -98,6 +98,34 @@ describe('loadActionSourcesAsync', () => {
     expect(results[0].name).toBe('action');
   });
 
+  it('skips .spec.lua files', async () => {
+    await fs.writeFile(path.join(tmpDir, 'action.lua'), 'included');
+    await fs.writeFile(path.join(tmpDir, 'action.spec.lua'), 'not included');
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results.map((r) => r.name)).toEqual(['action']);
+  });
+
+  it('finds every shipped action and none of their specs', async () => {
+    const results = await loadActionSourcesAsync();
+
+    expect(results.map((r) => r.name).sort()).toEqual([
+      'capture-screenshot',
+      'end-playtest',
+      'execute',
+      'export-instances',
+      'find-instances',
+      'grep-scripts',
+      'import-instances',
+      'query-data-model',
+      'query-logs',
+      'query-state',
+      'run-playtest-script',
+      'start-playtest',
+    ]);
+  });
+
   it('returns empty array for empty directory', async () => {
     const results = await loadActionSourcesAsync(tmpDir);
     expect(results).toHaveLength(0);

package/src/commands/framework/action-loader.ts

@@ -6,6 +6,9 @@
  * as its `.ts` file (e.g. `exec.lua` next to `exec.ts`). These files
  * are Luau modules that register action handlers in the plugin's
  * ActionRouter at runtime.
+ *
+ * `.spec.lua` files beside them are Jest specs. They are never pushed,
+ * since anything pushed runs inside the user's Studio.
  */
 
 import { createHash } from 'crypto';
@@ -26,7 +29,8 @@ export interface ActionSource {
 
 /**
  * Recursively scan `baseDir` for `.lua` files and return their contents
- * as `ActionSource` entries. Only files that end in `.lua` are included.
+ * as `ActionSource` entries. Only files that end in `.lua` are included,
+ * and `.spec.lua` files are skipped.
  */
 export async function loadActionSourcesAsync(
   baseDir?: string
@@ -54,7 +58,7 @@ async function scanDirAsync(
     const fullPath = path.join(currentDir, entry.name);
     if (entry.isDirectory()) {
       await scanDirAsync(baseDir, fullPath, results);
-    } else if (entry.name.endsWith('.lua')) {
+    } else if (isActionFile(entry.name)) {
       const source = await fs.readFile(fullPath, 'utf-8');
       const name = path.basename(entry.name, '.lua');
       const relativePath = path.relative(baseDir, fullPath);
@@ -63,3 +67,7 @@ async function scanDirAsync(
     }
   }
 }
+
+function isActionFile(fileName: string): boolean {
+  return fileName.endsWith('.lua') && !fileName.endsWith('.spec.lua');
+}

package/src/commands/framework/arg-builder.ts

@@ -1,12 +1,12 @@
 /**
  * Argument definition DSL and schema converters.
  *
- * `arg.positional()`, `arg.option()`, and `arg.flag()` produce `ArgDefinition`
+ * `arg.positional()`, `arg.option()`, `arg.flag()`, and `arg.passthrough()` produce `ArgDefinition`
  * objects that carry enough metadata to generate both yargs options and
  * JSON Schema properties for MCP tools.
  */
 
-export type ArgKind = 'positional' | 'option' | 'flag';
+export type ArgKind = 'positional' | 'option' | 'flag' | 'passthrough';
 export type ArgType = 'string' | 'number' | 'boolean';
 
 export interface ArgDefinition {
@@ -33,6 +33,8 @@ export const arg = {
     type?: 'string' | 'number';
     required?: boolean;
     choices?: readonly string[];
+    /** Collect every remaining positional into an array (`<name..>`). */
+    array?: boolean;
   }): ArgDefinition {
     return {
       kind: 'positional',
@@ -40,6 +42,7 @@ export const arg = {
       description: config.description,
       required: config.required ?? true,
       choices: config.choices,
+      array: config.array,
     };
   },
 
@@ -91,6 +94,22 @@ export const arg = {
       default: config.default ?? false,
     };
   },
+
+  /**
+   * Collect everything after `--` as a list of strings, unparsed.
+   *
+   * ```ts
+   * args: { scriptArgs: arg.passthrough({ description: 'Passed to the script' }) }
+   * ```
+   */
+  passthrough(config: { description: string }): ArgDefinition {
+    return {
+      kind: 'passthrough',
+      type: 'string',
+      description: config.description,
+      array: true,
+    };
+  },
 };
 
 export interface YargsPositional {
@@ -100,6 +119,7 @@ export interface YargsPositional {
     type: 'string' | 'number';
     demandOption?: boolean;
     choices?: readonly string[];
+    array?: boolean;
   };
 }
 
@@ -118,7 +138,9 @@ export function toYargsOptions(
   const options: Record<string, Record<string, unknown>> = {};
 
   for (const [name, def] of Object.entries(args)) {
-    if (def.kind === 'positional') {
+    if (def.kind === 'passthrough') {
+      continue;
+    } else if (def.kind === 'positional') {
       positionals.push({
         name,
         options: {
@@ -126,6 +148,7 @@ export function toYargsOptions(
           type: def.type as 'string' | 'number',
           demandOption: def.required,
           ...(def.choices ? { choices: def.choices } : {}),
+          ...(def.array ? { array: true } : {}),
         },
       });
     } else {