@el4cteo/rbx-studio-mcp 0.7.8 → 0.8.2

package/plugin/src/ExecRuntime.luau

@@ -1,161 +1,168 @@
---!strict
--- Shared bounded execution results in the VM that calls run.
-local LogService = game:GetService("LogService")
-local Serialize = require(script.Parent.Serialize)
--- A chunk that prints in a loop would otherwise return a response no context
--- window can hold.
-local MAX_OUTPUT_LINES = 200
-local MAX_RETURN_VALUES = 10
-
--- Returned tables are walked rather than counted, but not without limit: a
--- chunk that returns a whole config tree, or one with a cycle in it, must not be
--- able to produce a response nothing can read.
-local MAX_TABLE_ENTRIES = 50
-local MAX_TABLE_DEPTH = 4
-
-local function describe(value: any, depth: number?, seen: { [any]: boolean }?): any
-	local level = depth or 0
-	local visited = seen or {}
-	local kind = typeof(value)
-
-	if kind == "function" or kind == "thread" then
-		return string.format("<%s>", kind)
-	end
-	if kind ~= "table" then
-		return Serialize.value(value)
-	end
-
-	local source = value :: { [any]: any }
-	-- Named separately from the depth cap, because they mean opposite things to
-	-- a reader. The depth cap says "there is more below this"; a cycle says
-	-- "this is the table you are already inside". Reporting the second as the
-	-- first printed `t.self.self.self` as three distinct nested tables, which
-	-- reads as real structure that does not exist.
-	if visited[source] then
-		return "<circular reference>"
-	end
-	if level >= MAX_TABLE_DEPTH then
-		return "<nested table>"
-	end
-	visited[source] = true
-
-	local count = 0
-	for _ in source do
-		count += 1
-	end
-
-	-- Arrays keep their shape so they read as lists on the other side; anything
-	-- with non-sequential keys becomes a map with stringified keys.
-	if count == #source then
-		local list: { any } = {}
-		for index, item in ipairs(source) do
-			if index > MAX_TABLE_ENTRIES then
-				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
-				break
-			end
-			table.insert(list, describe(item, level + 1, visited))
-		end
-		-- Cleared on the way out so the same table appearing twice side by side
-		-- still renders twice; only a table containing itself is a cycle.
-		visited[source] = nil
-		return list
-	end
-
-	local map: { [string]: any } = {}
-	local shown = 0
-	for key, item in source do
-		shown += 1
-		if shown > MAX_TABLE_ENTRIES then
-			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
-			break
-		end
-		map[tostring(key)] = describe(item, level + 1, visited)
-	end
-	visited[source] = nil
-	return map
-end
-
-local Runtime = {}
-Runtime.describe = describe
-function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
-	-- Captured rather than inferred: a chunk's prints are usually the point, and
-	-- reading them back from the log afterwards would also pick up whatever else
-	-- the place logged in the meantime.
-	local output: { { [string]: any } } = {}
-	local connection = LogService.MessageOut:Connect(function(message, messageType)
-		if #output < MAX_OUTPUT_LINES then
-			table.insert(output, {
-				message = message,
-				level = if messageType == Enum.MessageType.MessageError
-					then "error"
-					elseif messageType == Enum.MessageType.MessageWarning then "warning"
-					else "print",
-			})
-		end
-	end)
-
-	local started = os.clock()
-	local results: any = nil
-	if timeout then
-		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
-		local deadline = started + timeout
-		while results == nil and os.clock() < deadline do task.wait() end
-		if results == nil then
-			task.cancel(worker)
-			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
-		end
-	else
-		results = table.pack(pcall(chunk :: () -> ...any))
-	end
-	local elapsed = os.clock() - started
-
-	--[[
-		MessageOut is deferred: `print` returns before the event fires, so
-		disconnecting straight after the chunk finished captured nothing at all.
-		A short settle picks the lines up.
-
-		It is bounded and stops as soon as the flow stops, rather than waiting a
-		fixed period, so a chunk that logged nothing costs almost no time and one
-		that logged plenty is not truncated.
-	]]
-	local settleDeadline = os.clock() + 0.5
-	local seen = #output
-	local quietFrames = 0
-	while os.clock() < settleDeadline and quietFrames < 3 do
-		task.wait()
-		if #output == seen then
-			quietFrames += 1
-		else
-			seen = #output
-			quietFrames = 0
-		end
-	end
-
-	connection:Disconnect()
-
-	if not results[1] then
-		return {
-			ok = false,
-			error = tostring(results[2]),
-			output = output,
-			milliseconds = math.floor(elapsed * 1000 + 0.5),
-		}
-	end
-
-	local returned: { any } = {}
-	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
-		-- A nil return is written out rather than dropped. `table.insert` of nil
-		-- does nothing, so `return a, nil, b` came back as two values and every
-		-- one after the nil shifted into the wrong position.
-		local value = results[index]
-		table.insert(returned, if value == nil then "nil" else describe(value))
-	end
-
-	return {
-		ok = true,
-		returned = returned,
-		output = output,
-		milliseconds = math.floor(elapsed * 1000 + 0.5),
-	}
-end
-return Runtime
+--!strict
+-- Shared bounded execution results in the VM that calls run.
+local LogService = game:GetService("LogService")
+local LogBuffer = require(script.Parent.LogBuffer)
+local Serialize = require(script.Parent.Serialize)
+-- A chunk that prints in a loop would otherwise return a response no context
+-- window can hold.
+local MAX_OUTPUT_LINES = 200
+local MAX_RETURN_VALUES = 10
+
+-- Returned tables are walked rather than counted, but not without limit: a
+-- chunk that returns a whole config tree, or one with a cycle in it, must not be
+-- able to produce a response nothing can read.
+local MAX_TABLE_ENTRIES = 50
+local MAX_TABLE_DEPTH = 4
+
+local function describe(value: any, depth: number?, seen: { [any]: boolean }?): any
+	local level = depth or 0
+	local visited = seen or {}
+	local kind = typeof(value)
+
+	if kind == "function" or kind == "thread" then
+		return string.format("<%s>", kind)
+	end
+	if kind ~= "table" then
+		return Serialize.value(value)
+	end
+
+	local source = value :: { [any]: any }
+	-- Named separately from the depth cap, because they mean opposite things to
+	-- a reader. The depth cap says "there is more below this"; a cycle says
+	-- "this is the table you are already inside". Reporting the second as the
+	-- first printed `t.self.self.self` as three distinct nested tables, which
+	-- reads as real structure that does not exist.
+	if visited[source] then
+		return "<circular reference>"
+	end
+	if level >= MAX_TABLE_DEPTH then
+		return "<nested table>"
+	end
+	visited[source] = true
+
+	local count = 0
+	for _ in source do
+		count += 1
+	end
+
+	-- Arrays keep their shape so they read as lists on the other side; anything
+	-- with non-sequential keys becomes a map with stringified keys.
+	if count == #source then
+		local list: { any } = {}
+		for index, item in ipairs(source) do
+			if index > MAX_TABLE_ENTRIES then
+				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
+				break
+			end
+			table.insert(list, describe(item, level + 1, visited))
+		end
+		-- Cleared on the way out so the same table appearing twice side by side
+		-- still renders twice; only a table containing itself is a cycle.
+		visited[source] = nil
+		return list
+	end
+
+	local map: { [string]: any } = {}
+	local shown = 0
+	for key, item in source do
+		shown += 1
+		if shown > MAX_TABLE_ENTRIES then
+			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
+			break
+		end
+		map[tostring(key)] = describe(item, level + 1, visited)
+	end
+	visited[source] = nil
+	return map
+end
+
+local Runtime = {}
+Runtime.describe = describe
+function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
+	-- Captured rather than inferred: a chunk's prints are usually the point, and
+	-- reading them back from the log afterwards would also pick up whatever else
+	-- the place logged in the meantime.
+	local output: { { [string]: any } } = {}
+	local connection = LogService.MessageOut:Connect(function(message, messageType, context)
+		if #output < MAX_OUTPUT_LINES then
+			-- A structured log's context rides on the line, as it does in `console`.
+			local encoded = LogBuffer.encodeContext(context)
+			if encoded then
+				message ..= "  " .. encoded
+			end
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					elseif messageType == Enum.MessageType.MessageInfo then "info"
+					else "print",
+			})
+		end
+	end)
+
+	local started = os.clock()
+	local results: any = nil
+	if timeout then
+		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
+		local deadline = started + timeout
+		while results == nil and os.clock() < deadline do task.wait() end
+		if results == nil then
+			task.cancel(worker)
+			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
+		end
+	else
+		results = table.pack(pcall(chunk :: () -> ...any))
+	end
+	local elapsed = os.clock() - started
+
+	--[[
+		MessageOut is deferred: `print` returns before the event fires, so
+		disconnecting straight after the chunk finished captured nothing at all.
+		A short settle picks the lines up.
+
+		It is bounded and stops as soon as the flow stops, rather than waiting a
+		fixed period, so a chunk that logged nothing costs almost no time and one
+		that logged plenty is not truncated.
+	]]
+	local settleDeadline = os.clock() + 0.5
+	local seen = #output
+	local quietFrames = 0
+	while os.clock() < settleDeadline and quietFrames < 3 do
+		task.wait()
+		if #output == seen then
+			quietFrames += 1
+		else
+			seen = #output
+			quietFrames = 0
+		end
+	end
+
+	connection:Disconnect()
+
+	if not results[1] then
+		return {
+			ok = false,
+			error = tostring(results[2]),
+			output = output,
+			milliseconds = math.floor(elapsed * 1000 + 0.5),
+		}
+	end
+
+	local returned: { any } = {}
+	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
+		-- A nil return is written out rather than dropped. `table.insert` of nil
+		-- does nothing, so `return a, nil, b` came back as two values and every
+		-- one after the nil shifted into the wrong position.
+		local value = results[index]
+		table.insert(returned, if value == nil then "nil" else describe(value))
+	end
+
+	return {
+		ok = true,
+		returned = returned,
+		output = output,
+		milliseconds = math.floor(elapsed * 1000 + 0.5),
+	}
+end
+return Runtime

package/plugin/src/LogBuffer.luau

@@ -35,6 +35,10 @@ local SLACK = 500
 -- handful of entries is a mismatch rather than a late delivery.
 local CORRELATION_WINDOW = 20
 
+-- A structured log's context, as JSON, is cut here: Roblox's own server logs
+-- drop context past 1KiB, so nothing longer is worth carrying.
+local MAX_CONTEXT = 1000
+
 export type Entry = {
 	sequence: number?,
 	level: string,
@@ -43,6 +47,8 @@ export type Entry = {
 	-- Present on errors once the matching stack trace has been correlated.
 	stack: string?,
 	source: string?,
+	-- The table a structured log (`LogService:Info(msg, context)`) carried, as JSON.
+	context: string?,
 }
 
 local LEVELS: { [number]: string } = {
@@ -107,6 +113,13 @@ end
 -- Each player gets a separate stream and token. Rejoining, reconnecting to a
 -- different server DataModel, or a plugin reload invalidates old cursors.
 function LogBuffer.startClient(player: Player)
+	-- A relay reinstalled after a respawn is the same player in the same session:
+	-- keep its log and cursor. Only a player that left (stopClient) starts fresh.
+	local existing = clientBuffers[player]
+	if existing then
+		existing.ready = false
+		return
+	end
 	clientBuffers[player] = { token = HttpService:GenerateGUID(false), entries = {}, dropped = 0, sequence = 0, startedAt = os.time(), ready = false, orphan = {} }
 end
 
@@ -146,6 +159,7 @@ function LogBuffer.pushClient(player: Player, payload: any)
 		timestamp = if typeof(payload.timestamp) == "number" and payload.timestamp >= 0 and payload.timestamp < 100000000000 then payload.timestamp else os.time(),
 		stack = if typeof(payload.stack) == "string" then string.sub(payload.stack, 1, 4000) else nil,
 		source = if typeof(payload.source) == "string" then string.sub(payload.source, 1, 500) else nil,
+		context = if typeof(payload.context) == "string" then string.sub(payload.context, 1, MAX_CONTEXT) else nil,
 	}
 	local waiting = buffer.orphan[entry.message]
 	if level == "error" and waiting then
@@ -176,12 +190,60 @@ function LogBuffer.stream(player: Player?): ({ Entry }, number, string, number,
 	return table.move(entries, 1, #entries, 1, {}), dropped, studioToken, nextSequence, LogBuffer.recordingSeconds()
 end
 
-local function push(message: string, messageType: Enum.MessageType, timestamp: number?)
+--[[
+	The context table of a structured log, as compact JSON.
+
+	`LogService:Info("{player} leveled up", { player = "Bob" })` prints only the
+	filled-in message; the table is the part that says which player and what
+	state, and MessageOut hands it over as a third argument. Plain prints pass an
+	empty table, which is dropped. Capped at 1000 characters -- the ceiling
+	Roblox's own server logs apply -- and a table JSON cannot hold (a Vector3, an
+	Instance) falls back to text rather than being lost.
+]]
+-- JSONEncode writes a Vector3 or an Instance as `null` without complaint, so
+-- anything JSON has no shape for is turned into its text first.
+local function plain(value: any, depth: number): any
+	local kind = typeof(value)
+	if kind == "string" or kind == "number" or kind == "boolean" then
+		return value
+	elseif kind == "table" then
+		if depth >= 4 then
+			return "<table>"
+		end
+		local copy = {}
+		for key, item in value do
+			copy[if typeof(key) == "number" then key else tostring(key)] = plain(item, depth + 1)
+		end
+		return copy
+	elseif kind == "Instance" then
+		local ok, full = pcall(function()
+			return value:GetFullName()
+		end)
+		return if ok then full else value.Name
+	end
+	return tostring(value)
+end
+
+function LogBuffer.encodeContext(context: any): string?
+	if typeof(context) ~= "table" or next(context) == nil then
+		return nil
+	end
+	local ok, encoded = pcall(function()
+		return HttpService:JSONEncode(plain(context, 0))
+	end)
+	if not ok then
+		return nil
+	end
+	return string.sub(encoded :: string, 1, MAX_CONTEXT)
+end
+
+local function push(message: string, messageType: Enum.MessageType, timestamp: number?, context: any?)
 	local level = LEVELS[messageType.Value] or "print"
 	local entry: Entry = {
 		level = level,
 		message = message,
 		timestamp = timestamp or os.time(),
+		context = LogBuffer.encodeContext(context),
 	}
 
 	-- Claim a trace that beat its own error line here.
@@ -254,7 +316,7 @@ function LogBuffer.start()
 		end
 	end
 
-	LogService.MessageOut:Connect(function(message: string, messageType: Enum.MessageType)
+	LogService.MessageOut:Connect(function(message: string, messageType: Enum.MessageType, context: any?)
 		local buffered = collecting
 
 		if buffered then
@@ -298,7 +360,7 @@ function LogBuffer.start()
 			return
 		end
 
-		push(message, messageType)
+		push(message, messageType, nil, context)
 	end)
 
 	--[[

package/plugin/src/Paths.luau

@@ -147,13 +147,19 @@ local function childBySegment(
 
 	if ordinal then
 		local list = childrenByName(parent, nil)[name]
-		if list == nil then
-			return nil, nil
-		end
-		local child = list[ordinal]
+		local child = if list then list[ordinal] else nil
 		if child then
 			return child, nil
 		end
+		-- Not an index after all: a child literally named "x[1]". Typed by hand,
+		-- or from a path emitted before `Paths.of` began marking such names.
+		local literal = parent:FindFirstChild(segment)
+		if literal then
+			return literal, nil
+		end
+		if list == nil then
+			return nil, nil
+		end
 		return nil,
 			string.format(
 				'"%s" has %d child%s named "%s", so [%d] is past the end. Indexes are '
@@ -343,6 +349,11 @@ function Paths.of(instance: Instance, memo: NameIndex?): string
 	while current ~= nil and current ~= game do
 		local node = current :: Instance
 		local ordinal = siblingIndex(node, memo)
+		-- A name that itself ends in "[n]" would read back as an index into a
+		-- shorter name. An explicit index keeps it literal: "x[1][1]".
+		if ordinal == nil and string.match(node.Name, "%[%d+%]$") then
+			ordinal = 1
+		end
 		table.insert(
 			segments,
 			1,

package/plugin/src/Phrase.luau

@@ -341,6 +341,8 @@ local DESCRIBERS: { [string]: Describer } = {
 			return "Run the place"
 		elseif op == "multiplayer" then
 			return string.format("Start a %s test", plural(tonumber(params.players) or 2, "player"))
+		elseif op == "addPlayers" then
+			return string.format("Add %s to the test", plural(tonumber(params.players) or 1, "player"))
 		elseif op == "stop" then
 			return "Stop the playtest"
 		elseif op == "endTest" then
@@ -566,29 +568,11 @@ local DESCRIBERS: { [string]: Describer } = {
 
 	--[[
 		Everything below was added after the first pass over this table, and each
-		one spent time showing as the fallback -- "Anim preview", "Data set",
+		one spent time showing as the fallback -- "Data set",
 		"Terrain fill". That form is honest but says nothing about the subject,
 		which is the whole point of this module: the panel is watched to see WHAT
 		an agent is touching, and 26 of 72 operations were declining to say.
 	]]
-	["anim.read"] = function(params)
-		local name = leaf(params.assetId)
-		return if name ~= nil then "Read the animation " .. name else "Read an animation"
-	end,
-	["anim.build"] = function(params)
-		local frames = count(params.keyframes)
-		return string.format("Build an animation from %s", plural(frames, "keyframe"))
-	end,
-	["anim.preview"] = function(params)
-		local rig = leaf(params.rig) or "a rig"
-		if params.op == "stop" then
-			return "Clear the pose on " .. rig
-		end
-		local at = tonumber(params.at)
-		return if at ~= nil
-			then string.format("Pose %s at %.2fs", rig, at)
-			else "Pose " .. rig
-	end,
 
 	["data.list"] = function(params)
 		local store = params.store
@@ -771,7 +755,6 @@ local KINDS: { [string]: string } = {
 	]]
 	terrain = "write",
 	generate = "write",
-	anim = "write",
 	data = "write",
 }
 

package/plugin/src/ScriptEdit.luau

@@ -67,6 +67,20 @@ local function confirm(target: LuaSourceContainer, produced: string?)
 		return
 	end
 
+	--[[
+		No document, no race. The overwrite comes from an editor tab that was
+		loading while we wrote; a tab opened afterwards loads the new source. So
+		a script nobody has open is confirmed by one read, instead of paying the
+		settle -- which cost every written script 200ms, one after another, on
+		every script_edit and script_create.
+	]]
+	local found, document = pcall(function()
+		return ScriptEditorService:FindScriptDocument(target)
+	end)
+	if found and document == nil and ScriptEdit.read(target) == produced then
+		return
+	end
+
 	-- Three rounds: the race is with one load, so a single rewrite settles it,
 	-- and a script that discards three identical writes is failing for a reason
 	-- repeating will not fix.

package/plugin/src/Serialize.luau

@@ -403,6 +403,11 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		return true, Vector2.new(numbers[1], numbers[2]), nil
 	end
 	if valueType == "Color3" then
+		-- "#FF8800", the way colours are usually written everywhere else.
+		local hex = if kind == "string" then string.match(text, "^%s*#(%x%x%x%x%x%x)%s*$") else nil
+		if hex then
+			return true, Color3.fromHex(hex), nil
+		end
 		if #numbers < 3 then
 			return false, nil, 'expected three 0-1 components, e.g. "1, 0.5, 0"'
 		end
@@ -435,6 +440,18 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		return true, UDim.new(numbers[1], numbers[2]), nil
 	end
 	if valueType == "CFrame" then
+		-- Twelve numbers are a full matrix -- what `tostring(cframe)` prints. Read
+		-- as "position | rotation" they gave a silently wrong orientation.
+		if #numbers == 12 then
+			return true,
+				CFrame.new(
+					numbers[1], numbers[2], numbers[3],
+					numbers[4], numbers[5], numbers[6],
+					numbers[7], numbers[8], numbers[9],
+					numbers[10], numbers[11], numbers[12]
+				),
+				nil
+		end
 		if #numbers >= 6 then
 			return true,
 				CFrame.new(numbers[1], numbers[2], numbers[3])

package/plugin/src/TextEdit.luau

@@ -263,6 +263,12 @@ function TextEdit.apply(path: string, source: string, edits: { Edit }): string
 	end
 
 	local text = table.concat(lines, "\n")
+	-- `toLines` drops the final newline, so it is put back here. Without this
+	-- every edit -- even a find/replace in the middle -- stripped it silently,
+	-- and a `find` that included it could never match.
+	if string.sub(source, -1) == "\n" and #lines > 0 then
+		text ..= "\n"
+	end
 
 	for _, edit in findEdits do
 		local needle = edit.find :: string

package/plugin/src/handlers/Api.luau

@@ -122,6 +122,14 @@ local function collect(entries: { any }, className: string, wantInherited: boole
 			deprecated += 1
 			continue
 		end
+		-- No permits at all means no script can touch it: Part's old `shap` and
+		-- `shape` aliases, or engine-only calls like GetPhysicsCost. The engine
+		-- does not flag those as deprecated, so they are held back here too.
+		local permits = if typeof(entry) == "table" then (entry :: any).Permits else nil
+		if typeof(permits) == "table" and next(permits) == nil then
+			deprecated += 1
+			continue
+		end
 		local own = typeof(entry) ~= "table" or tostring((entry :: any).Owner) == className
 		if not own then
 			inherited += 1