@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.7

package/plugin/src/Secret.luau

@@ -0,0 +1,86 @@
+--!strict
+--[[
+	Keeps a typed secret out of everything that remembers.
+
+	The panel is built to remember what you type. The line is echoed into the log
+	under "you", it goes into the up-arrow history, the log can be copied to the
+	clipboard with `copy`, and the whole widget ends up in screenshots -- which
+	this very server takes on request. Every one of those is correct behaviour
+	for `theme dark` and a disaster for an API key: a credential that can publish
+	assets under the user's name would sit in a scrollback that gets pasted into
+	a bug report.
+
+	So the one command that carries a secret is masked at every point where a
+	line is kept, and that masking lives here rather than in `Commands` because
+	two unrelated files -- the echo and the history -- both have to do it, and a
+	secret protected in one of two places is not protected.
+
+	Masking, not dropping. `cloud key ****` in the log still tells the user that
+	the command ran; a line that vanished would read as the panel ignoring them,
+	and the next thing a person does about that is type it again.
+]]
+
+local Secret = {}
+
+--[[
+	Commands whose arguments are secret, and from which word onwards.
+
+	Keyed by "command subcommand" so `cloud key <secret>` is covered and `cloud
+	test` -- which carries nothing -- is not masked into uselessness. The user id
+	is masked too. It is not a credential and it is on a public profile URL, but
+	it names the account the key belongs to, and a screenshot showing both is
+	worth more to somebody than a screenshot showing either.
+]]
+--[[
+	Commands whose arguments are secret, and from which word onwards.
+
+	Keyed by "command subcommand" so `cloud key <secret>` is covered and `cloud
+	test` -- which carries nothing -- is not masked into uselessness.
+
+	ONLY the key. The user, group, universe and place ids were masked here too
+	at first, which was theatre: they are public -- a user id is in the profile
+	URL and a universe id is on the game's dashboard page -- and the reply that
+	confirms each one prints it back in full anyway, so the dots hid a value
+	from the same log line that then showed it. Masking something that is about
+	to be displayed teaches a reader that the dots mean nothing, which is
+	exactly the wrong lesson for the one line where they do.
+]]
+local SECRET_FROM: { [string]: number } = {
+	["cloud key"] = 3,
+}
+
+--[[
+	Returns the line as it is safe to display, and whether anything was hidden.
+
+	The caller gets the flag because "this was masked" is worth saying once, next
+	to the echoed line -- otherwise a user who sees dots where they typed a key
+	cannot tell whether the panel hid it or mangled it.
+]]
+function Secret.mask(line: string): (string, boolean)
+	local words: { string } = {}
+	for word in string.gmatch(line, "%S+") do
+		table.insert(words, word)
+	end
+	if #words < 2 then
+		return line, false
+	end
+
+	local from = SECRET_FROM[string.lower(words[1]) .. " " .. string.lower(words[2])]
+	if from == nil or #words < from then
+		return line, false
+	end
+
+	--[[
+		One fixed marker for everything from `from` on, not one per character
+		and not one per word.
+
+		Length is information: eight dots against thirty says which of two things
+		was typed, and for a key it narrows a guess. Every masked value looks
+		identical, whatever was actually there.
+	]]
+	local masked = table.move(words, 1, from - 1, 1, {} :: { string })
+	table.insert(masked, "••••••••")
+	return table.concat(masked, " "), true
+end
+
+return Secret

package/plugin/src/Serialize.luau

@@ -13,8 +13,21 @@
 	straight back without the agent reformatting it.
 ]]
 
+local Paths = require(script.Parent.Paths)
+
 local Serialize = {}
 
+--[[
+	Marks a failure that means "the instance is not there" rather than "this
+	value is wrong".
+
+	The create handler retries only these, once the whole batch is attached, so
+	a reference to a sibling made in the same call resolves. Anything else is a
+	real mistake and is reported straight away.
+]]
+local UNRESOLVED_PREFIX = "[unresolved] "
+Serialize.UNRESOLVED_PREFIX = UNRESOLVED_PREFIX
+
 -- Floats are rounded before display: Studio reports positions like
 -- 12.000000476837158, which costs tokens and means nothing to the caller.
 local PRECISION = 4
@@ -87,11 +100,54 @@ function Serialize.value(value: any): any
 	if kind == "UDim" then
 		return string.format("{%s, %s}", num(value.Scale), num(value.Offset))
 	end
+	if kind == "Font" then
+		--[[
+			Written so it can be read back, which `tostring` is not.
+
+			A Font stringifies as `Font { Family = rbxasset://..., Weight = Bold,
+			Style = Normal }`, which nothing here can parse. The family, weight
+			and style are all there is to one, so they are written plainly and
+			separated the way a composite value is elsewhere in this module.
+		]]
+		return string.format(
+			"%s | %s | %s",
+			value.Family,
+			value.Weight.Name,
+			value.Style.Name
+		)
+	end
 	if kind == "EnumItem" then
 		return string.format("Enum.%s.%s", tostring(value.EnumType), value.Name)
 	end
+	if kind == "Content" then
+		--[[
+			Written as the bare URI so it can be read back.
+
+			`tostring` on a Content gives `Content{SourceType=Uri,
+			Uri=rbxassetid://123}`, which `parse` cannot take. A Content that
+			holds an Object or no source at all has no URI to give, so those are
+			named rather than rendered as an empty string that would read as
+			"cleared".
+		]]
+		if value.Uri then
+			return value.Uri
+		end
+		if value.Object then
+			return Paths.of(value.Object)
+		end
+		return ""
+	end
 	if kind == "Instance" then
-		return value:GetFullName()
+		--[[
+			Formatted as an address, not as a display name.
+
+			`GetFullName` writes "StarterPack.Pistol.Handle" for both of two
+			Tools named Pistol, so reading a Motor6D's Part1 and writing it back
+			pointed at the wrong one -- silently, since both paths resolve.
+			`Paths.of` adds the [n] that tells them apart, which is what makes a
+			value read here safe to write straight back.
+		]]
+		return Paths.of(value)
 	end
 	if kind == "NumberRange" then
 		return string.format("%s..%s", num(value.Min), num(value.Max))
@@ -176,6 +232,51 @@ local function scanTokens(text: string): { number }
 	return numbers
 end
 
+--[[
+	ColorSequence and NumberSequence.
+
+	`Serialize.value` has always WRITTEN these -- "0=1, 0, 0 1=0, 0, 1" for a
+	red-to-blue gradient -- and `parse` had no branch for either, so every one of
+	them could be read and none could be written back. That is not a corner:
+	ColorSequence and NumberSequence are what ParticleEmitter, Beam, Trail and
+	UIGradient are made of, so recolouring any effect fell out of `modify`
+	entirely and needed `execute_luau`. Found by auditing the round trip rather
+	than by hitting it.
+
+	Keypoints are split on the "<time>=" markers rather than on whitespace,
+	because the VALUE of a ColorSequence keypoint contains both commas and
+	spaces of its own and nothing else can tell the two apart.
+
+	A bare value is also accepted and means a constant sequence: `Color3` text
+	for a ColorSequence, one number for a NumberSequence. People write
+	`Color = "1, 0, 0"` meaning solid red, and refusing that to insist on
+	"0=1, 0, 0 1=1, 0, 0" would be pedantry.
+]]
+local function splitKeypoints(text: string): { { time: number, value: string } }
+	local marks: { { at: number, finish: number, time: number } } = {}
+	local index = 1
+	while true do
+		local at, finish, captured = string.find(text, "([%d%.]+)%s*=", index)
+		if not at then
+			break
+		end
+		local time = tonumber(captured)
+		if time then
+			table.insert(marks, { at = at, finish = finish, time = time })
+		end
+		index = finish + 1
+	end
+
+	local out: { { time: number, value: string } } = {}
+	for position, mark in marks do
+		local stop = if marks[position + 1] then marks[position + 1].at - 1 else #text
+		local value = string.match(string.sub(text, mark.finish + 1, stop), "^%s*(.-)%s*$") or ""
+		table.insert(out, { time = mark.time, value = value })
+	end
+	return out
+end
+
+
 --[[
 	Parses a serialized string back into a Roblox value, given the target type
 	from the API dump. Returns ok=false with a reason the agent can act on
@@ -194,9 +295,48 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		return true, text, nil
 	end
 
-	if valueType == "string" or valueType == "Content" or valueType == "ProtectedString" then
+	if valueType == "string" or valueType == "ProtectedString" then
 		return true, tostring(text), nil
 	end
+
+	--[[
+		Asset references come in two shapes with almost the same name.
+
+		`ContentId` is the old one and is still just a string: `MeshPart.MeshId`,
+		`Decal.Texture`, `SurfaceAppearance.ColorMap`. It had no branch here at
+		all, so every one of them failed with `no conversion known for type
+		"ContentId"` -- which is how a SurfaceAppearance could be created but
+		never given a texture.
+
+		`Content` is the new datatype and is NOT a string. Assigning
+		`"rbxassetid://123"` to `AudioPlayer.AudioContent` or
+		`ImageLabel.ImageContent` throws; it wants `Content.fromUri`. This branch
+		used to lump it in with `string` above, so those writes reported a parse
+		success and then failed at assignment with a message about a type the
+		caller never mentioned.
+
+		An empty string means "nothing", the same as it does for an instance
+		reference: `Content.none` is the engine's own name for that.
+	]]
+	if valueType == "ContentId" then
+		return true, tostring(text), nil
+	end
+	if valueType == "Content" then
+		if typeof(text) == "Content" then
+			return true, text, nil
+		end
+		local uri = tostring(text)
+		if uri == "" then
+			return true, Content.none, nil
+		end
+		local okContent, content = pcall(function()
+			return Content.fromUri(uri)
+		end)
+		if okContent then
+			return true, content, nil
+		end
+		return false, nil, string.format('"%s" is not a content URI', uri)
+	end
 	if valueType == "bool" then
 		if kind == "boolean" then
 			return true, text, nil
@@ -300,16 +440,232 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		end
 		return false, nil, 'expected "pos x, y, z" or "pos x, y, z | rot rx, ry, rz"'
 	end
+	--[[
+		NumberRange, which the shared tokenizer cannot see.
+
+		`Serialize.value` writes one as "1..3", but `scanTokens` splits on
+		commas, whitespace and brackets -- never on "..", so "1..3" arrives as a
+		single token, `tonumber` returns nil, and the parse failed with `expected
+		"min..max"` while being handed exactly that. A value this module printed
+		could not be fed back to it, which is the one promise the whole file
+		makes. Caught in QA on ParticleEmitter.Lifetime.
+
+		Parsed here directly. A single number is accepted too, because
+		`NumberRange.new(2)` is a real range and people write it that way.
+	]]
+	if valueType == "ColorSequence" then
+		if kind ~= "string" then
+			return false, nil, "expected text like \"0=1, 0, 0 1=0, 0, 1\""
+		end
+		local points = splitKeypoints(text)
+		if #points == 0 then
+			-- A bare colour: a sequence that is that colour the whole way.
+			local okColour, colour = Serialize.parse(text, "Color3")
+			if okColour and typeof(colour) == "Color3" then
+				return true, ColorSequence.new(colour :: Color3), nil
+			end
+			return false, nil, "expected \"0=1, 0, 0 1=0, 0, 1\", or one colour for a solid sequence"
+		end
+
+		local keypoints: { ColorSequenceKeypoint } = {}
+		for _, point in points do
+			local okColour, colour = Serialize.parse(point.value, "Color3")
+			if not okColour or typeof(colour) ~= "Color3" then
+				return false, nil, string.format("keypoint at %s is not a colour: %q", tostring(point.time), point.value)
+			end
+			table.insert(keypoints, ColorSequenceKeypoint.new(point.time, colour :: Color3))
+		end
+		-- Roblox requires the first keypoint at 0 and the last at 1, in order, and
+		-- throws an unhelpful error otherwise.
+		table.sort(keypoints, function(a, b)
+			return a.Time < b.Time
+		end)
+		if keypoints[1].Time ~= 0 or keypoints[#keypoints].Time ~= 1 then
+			return false,
+				nil,
+				"a ColorSequence must start at time 0 and end at time 1"
+		end
+		local okBuild, built = pcall(ColorSequence.new, keypoints)
+		if not okBuild then
+			return false, nil, tostring(built)
+		end
+		return true, built, nil
+	end
+
+	if valueType == "NumberSequence" then
+		if kind == "number" then
+			return true, NumberSequence.new(text), nil
+		end
+		if kind ~= "string" then
+			return false, nil, "expected text like \"0=0 1=1\""
+		end
+		local points = splitKeypoints(text)
+		if #points == 0 then
+			local single = tonumber(text)
+			if single then
+				return true, NumberSequence.new(single), nil
+			end
+			return false, nil, "expected \"0=0 1=1\", or one number for a flat sequence"
+		end
+
+		local keypoints: { NumberSequenceKeypoint } = {}
+		for _, point in points do
+			local value = tonumber(point.value)
+			if not value then
+				return false, nil, string.format("keypoint at %s is not a number: %q", tostring(point.time), point.value)
+			end
+			table.insert(keypoints, NumberSequenceKeypoint.new(point.time, value))
+		end
+		table.sort(keypoints, function(a, b)
+			return a.Time < b.Time
+		end)
+		if keypoints[1].Time ~= 0 or keypoints[#keypoints].Time ~= 1 then
+			return false, nil, "a NumberSequence must start at time 0 and end at time 1"
+		end
+		local okBuild, built = pcall(NumberSequence.new, keypoints)
+		if not okBuild then
+			return false, nil, tostring(built)
+		end
+		return true, built, nil
+	end
+
+	--[[
+		Rect, which `Serialize.value` writes and `parse` did not read.
+
+		The last of the write-but-cannot-read set, after NumberRange and the two
+		sequences. Offered in the attribute type list too, so `rect` attributes
+		were advertised and refused in the same breath. Four numbers, in the
+		order the writer emits them: min X, min Y, max X, max Y.
+	]]
+	if valueType == "Rect" then
+		if #numbers < 4 then
+			return false, nil, 'expected "minX, minY, maxX, maxY"'
+		end
+		return true, Rect.new(numbers[1], numbers[2], numbers[3], numbers[4]), nil
+	end
+
 	if valueType == "NumberRange" then
-		if #numbers < 2 then
-			return false, nil, 'expected "min..max"'
+		if kind == "string" then
+			local low, high = string.match(text, "^%s*(-?[%d%.]+)%s*%.%.%s*(-?[%d%.]+)%s*$")
+			if low and high and tonumber(low) and tonumber(high) then
+				return true, NumberRange.new(tonumber(low) :: number, tonumber(high) :: number), nil
+			end
+		end
+		if #numbers >= 2 then
+			return true, NumberRange.new(numbers[1], numbers[2]), nil
+		end
+		if #numbers == 1 then
+			return true, NumberRange.new(numbers[1]), nil
 		end
-		return true, NumberRange.new(numbers[1], numbers[2]), nil
+		return false, nil, 'expected "min..max", e.g. "1..3"'
 	end
 
-	-- Enum values arrive as "Enum.Material.Plastic" or bare "Plastic".
-	local enumType = (Enum :: any)[valueType]
-	if enumType then
+	--[[
+		PhysicalProperties, which is neither a vector nor an enum.
+
+		Written as the Properties panel writes it: density, friction,
+		elasticity, and optionally the two weights. Handled here because it is a
+		real property on every BasePart and the fall-through below cannot take
+		it -- see the note on the Enum lookup.
+	]]
+	if valueType == "PhysicalProperties" then
+		if #numbers >= 5 then
+			return true, PhysicalProperties.new(numbers[1], numbers[2], numbers[3], numbers[4], numbers[5]), nil
+		end
+		if #numbers >= 3 then
+			return true, PhysicalProperties.new(numbers[1], numbers[2], numbers[3]), nil
+		end
+		return false, nil, 'expected "density, friction, elasticity" and optionally two weights'
+	end
+
+	--[[
+		Fonts, which look like an enum and are not one.
+
+		`TextLabel.FontFace` holds a `Font`, while `Enum.Font` is a separate
+		thing that happens to share its names. The fall-through below found
+		`Enum.Font` first and returned an EnumItem, so every attempt to set
+		FontFace failed with "Font expected, got EnumItem" -- measured while
+		building an ordinary shop panel, where it stopped the whole batch. This
+		has to come first for that reason.
+
+		Three spellings are accepted, because all three are what someone
+		actually has to hand: the familiar enum name ("GothamBold"), a family
+		asset id, and a family with a weight and style after it -- the form this
+		module writes when it reads a Font back.
+	]]
+	if valueType == "Font" then
+		local written = tostring(text)
+		local pieces: { string } = {}
+		for piece in string.gmatch(written, "[^|]+") do
+			table.insert(pieces, (string.gsub(piece, "^%s*(.-)%s*$", "%1")))
+		end
+
+		local family = if #pieces > 0 then pieces[1] else written
+		local weight = Enum.FontWeight.Regular
+		local style = Enum.FontStyle.Normal
+		if #pieces >= 2 then
+			local okWeight, found = pcall(function()
+				return (Enum.FontWeight :: any)[pieces[2]]
+			end)
+			if okWeight and found then
+				weight = found
+			end
+		end
+		if #pieces >= 3 and pieces[3] == "Italic" then
+			style = Enum.FontStyle.Italic
+		end
+
+		-- The enum spelling first: "GothamBold" carries its weight in the name,
+		-- and `fromEnum` knows the pairing better than any table here would.
+		if #pieces == 1 then
+			local name = family:match("([^%.]+)$") or family
+			for _, item in Enum.Font:GetEnumItems() do
+				if item.Name == name and item ~= Enum.Font.Unknown then
+					local okEnumFont, font = pcall(function()
+						return Font.fromEnum(item)
+					end)
+					if okEnumFont then
+						return true, font, nil
+					end
+				end
+			end
+		end
+
+		if string.sub(family, 1, 9) == "rbxasset:" or string.sub(family, 1, 12) == "rbxassetid:" then
+			return true, Font.new(family, weight, style), nil
+		end
+
+		local okName, font = pcall(function()
+			return Font.fromName(family, weight, style)
+		end)
+		if okName and font then
+			return true, font, nil
+		end
+
+		return false,
+			nil,
+			string.format(
+				'"%s" is not a font. Use an Enum.Font name like "GothamBold", a family '
+					.. 'name like "Gotham", or "family | Weight | Style".',
+				written
+			)
+	end
+
+	--[[
+		Enum values arrive as "Enum.Material.Plastic" or bare "Plastic".
+
+		Indexed inside a pcall, because `Enum` throws on an unknown name rather
+		than returning nil. Every value type this function does not handle ends
+		up here, so an unguarded lookup turned "no conversion known for type X"
+		-- a clear message naming the property -- into a raw HANDLER_ERROR
+		reading "PhysicalProperties is not a valid member of Enum", which names
+		the wrong thing entirely. Measured on a `modify` setting
+		CustomPhysicalProperties.
+	]]
+	local okEnum, enumType = pcall(function()
+		return (Enum :: any)[valueType]
+	end)
+	if okEnum and enumType then
 		local name = tostring(text):match("([^%.]+)$") or tostring(text)
 		for _, item in enumType:GetEnumItems() do
 			if item.Name == name then
@@ -321,6 +677,82 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 			string.format('"%s" is not a member of Enum.%s', tostring(text), valueType)
 	end
 
+	--[[
+		Instance references, written as the path of the thing pointed at.
+
+		Motor6D.Part0, WeldConstraint.Part1, ObjectValue.Value, Beam.Attachment0,
+		Model.PrimaryPart, BillboardGui.Adornee -- every one of these holds
+		another instance, and none of them could be set at all before this. That
+		is not a corner: a Motor6D with no Part0 joins nothing, so building a rig
+		or welding a gun to a hand fell out of `create` entirely and had to go
+		through `execute_luau`. Measured on a six-joint R6 rig, which failed with
+		"no conversion known for type BasePart".
+
+		Written the same way every reference is READ -- `Serialize.value` returns
+		`GetFullName()` for an instance -- so a value read here can be written
+		straight back, which is the promise the rest of this module makes.
+
+		The class is checked against the property's own type, because the engine
+		accepts the assignment and then quietly does nothing useful with a Part0
+		pointing at a Folder. An empty string clears the reference, which is the
+		only way to say "nothing" in a field that otherwise takes a path.
+	]]
+	if kind == "string" then
+		local wanted = tostring(text)
+		if wanted == "" then
+			return true, nil, nil
+		end
+		local okPath, resolved = pcall(Paths.resolve, wanted)
+		if okPath and typeof(resolved) == "Instance" then
+			local instance = resolved :: Instance
+			if instance:IsA(valueType) then
+				return true, instance, nil
+			end
+			return false,
+				nil,
+				string.format(
+					"%s is a %s, but this property holds a %s",
+					wanted,
+					instance.ClassName,
+					valueType
+				)
+		end
+
+		--[[
+			The path did not resolve, and saying so is the whole point.
+
+			This used to fall through to the "no conversion known for type X"
+			line below, which blames the TYPE for what is really a missing
+			instance: setting `HingeConstraint.Attachment0` to a path that did
+			not exist yet reported `no conversion known for type "Attachment"`,
+			sending the reader to look for a serializer that was never the
+			problem. Measured while building a hinge in one `create` call.
+		]]
+		--[[
+			Only text that actually looks like a path is reported as a missing
+			instance -- and only that text is worth retrying later.
+
+			Without this check every unparseable string took this branch: a
+			ColorSequence written as "0=1, 0, 0" came back as `nothing at
+			"0=1, 0, 0"`, which names the wrong problem entirely and sends the
+			create handler off to retry something no amount of waiting will fix.
+
+			The test is whether the first segment names something real at the
+			root of the data model. "Workspace.Nowhere" passes it -- Workspace
+			exists, the rest does not, which is exactly the retryable case --
+			while "0.5" and "0=1, 0, 0" do not.
+		]]
+		local head = string.match(wanted, "^([%a_][%w_]*)%.") or string.match(wanted, "^([%a_][%w_]*)$")
+		local looksLikePath = head ~= nil and pcall(function()
+			return game:FindFirstChild(head :: string) ~= nil or game:GetService(head :: any) ~= nil
+		end)
+		if looksLikePath then
+			return false,
+				nil,
+				string.format('%snothing at "%s" (this property holds a %s)', UNRESOLVED_PREFIX, wanted, valueType)
+		end
+	end
+
 	return false, nil, string.format('no conversion known for type "%s"', valueType)
 end