@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/handlers/Playtest.luau

@@ -0,0 +1,205 @@
+--!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

package/plugin/src/handlers/Scripts.luau

@@ -0,0 +1,387 @@
+--!strict
+--[[
+	Script reading, searching, editing and creation.
+
+	Everything here that writes goes through `ScriptEdit`, which routes the change
+	through `ScriptEditorService:UpdateSourceAsync` rather than assigning
+	`script.Source`. That is the difference between an edit the Studio editor
+	agrees with and one that silently loses whatever the user had typed but not
+	saved. Reads use the editor buffer for the same reason: handing an agent stale
+	source makes it "fix" changes the user just made.
+
+	Edits are also wrapped in a single `Undo` recording, so a batch across ten
+	scripts is one Ctrl+Z, and a batch that fails half way is rolled back rather
+	than left half applied.
+
+	The text manipulation itself lives in `TextEdit`, which has no Roblox
+	dependencies and is unit tested.
+]]
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Scope = require(script.Parent.Parent.Scope)
+local ScriptEdit = require(script.Parent.Parent.ScriptEdit)
+local TextEdit = require(script.Parent.Parent.TextEdit)
+local Undo = require(script.Parent.Parent.Undo)
+
+-- Reading every script's editor buffer is a service call each. A place with more
+-- scripts than this is better served by narrowing `path` than by a slow grep
+-- that blocks Studio's main thread.
+local MAX_SCRIPTS = 3_000
+local MAX_MATCHES = 500
+local DEFAULT_CONTEXT = 0
+
+local CREATABLE = {
+	Script = true,
+	LocalScript = true,
+	ModuleScript = true,
+}
+
+local Scripts = {}
+
+--[[
+	Resolves a path and insists it holds Luau. Pointing a script tool at an
+	ordinary instance otherwise fails later with a confusing property error.
+]]
+local function resolveScript(path: string): LuaSourceContainer
+	local instance = Paths.resolve(path)
+	if not ScriptEdit.isScript(instance) then
+		Dispatch.fail(
+			"NOT_A_SCRIPT",
+			string.format('"%s" is a %s, not a script.', path, instance.ClassName),
+			"Script tools accept Script, LocalScript and ModuleScript. Use `inspect` "
+				.. "for other instances, or `find` with className LuaSourceContainer to locate scripts."
+		)
+	end
+	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.
+]]
+function Scripts.read(params: { [string]: any }): { [string]: any }
+	local paths = params.paths
+	if typeof(paths) ~= "table" or #paths == 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"script_read requires a non-empty `paths` array.",
+			"Use `find` with className LuaSourceContainer to locate scripts."
+		)
+	end
+
+	local items: { { [string]: any } } = {}
+	local failures: { string } = {}
+	local memo: Paths.NameIndex = {}
+
+	for _, path in paths do
+		local ok, resolved = pcall(resolveScript, path)
+		if not ok then
+			local err = resolved :: any
+			local reason = if typeof(err) == "table"
+				then (if err.hint then err.message .. " " .. err.hint else err.message)
+				else tostring(err)
+			table.insert(failures, string.format("%s: %s", path, reason))
+			continue
+		end
+
+		local target = resolved :: LuaSourceContainer
+		local lines = TextEdit.toLines(ScriptEdit.read(target))
+		local startLine = math.max(tonumber(params.startLine) or 1, 1)
+		local endLine = math.min(tonumber(params.endLine) or #lines, #lines)
+
+		local window: { string } = {}
+		table.move(lines, startLine, endLine, 1, window)
+
+		table.insert(items, {
+			path = Paths.of(target, memo),
+			className = target.ClassName,
+			lineCount = #lines,
+			startLine = startLine,
+			source = table.concat(window, "\n"),
+		})
+	end
+
+	return { items = items, failures = failures }
+end
+
+--[[
+	Applies every edit in a batch, or none of them.
+
+	Atomicity here cannot come from ChangeHistoryService. A recording captures
+	instance changes, but `UpdateSourceAsync` goes through the script editor's own
+	per-document history, so cancelling a recording leaves an already-written
+	script edited -- measured, not assumed. Wrapping this in `Undo.record` would
+	therefore promise a rollback that never happens.
+
+	So the batch is a two-phase commit instead. Phase one reads and transforms
+	every script without writing anything, which is where essentially all failures
+	live: a missing `find`, an ambiguous one, a bad line range, conflicting edits.
+	Phase two writes the finished text. If a write fails there -- realistically
+	only a locked or package-owned script -- the scripts already written are
+	restored from the source captured in phase one.
+]]
+function Scripts.edit(params: { [string]: any }): { [string]: any }
+	local edits = params.edits
+	if typeof(edits) ~= "table" or #edits == 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"script_edit requires a non-empty `edits` array.",
+			"Each edit needs a `path` plus one of `find`/`replace`, "
+				.. "`startLine`/`replacement`, or `source`."
+		)
+	end
+
+	local order: { LuaSourceContainer } = {}
+	local grouped: { [Instance]: { TextEdit.Edit } } = {}
+	for position, edit in edits do
+		TextEdit.validate(edit, position)
+		local target = resolveScript(edit.path)
+		local bucket = grouped[target]
+		if not bucket then
+			bucket = {}
+			grouped[target] = bucket
+			table.insert(order, target)
+		end
+		table.insert(bucket :: { TextEdit.Edit }, edit)
+	end
+
+	-- Phase one: transform everything in memory. Any failure raises here, with
+	-- nothing written and the place untouched.
+	type Pending = { target: LuaSourceContainer, before: string, after: string }
+	local pending: { Pending } = {}
+	for _, target in order do
+		local before = ScriptEdit.read(target)
+		local after = TextEdit.apply(target:GetFullName(), before, grouped[target] :: { TextEdit.Edit })
+		table.insert(pending, { target = target, before = before, after = after })
+	end
+
+	-- Phase two: write. `written` is the compensation log for a mid-batch failure.
+	local written: { Pending } = {}
+	local memo: Paths.NameIndex = {}
+	local results: { { [string]: any } } = {}
+
+	for _, entry in pending do
+		-- Wrapped in a closure rather than passed to pcall directly: `write`
+		-- returns nothing, and pcall's typed signature expects a value back.
+		local ok, err = pcall(function()
+			ScriptEdit.write(entry.target, function()
+				return entry.after
+			end)
+		end)
+
+		if not ok then
+			for index = #written, 1, -1 do
+				local done = written[index]
+				-- Best effort: a restore that fails leaves that script edited, and
+				-- the original error still describes what actually went wrong.
+				pcall(function()
+					ScriptEdit.write(done.target, function()
+						return done.before
+					end)
+				end)
+			end
+			error(err, 0)
+		end
+
+		table.insert(written, entry)
+		table.insert(results, {
+			path = Paths.of(entry.target, memo),
+			className = entry.target.ClassName,
+			edits = #(grouped[entry.target] :: { TextEdit.Edit }),
+			lineCount = #TextEdit.toLines(entry.after),
+			lineDelta = #TextEdit.toLines(entry.after) - #TextEdit.toLines(entry.before),
+		})
+	end
+
+	return { items = results }
+end
+
+--[[
+	Searches script source. Matches come from the editor buffer, so text the user
+	has typed but not saved is found too -- which is the state an agent about to
+	edit the file actually needs to see.
+]]
+function Scripts.grep(params: { [string]: any }): { [string]: any }
+	local pattern = params.pattern
+	if typeof(pattern) ~= "string" or pattern == "" then
+		Dispatch.fail("BAD_PARAMS", "script_grep requires a `pattern`.")
+	end
+
+	local root = if params.path then Paths.resolve(params.path) else game
+	local literal = params.literal == true
+	local ignoreCase = params.ignoreCase == true
+	local contextLines = math.clamp(tonumber(params.contextLines) or DEFAULT_CONTEXT, 0, 10)
+	local limit = math.min(tonumber(params.limit) or 100, MAX_MATCHES)
+	local offset = tonumber(params.offset) or 0
+	local classFilter = params.className
+
+	local needle = if ignoreCase then string.lower(pattern) else pattern
+
+	local targets: { LuaSourceContainer } = {}
+	for _, instance in root:GetDescendants() do
+		if not instance:IsA("LuaSourceContainer") then
+			continue
+		end
+		if root == game and Scope.isNoisy(instance) then
+			continue
+		end
+		if classFilter and not instance:IsA(classFilter) then
+			continue
+		end
+		table.insert(targets, instance)
+	end
+
+	if #targets > MAX_SCRIPTS then
+		Dispatch.fail(
+			"TOO_BROAD",
+			string.format("That search covers %d scripts, over the %d limit.", #targets, MAX_SCRIPTS),
+			"Narrow it with `path` to search one service or folder instead of the whole place."
+		)
+	end
+
+	local matches: { { [string]: any } } = {}
+	local total = 0
+	local memo: Paths.NameIndex = {}
+
+	for _, target in targets do
+		local lines = TextEdit.toLines(ScriptEdit.read(target))
+		local path: string? = nil
+
+		for number, line in lines do
+			local haystack = if ignoreCase then string.lower(line) else line
+			-- An invalid Lua pattern raises rather than simply not matching, so it
+			-- 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."
+				)
+			end
+			if not from then
+				continue
+			end
+
+			total += 1
+			if total <= offset or #matches >= limit then
+				continue
+			end
+
+			if not path then
+				path = Paths.of(target, memo)
+			end
+
+			local entry: { [string]: any } = {
+				path = path,
+				line = number,
+				text = line,
+			}
+			if contextLines > 0 then
+				local before: { string } = {}
+				local after: { string } = {}
+				table.move(lines, math.max(number - contextLines, 1), number - 1, 1, before)
+				table.move(lines, number + 1, math.min(number + contextLines, #lines), 1, after)
+				entry.before = before
+				entry.after = after
+			end
+			table.insert(matches, entry)
+		end
+	end
+
+	return {
+		items = matches,
+		total = total,
+		offset = offset,
+		searched = #targets,
+	}
+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
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"script_create requires a non-empty `scripts` array.",
+			"Each entry needs `parent`, `name` and `className`."
+		)
+	end
+
+	for position, request in requests do
+		if typeof(request.name) ~= "string" or request.name == "" then
+			Dispatch.fail("BAD_PARAMS", string.format("scripts[%d] has no `name`.", position))
+		end
+		if not CREATABLE[request.className] then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format('scripts[%d] has className "%s".', position, tostring(request.className)),
+				"Use Script, LocalScript or ModuleScript. Prefer a Script with "
+					.. "runContext Client over LocalScript in new work."
+			)
+		end
+	end
+
+	-- 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 created, recorded = Undo.record("StudioMCP.ScriptCreate", "MCP create script", function()
+		local created: { { [string]: any } } = {}
+
+		for _, request in requests do
+			local parent = Paths.resolve(request.parent)
+			local instance = Instance.new(request.className) :: LuaSourceContainer
+
+			instance.Name = request.name
+			if typeof(request.source) == "string" then
+				(instance :: ScriptEdit.SourceContainer).Source = request.source
+			end
+
+			if typeof(request.runContext) == "string" and instance:IsA("Script") then
+				local ok, runContext = pcall(function()
+					return (Enum.RunContext :: any)[request.runContext]
+				end)
+				if not ok or runContext == nil then
+					Dispatch.fail(
+						"BAD_PARAMS",
+						string.format('"%s" is not a RunContext.', tostring(request.runContext)),
+						"Use Legacy, Server or Client."
+					)
+				end
+				instance.RunContext = runContext
+			end
+			if request.disabled == true and instance:IsA("BaseScript") then
+				instance.Disabled = true
+			end
+
+			instance.Parent = parent
+
+			table.insert(created, {
+				path = Paths.of(instance),
+				className = instance.ClassName,
+			})
+		end
+
+		return created
+	end)
+
+	return { items = created, undoStep = if recorded then "MCP create script" else nil }
+end
+
+function Scripts.register()
+	Dispatch.registerAll("script", {
+		read = Scripts.read,
+		edit = Scripts.edit,
+		grep = Scripts.grep,
+		create = Scripts.create,
+	})
+end
+
+return Scripts