@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

package/plugin/src/ScriptEdit.luau

@@ -38,6 +38,70 @@ function ScriptEdit.read(target: LuaSourceContainer): string
 	return (target :: SourceContainer).Source
 end
 
+--[[
+	A short fingerprint of a script's source, for detecting that it moved.
+
+	Handed out by `script_read` and passed back to `script_edit`, and kept by
+	`sync` to tell which side of a synced script changed. `edit`, which refuses to write when
+	the live source no longer matches. That is the only thing standing between
+	two agents on one place and a silent overwrite: a line-range edit computed
+	against source somebody has since changed still applies cleanly, it just
+	applies to the wrong lines, and nothing anywhere reports it.
+
+	FNV-1a over the whole string, with the length appended. Not a security
+	hash and does not need to be -- it is guarding against ordinary concurrent
+	editing, not against someone constructing a collision. The length is there
+	because it is free and rules out the whole class of same-length accidents.
+
+	The multiply is split into 16-bit halves on purpose. `hash * 16777619` with
+	a 32-bit hash reaches 2^56, past the 2^53 where doubles stop being exact,
+	so the low bits -- the ones that carry the mixing -- would be quietly
+	rounded away.
+]]
+function ScriptEdit.fingerprint(source: string): string
+	local hash = 2166136261
+	local length = #source
+	local index = 1
+	while index <= length do
+		local last = math.min(index + 511, length)
+		local chunk = { string.byte(source, index, last) }
+		for _, byte in chunk do
+			hash = bit32.bxor(hash, byte)
+			local low = bit32.band(hash, 0xFFFF)
+			local high = bit32.rshift(hash, 16)
+			-- 16777619 == 0x01000193, so 0x0193 is 403 and 0x0100 is 256.
+			hash = bit32.band(low * 403 + bit32.lshift(bit32.band(high * 403 + low * 256, 0xFFFF), 16), 0xFFFFFFFF)
+		end
+		index = last + 1
+	end
+	return string.format("%08x-%x", hash, length)
+end
+
+--[[
+	A script's revision, computed once per distinct text.
+
+	Fingerprinting walks every byte in Luau, and `sync` asks for the revision of
+	every script in a place on each run -- so a place with megabytes of code paid
+	for hashing all of it after every save, to learn that one file changed. The
+	text is kept beside its revision per script, and a lookup whose text is the
+	same string skips the hash: Luau interns strings, so that comparison is a
+	pointer check, not a second pass over the source.
+
+	Weak keys, so a deleted script's entry goes with it.
+]]
+local revisions: { [Instance]: { source: string, revision: string } } = setmetatable({}, { __mode = "k" }) :: any
+
+function ScriptEdit.revisionOf(target: LuaSourceContainer, source: string?): string
+	local text = source or ScriptEdit.read(target)
+	local cached = revisions[target]
+	if cached ~= nil and cached.source == text then
+		return cached.revision
+	end
+	local revision = ScriptEdit.fingerprint(text)
+	revisions[target] = { source = text, revision = revision }
+	return revision
+end
+
 --[[
 	Makes sure a write that reported success actually stuck.
 
@@ -59,11 +123,16 @@ end
 	caused this is only reachable when the USER opens one in the same moment we
 	write to it -- rare, and cheap enough to cover anyway. One settle, one read,
 	and a rewrite if it did not take.
+
+	A rewrite only ever replaces `original`, the text our write replaced. That
+	is what a finishing load puts back. Anything else in the buffer is somebody
+	typing after the write landed, and rewriting it "to make ours stick" would
+	delete their work -- so that is reported instead, and their text is kept.
 ]]
 local SETTLE = 0.2
 
-local function confirm(target: LuaSourceContainer, produced: string?)
-	if produced == nil then
+local function confirm(target: LuaSourceContainer, produced: string?, original: string?)
+	if produced == nil or produced == original then
 		return
 	end
 
@@ -86,20 +155,35 @@ local function confirm(target: LuaSourceContainer, produced: string?)
 	-- repeating will not fix.
 	for _ = 1, 3 do
 		task.wait(SETTLE)
-		if ScriptEdit.read(target) == produced then
+		local current = ScriptEdit.read(target)
+		if current == produced then
 			return
 		end
+		if current ~= original then
+			break
+		end
 		pcall(function()
-			ScriptEditorService:UpdateSourceAsync(target, function()
-				return produced
+			ScriptEditorService:UpdateSourceAsync(target, function(source)
+				-- Checked again at commit time: the user may have typed since the read.
+				return if source == original then produced :: string else source
 			end)
 		end)
 	end
+
+	if ScriptEdit.read(target) ~= produced then
+		Dispatch.fail(
+			"VERIFY_FAILED",
+			string.format("%s changed while the write was being confirmed.", target:GetFullName()),
+			"The newer text was kept, not overwritten. Read the script again before retrying."
+		)
+	end
 end
 
 --[[
-	Replaces source through the editor. `transform` receives the current text and
-	returns the replacement; returning the input unchanged is a no-op.
+	Replaces source through the editor. `transform` receives the current text --
+	read at commit time, so it is where a "has this changed since I read it"
+	check belongs -- and returns the replacement; returning the input unchanged
+	is a no-op.
 
 	`transform` is allowed to raise a structured Dispatch failure -- a bad line
 	range is only discoverable once the authoritative source is in hand. Such a
@@ -115,10 +199,12 @@ function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> str
 	local pending: any = nil
 
 	local produced: string? = nil
+	local original: string? = nil
 	local ok, err = pcall(function()
 		ScriptEditorService:UpdateSourceAsync(target, function(source)
 			local applied, result = pcall(transform, source)
 			if applied then
+				original = source
 				produced = result
 				return result
 			end
@@ -131,7 +217,7 @@ function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> str
 		error(pending, 0)
 	end
 	if ok then
-		confirm(target, produced)
+		confirm(target, produced, original)
 		return
 	end
 

package/plugin/src/Serialize.luau

@@ -413,7 +413,22 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		end
 		-- 0-255 is a common mistake and unambiguous to detect, so accept it.
 		local scale = if numbers[1] > 1 or numbers[2] > 1 or numbers[3] > 1 then 255 else 1
-		return true, Color3.new(numbers[1] / scale, numbers[2] / scale, numbers[3] / scale), nil
+		--[[
+			Snapped back to an exact 1/255 step when the text is that step
+			rounded to PRECISION places.
+
+			Part colours are stored as bytes. "0.7686" is how 196/255 prints,
+			but it is a hair under it, and the engine truncates on the way in
+			-- so a colour read and written back came out as 195, one step
+			darker each round trip. A value genuinely between steps, like 0.5,
+			is further than half a printed digit from one and is left alone.
+		]]
+		local function component(value: number): number
+			local unit = value / scale
+			local step = math.round(unit * 255) / 255
+			return if math.abs(unit - step) <= 0.5 * 10 ^ -PRECISION then step else unit
+		end
+		return true, Color3.new(component(numbers[1]), component(numbers[2]), component(numbers[3])), nil
 	end
 	if valueType == "BrickColor" then
 		-- Cast because the API definitions type this overload as a literal union

package/plugin/src/Transport.luau

@@ -26,7 +26,9 @@ local Transport = {}
 export type Status = "disconnected" | "connecting" | "connected"
 
 type Callbacks = {
-	onCommand: (id: string, op: string, params: { [string]: any }?) -> (),
+	-- `deadlineMs` is when the server stops waiting for the reply, on this
+	-- machine's clock: the server sends a duration, never a time (see Command.timeoutMs).
+	onCommand: (id: string, op: string, params: { [string]: any }?, deadlineMs: number?) -> (),
 	onStatus: (status: Status, detail: string?) -> (),
 	--[[
 		Anything the bridge wants to tell this plugin that is not a command.
@@ -243,7 +245,8 @@ local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
 	local id = frame.id
 	local op = frame.op
 	if typeof(id) == "string" and typeof(op) == "string" then
-		callbacks.onCommand(id, op, frame.params)
+		local deadline = if typeof(frame.timeoutMs) == "number" then DateTime.now().UnixTimestampMillis + frame.timeoutMs else nil
+		callbacks.onCommand(id, op, frame.params, deadline)
 		return
 	end
 	if typeof(frame.event) == "string" then

package/plugin/src/Undo.luau

@@ -18,6 +18,8 @@
 
 local ChangeHistoryService = game:GetService("ChangeHistoryService")
 
+local Dispatch = require(script.Parent.Dispatch)
+
 local Undo = {}
 
 --[[
@@ -132,13 +134,57 @@ end
 	is something tools tell the agent, and therefore the user, so it has to be
 	observed rather than assumed: a claim of "one Ctrl+Z" that silently degrades
 	to no undo entry at all is worse than no claim.
+
+	Refusing instead is not an option either: Studio opens no recording at all
+	inside a running playtest (measured), so a refusal would make every write
+	tool unusable against the runtime session.
+]]
+
+-- Opens a recording, or nil. Guarded because an engine error here must not
+-- escape with the lock held.
+local function begin(name: string, displayName: string): string?
+	local ok, identifier = pcall(function()
+		return ChangeHistoryService:TryBeginRecording(name, displayName)
+	end)
+	return if ok then identifier else nil
+end
+
+--[[
+	Runs `body` after the lock is ours, unless the request expired while it
+	waited. The server stops waiting at its timeout, so work that starts later
+	would be reported to nobody -- and an agent told "timed out" is likely to
+	retry it.
 ]]
+local function run<T>(body: () -> T): (boolean, any)
+	return pcall(function()
+		Dispatch.checkDeadline()
+		return body()
+	end)
+end
+
+-- Closes a recording. A failure here is reported, with the lock released, as
+-- an outcome the agent must check rather than assume.
+local function finish(identifier: string, operation: Enum.FinishRecordingOperation, acquired: boolean)
+	local ok, err = pcall(function()
+		ChangeHistoryService:FinishRecording(identifier, operation)
+	end)
+	if ok then
+		return
+	end
+	release(acquired)
+	Dispatch.fail(
+		"UNDO_FAILED",
+		string.format("Studio could not close the undo recording: %s", tostring(err)),
+		"The change may or may not have applied. Inspect the affected instances before retrying."
+	)
+end
+
 function Undo.record<T>(name: string, displayName: string, body: () -> T): (T, boolean)
 	local acquired = acquire()
 
-	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	local identifier = begin(name, displayName)
 	if not identifier then
-		local ok, result = pcall(body)
+		local ok, result = run(body)
 		release(acquired)
 		if not ok then
 			error(result, 0)
@@ -146,15 +192,15 @@ function Undo.record<T>(name: string, displayName: string, body: () -> T): (T, b
 		return result, false
 	end
 
-	local ok, result = pcall(body)
+	local ok, result = run(body)
 	if ok then
-		ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+		finish(identifier, Enum.FinishRecordingOperation.Commit, acquired)
 		release(acquired)
 		return result, true
 	end
 
-	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Cancel)
-	dropRedo()
+	finish(identifier, Enum.FinishRecordingOperation.Cancel, acquired)
+	pcall(dropRedo)
 	release(acquired)
 	error(result, 0)
 end
@@ -167,9 +213,9 @@ end
 function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T): (T, boolean)
 	local acquired = acquire()
 
-	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	local identifier = begin(name, displayName)
 	if not identifier then
-		local ok, result = pcall(body)
+		local ok, result = run(body)
 		release(acquired)
 		if not ok then
 			error(result, 0)
@@ -177,8 +223,8 @@ function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T)
 		return result, false
 	end
 
-	local ok, result = pcall(body)
-	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+	local ok, result = run(body)
+	finish(identifier, Enum.FinishRecordingOperation.Commit, acquired)
 	release(acquired)
 	if not ok then
 		error(result, 0)
@@ -186,4 +232,22 @@ function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T)
 	return result, true
 end
 
+--[[
+	Holds the mutation lock without opening a recording.
+
+	For script source, whose undo is the script editor's own, per document --
+	a recording would add an empty step, not make the edit undoable. The lock
+	is what matters: two batches writing the same scripts must not interleave
+	their writes and their rollbacks.
+]]
+function Undo.exclusive<T>(body: () -> T): T
+	local acquired = acquire()
+	local ok, result = run(body)
+	release(acquired)
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+
 return Undo