@el4cteo/rbx-studio-mcp 0.7.1 → 0.7.5

package/plugin/src/handlers/Playtest.luau

@@ -1,205 +1,245 @@
---!strict
---[[
-	Driving Studio's playtests.
-
-	`StudioTestService`, not `RunService:Run`. Run/Pause/Stop are marked
-	PluginSecurity and are permitted, and they do nothing: called from a real
-	plugin handler -- not just through the loadstring sandbox, which was the first
-	wrong explanation -- `Run()` returns successfully and leaves Studio in edit
-	mode with nothing logged. StudioTestService is the service Roblox added for
-	this, and it reaches further: Play mode with a character, and multiplayer
-	tests, neither of which RunService offered at all.
-
-	The Execute calls yield until the test ends -- specifically until something
-	inside the session calls `EndTest`. That is the wrong shape for a request
-	that should answer promptly, so the call is started on its own task and the
-	reply describes the state it reached. The result, whenever the test finally
-	produces one, is kept for a later `state` to collect.
-]]
-
-local RunService = game:GetService("RunService")
-local StudioTestService = game:GetService("StudioTestService")
-
-local Dispatch = require(script.Parent.Parent.Dispatch)
-
--- Long enough for Studio to actually enter the mode before the state is read
--- back, so the reply describes what happened rather than what was asked for.
-local SETTLE_SECONDS = 1.5
-
-local Playtest = {}
-
--- Outcome of the most recent test, which arrives long after the call that
--- started it returned.
-local pending = false
-local lastResult: any = nil
-local lastError: string? = nil
-local startedAt: number? = nil
-
-local function service(): any
-	return StudioTestService :: any
-end
-
-local function editModeActive(): boolean?
-	local ok, value = pcall(function()
-		return service().EditModeActive
-	end)
-	return if ok and typeof(value) == "boolean" then value else nil
-end
-
-local function state(): { [string]: any }
-	return {
-		isEdit = RunService:IsEdit(),
-		isRunning = RunService:IsRunning(),
-		isRunMode = RunService:IsRunMode(),
-		editModeActive = editModeActive(),
-		playerCount = #game:GetService("Players"):GetPlayers(),
-		testPending = pending,
-		-- Kept from the previous test rather than discarded, since whatever
-		-- EndTest returned is the only thing a test session can hand back.
-		lastResult = lastResult,
-		lastError = lastError,
-		runningForSeconds = if startedAt then math.floor(os.clock() - startedAt) else nil,
-	}
-end
-
---[[
-	Starts a test without waiting for it to finish.
-
-	Every failure here has to survive on its own thread: nothing is watching it
-	by the time it fails, so the reason is stored for the next `state` instead of
-	being raised into a caller that has already been answered.
-]]
-local function launch(name: string, call: () -> any)
-	pending = true
-	lastResult = nil
-	lastError = nil
-	startedAt = os.clock()
-
-	task.spawn(function()
-		local ok, result = pcall(call)
-		pending = false
-		startedAt = nil
-		if ok then
-			lastResult = result
-		else
-			lastError = string.format("%s failed: %s", name, tostring(result))
-		end
-	end)
-end
-
-function Playtest.control(params: { [string]: any }): { [string]: any }
-	local op = params.op
-	local before = state()
-
-	if op == "state" then
-		return { changed = false, state = before }
-	end
-
-	--[[
-		Ending a test has to happen inside it.
-
-		`LeaveTest` reads like the plugin-side exit and is not: it refuses with
-		"can only be called from the client DataModel of a running Studio test
-		session", and a playtest client can never reach this bridge because Studio
-		bars client sessions from making HTTP requests. So that route is closed for
-		good, not merely awkward.
-
-		`EndTest` works from the playtest's *server* session, which does connect --
-		and its value travels back to whichever plugin called ExecutePlayModeAsync.
-		The server tool routes a stop to that session; this op is what it calls.
-	]]
-	if op == "endTest" then
-		--[[
-			Deferred, because EndTest destroys the DataModel this handler is
-			running in -- including the connection carrying the reply. Called
-			inline it does end the test and the caller sees only DISCONNECTED,
-			which reads as a failed stop for something that worked perfectly.
-
-			The reply goes out first and the teardown follows. Whether it
-			actually ended is not taken on trust either way: the caller confirms
-			against the editor session, which survives.
-		]]
-		task.delay(0.25, function()
-			pcall(function()
-				service():EndTest(params.value or "stopped by studio-mcp")
-			end)
-		end)
-		return { changed = true, deferred = true, state = before }
-	end
-
-	if op == "stop" then
-		if before.isEdit and not before.isRunning and not pending then
-			return { changed = false, reason = "no test is running", state = before }
-		end
-
-		-- Only reachable when the caller could not find a playtest session to end
-		-- from. Stops a Run-mode session, which has no separate DataModel.
-		pcall(function()
-			RunService:Stop()
-		end)
-
-		task.wait(SETTLE_SECONDS)
-		local after = state()
-		return {
-			changed = after.isRunning ~= before.isRunning or after.isEdit ~= before.isEdit,
-			state = after,
-		}
-	end
-
-	if pending then
-		Dispatch.fail(
-			"ALREADY_RUNNING",
-			"A test is already running.",
-			"Stop it first, or call with op 'state' to see how it is doing."
-		)
-	end
-
-	-- ExecutePlayModeAsync rejects a nil argument outright -- "Argument 1 missing
-	-- or nil" -- even though the parameter is a Variant, so an omitted `args`
-	-- becomes an empty string rather than a failed launch.
-	local args = if params.args == nil then "" else params.args
-	if op == "play" then
-		launch("ExecutePlayModeAsync", function()
-			return service():ExecutePlayModeAsync(args)
-		end)
-	elseif op == "run" then
-		launch("ExecuteRunModeAsync", function()
-			return service():ExecuteRunModeAsync(args)
-		end)
-	elseif op == "multiplayer" then
-		local players = tonumber(params.players) or 2
-		if players < 1 or players > 8 then
-			Dispatch.fail("BAD_PARAMS", "players must be between 1 and 8.")
-		end
-		launch("ExecuteMultiplayerTestAsync", function()
-			return service():ExecuteMultiplayerTestAsync(players, args)
-		end)
-	else
-		Dispatch.fail("BAD_PARAMS", string.format("unknown op %q", tostring(op)))
-	end
-
-	task.wait(SETTLE_SECONDS)
-	local after = state()
-
-	-- Whether the mode moved, not whether the call was accepted. Accepting and
-	-- doing nothing is exactly how RunService:Run behaved here.
-	local moved = after.isRunning ~= before.isRunning
-		or after.isEdit ~= before.isEdit
-		or after.editModeActive ~= before.editModeActive
-
-	return {
-		changed = moved or after.testPending,
-		reason = if after.lastError then after.lastError
-			elseif not moved and not after.testPending then "Studio accepted the call but the mode did not change"
-			else nil,
-		state = after,
-	}
-end
-
-function Playtest.register()
-	Dispatch.registerAll("playtest", {
-		control = Playtest.control,
-	})
-end
-
-return Playtest
+--!strict
+--[[
+	Driving Studio's playtests.
+
+	`StudioTestService`, not `RunService:Run`. Run/Pause/Stop are marked
+	PluginSecurity and are permitted, and they do nothing: called from a real
+	plugin handler -- not just through the loadstring sandbox, which was the first
+	wrong explanation -- `Run()` returns successfully and leaves Studio in edit
+	mode with nothing logged. StudioTestService is the service Roblox added for
+	this, and it reaches further: Play mode with a character, and multiplayer
+	tests, neither of which RunService offered at all.
+
+	The Execute calls yield until the test ends -- specifically until something
+	inside the session calls `EndTest`. That is the wrong shape for a request
+	that should answer promptly, so the call is started on its own task and the
+	reply describes the state it reached. The result, whenever the test finally
+	produces one, is kept for a later `state` to collect.
+]]
+
+local RunService = game:GetService("RunService")
+local StudioTestService = game:GetService("StudioTestService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+
+-- Long enough for Studio to actually enter the mode before the state is read
+-- back, so the reply describes what happened rather than what was asked for.
+local SETTLE_SECONDS = 1.5
+
+local Playtest = {}
+
+-- Supplied by the plugin entrypoint, which owns persistent plugin settings.
+-- Read on every request so another panel context's choice is not cached here.
+local readAllowed: () -> any = function() return nil end
+local writeAllowed: (boolean) -> () = function() error("Playtest settings are not initialized") end
+function Playtest.setup(read: () -> any, write: (boolean) -> ())
+	readAllowed, writeAllowed = read, write
+end
+function Playtest.isAllowed(): boolean
+	return readAllowed() ~= false
+end
+function Playtest.setAllowed(value: boolean)
+	writeAllowed(value)
+end
+local function requireAllowed()
+	if not Playtest.isAllowed() then
+		Dispatch.fail("PLAYTEST_DISABLED", "Playtests are disabled by the user.",
+			"Do not start or simulate a playtest. Continue using edit-mode tools and static inspection where possible.\nRun `playtests on` in the Studio MCP panel to re-enable playtesting.")
+	end
+end
+
+-- Outcome of the most recent test, which arrives long after the call that
+-- started it returned.
+local pending = false
+local lastResult: any = nil
+local lastError: string? = nil
+local startedAt: number? = nil
+
+local function service(): any
+	return StudioTestService :: any
+end
+
+local function editModeActive(): boolean?
+	local ok, value = pcall(function()
+		return service().EditModeActive
+	end)
+	return if ok and typeof(value) == "boolean" then value else nil
+end
+
+local function state(): { [string]: any }
+	return {
+		playtestsAllowed = Playtest.isAllowed(),
+		isEdit = RunService:IsEdit(),
+		isRunning = RunService:IsRunning(),
+		isRunMode = RunService:IsRunMode(),
+		editModeActive = editModeActive(),
+		playerCount = #game:GetService("Players"):GetPlayers(),
+		testPending = pending,
+		-- Kept from the previous test rather than discarded, since whatever
+		-- EndTest returned is the only thing a test session can hand back.
+		lastResult = lastResult,
+		lastError = lastError,
+		runningForSeconds = if startedAt then math.floor(os.clock() - startedAt) else nil,
+	}
+end
+
+--[[
+	Starts a test without waiting for it to finish.
+
+	Every failure here has to survive on its own thread: nothing is watching it
+	by the time it fails, so the reason is stored for the next `state` instead of
+	being raised into a caller that has already been answered.
+]]
+local function launch(name: string, call: () -> any)
+	pending = true
+	lastResult = nil
+	lastError = nil
+	startedAt = os.clock()
+
+	task.spawn(function()
+		local ok, result = pcall(function()
+			-- Recheck after scheduling: OFF may have been entered while queued.
+			requireAllowed()
+			return call()
+		end)
+		pending = false
+		startedAt = nil
+		if ok then
+			lastResult = result
+		else
+			lastError = if typeof(result) == "table" and result.code == "PLAYTEST_DISABLED"
+				then result.code .. ": " .. result.message .. "\n" .. result.hint
+				else string.format("%s failed: %s", name, tostring(result))
+		end
+	end)
+end
+
+function Playtest.control(params: { [string]: any }): { [string]: any }
+	local op = params.op
+	if op == "play" or op == "run" or op == "multiplayer" then requireAllowed() end
+	local before = state()
+
+	if op == "state" then
+		return { changed = false, state = before }
+	end
+
+	--[[
+		Ending a test has to happen inside it.
+
+		`LeaveTest` reads like the plugin-side exit and is not: it refuses with
+		"can only be called from the client DataModel of a running Studio test
+		session", and a playtest client can never reach this bridge because Studio
+		bars client sessions from making HTTP requests. So that route is closed for
+		good, not merely awkward.
+
+		`EndTest` works from the playtest's *server* session, which does connect --
+		and its value travels back to whichever plugin called ExecutePlayModeAsync.
+		The server tool routes a stop to that session; this op is what it calls.
+	]]
+	if op == "endTest" then
+		--[[
+			Deferred, because EndTest destroys the DataModel this handler is
+			running in -- including the connection carrying the reply. Called
+			inline it does end the test and the caller sees only DISCONNECTED,
+			which reads as a failed stop for something that worked perfectly.
+
+			The reply goes out first and the teardown follows. Whether it
+			actually ended is not taken on trust either way: the caller confirms
+			against the editor session, which survives.
+		]]
+		task.delay(0.25, function()
+			pcall(function()
+				service():EndTest(params.value or "stopped by studio-mcp")
+			end)
+		end)
+		return { changed = true, deferred = true, state = before }
+	end
+
+	if op == "stop" then
+		if before.isEdit and not before.isRunning and not pending then
+			return { changed = false, reason = "no test is running", state = before }
+		end
+
+		-- Only reachable when the caller could not find a playtest session to end
+		-- from. Stops a Run-mode session, which has no separate DataModel.
+		pcall(function()
+			RunService:Stop()
+		end)
+
+		task.wait(SETTLE_SECONDS)
+		local after = state()
+		return {
+			changed = after.isRunning ~= before.isRunning or after.isEdit ~= before.isEdit,
+			state = after,
+		}
+	end
+
+	if pending then
+		Dispatch.fail(
+			"ALREADY_RUNNING",
+			"A test is already running.",
+			"Stop it first, or call with op 'state' to see how it is doing."
+		)
+	end
+
+	-- ExecutePlayModeAsync rejects a nil argument outright -- "Argument 1 missing
+	-- or nil" -- even though the parameter is a Variant, so an omitted `args`
+	-- becomes an empty string rather than a failed launch.
+	local args = if params.args == nil then "" else params.args
+	if op == "play" then
+		launch("ExecutePlayModeAsync", function()
+			return service():ExecutePlayModeAsync(args)
+		end)
+	elseif op == "run" then
+		launch("ExecuteRunModeAsync", function()
+			return service():ExecuteRunModeAsync(args)
+		end)
+	elseif op == "multiplayer" then
+		local players = tonumber(params.players) or 2
+		if players < 1 or players > 8 then
+			Dispatch.fail("BAD_PARAMS", "players must be between 1 and 8.")
+		end
+		launch("ExecuteMultiplayerTestAsync", function()
+			return service():ExecuteMultiplayerTestAsync(players, args)
+		end)
+	else
+		Dispatch.fail("BAD_PARAMS", string.format("unknown op %q", tostring(op)))
+	end
+
+	task.wait(SETTLE_SECONDS)
+	local after = state()
+
+	-- Whether the mode moved, not whether the call was accepted. Accepting and
+	-- doing nothing is exactly how RunService:Run behaved here.
+	local moved = after.isRunning ~= before.isRunning
+		or after.isEdit ~= before.isEdit
+		or after.editModeActive ~= before.editModeActive
+
+	return {
+		changed = moved or after.testPending,
+		reason = if after.lastError then after.lastError
+			elseif not moved and not after.testPending then "Studio accepted the call but the mode did not change"
+			else nil,
+		state = after,
+	}
+end
+
+-- Panel-only stop, also usable in the client view which cannot make HTTP calls.
+-- No state-change listener is installed: manual Play stays available while OFF.
+function Playtest.stopLocal()
+	if not RunService:IsEdit() and RunService:IsClient() and not RunService:IsServer() then
+		service():LeaveTest()
+	elseif not RunService:IsEdit() and not RunService:IsRunMode() then
+		Playtest.control({ op = "endTest" })
+	else
+		Playtest.control({ op = "stop" })
+	end
+end
+
+function Playtest.register()
+	Dispatch.registerAll("playtest", {
+		control = Playtest.control,
+	})
+end
+
+return Playtest

package/plugin/src/handlers/Scripts.luau

@@ -56,11 +56,6 @@ local function resolveScript(path: string): LuaSourceContainer
 	return instance :: LuaSourceContainer
 end
 
---[[
-	Reads source, optionally a line window. `startLine`/`endLine` are 1-based and
-	inclusive, matching the numbers script_edit takes back, so a read and a write
-	need no off-by-one conversion between them.
-]]
 --[[
 	A short fingerprint of a script's source, for detecting that it moved.
 
@@ -136,6 +131,11 @@ local function syncedFile(target: Instance): string?
 	return name
 end
 
+--[[
+	Reads source, optionally a line window. `startLine`/`endLine` are 1-based and
+	inclusive, matching the numbers script_edit takes back, so a read and a write
+	need no off-by-one conversion between them.
+]]
 function Scripts.read(params: { [string]: any }): { [string]: any }
 	local paths = params.paths
 	if typeof(paths) ~= "table" or #paths == 0 then
@@ -381,12 +381,45 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 		)
 	end
 
+	local function badPattern(reason: any): never
+		Dispatch.fail(
+			"BAD_PATTERN",
+			string.format("%s is not a valid Lua pattern: %s", pattern, tostring(reason)),
+			"Lua patterns escape with %, not backslash, and have no alternation. "
+				.. "Set `literal` to search for the text exactly as written."
+		)
+	end
+
+	--[[
+		One search over the whole file before splitting it into lines.
+
+		Most scripts in a place do not contain what is being looked for, and
+		splitting each into a line table only to find nothing was most of the cost
+		of a place-wide search. A pattern that matches no line cannot match the
+		whole file either -- except one anchored with `^` or `$`, which mean line
+		ends here but file ends there, so those skip this shortcut.
+	]]
+	-- Any trailing `$` counts, escaped or not: skipping the shortcut costs speed,
+	-- taking it wrongly would hide matches.
+	local anchored = not literal and (string.sub(needle, 1, 1) == "^" or string.sub(needle, -1) == "$")
+
 	local matches: { { [string]: any } } = {}
 	local total = 0
 	local memo: Paths.NameIndex = {}
 
 	for _, target in targets do
-		local lines = TextEdit.toLines(ScriptEdit.read(target))
+		local source = ScriptEdit.read(target)
+		if not anchored then
+			local ok, found = pcall(string.find, if ignoreCase then string.lower(source) else source, needle, 1, literal)
+			if not ok then
+				badPattern(found)
+			end
+			if not found then
+				continue
+			end
+		end
+
+		local lines = TextEdit.toLines(source)
 		local path: string? = nil
 
 		for number, line in lines do
@@ -395,12 +428,7 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 			-- has to be caught and reported as a pattern problem, not a no-match.
 			local ok, from = pcall(string.find, haystack, needle, 1, literal)
 			if not ok then
-				Dispatch.fail(
-					"BAD_PATTERN",
-					string.format("%s is not a valid Lua pattern: %s", pattern, tostring(from)),
-					"Lua patterns escape with %, not backslash, and have no alternation. "
-						.. "Set `literal` to search for the text exactly as written."
-				)
+				badPattern(from)
 			end
 			if not from then
 				continue
@@ -440,12 +468,6 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Creates scripts. Source is assigned directly here rather than through
-	`UpdateSourceAsync`: the instance does not exist yet, so nothing can have it
-	open in the editor and there is no buffer to conflict with. Every later edit
-	goes through the editor path.
-]]
 --[[
 	Names the starter container a script was just parented into, or nil.
 
@@ -457,6 +479,14 @@ end
 	Client over LocalScript" advice writes a double-running script and is given
 	no way to find out.
 ]]
+--[[
+	Assigning `Source` fails at 200,000 characters or more ("Provided string
+	length ... is greater than or equal to max length (200000)"), while
+	`UpdateSourceAsync` takes far more -- measured writing 279,000. Sources at
+	the limit are written through the editor instead of refused.
+]]
+local SOURCE_PROPERTY_LIMIT = 200000
+
 local STARTER_CONTAINERS = {
 	"StarterGui",
 	"StarterPack",
@@ -473,6 +503,12 @@ local function starterContainer(instance: Instance): string?
 	return nil
 end
 
+--[[
+	Creates scripts. Source is assigned directly here rather than through
+	`UpdateSourceAsync`: the instance does not exist yet, so nothing can have it
+	open in the editor and there is no buffer to conflict with. Every later edit
+	goes through the editor path.
+]]
 function Scripts.create(params: { [string]: any }): { [string]: any }
 	local requests = params.scripts
 	if typeof(requests) ~= "table" or #requests == 0 then
@@ -503,6 +539,7 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 	-- No shared path memo here: each creation changes its parent's children, so a
 	-- cached sibling grouping would go stale mid-batch and mis-number the paths.
 	local warnings: { string } = {}
+	local oversized: { { target: LuaSourceContainer, source: string } } = {}
 
 	local created, recorded = Undo.record("StudioMCP.ScriptCreate", "MCP create script", function()
 		local created: { { [string]: any } } = {}
@@ -513,7 +550,11 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 
 			instance.Name = request.name
 			if typeof(request.source) == "string" then
-				(instance :: ScriptEdit.SourceContainer).Source = request.source
+				if #request.source < SOURCE_PROPERTY_LIMIT then
+					(instance :: ScriptEdit.SourceContainer).Source = request.source
+				else
+					table.insert(oversized, { target = instance, source = request.source })
+				end
 			end
 
 			if typeof(request.runContext) == "string" and instance:IsA("Script") then
@@ -605,6 +646,14 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 		return created
 	end)
 
+	-- After the recording, because the editor write yields. Undoing the create
+	-- still removes these scripts whole, source and all.
+	for _, entry in oversized do
+		ScriptEdit.write(entry.target, function()
+			return entry.source
+		end)
+	end
+
 	return {
 		items = created,
 		undoStep = if recorded then "MCP create script" else nil,