@el4cteo/rbx-studio-mcp 0.8.4 → 0.8.6

package/plugin/src/handlers/Sync.luau

@@ -0,0 +1,968 @@
+--!strict
+--[[
+	The Studio half of `sync`: scripts mirrored to files on disk, and instance
+	trees exported to build files and rebuilt from them.
+
+	Everything that decides WHAT to sync lives in the server, which can see the
+	disk. This side answers four questions and carries out one kind of order:
+
+	  scan     which scripts exist, where, and at what revision
+	  read     their source
+	  changes  what changed since the last time anyone asked (for `watch`)
+	  export   an instance tree as the same spec `create` takes
+
+	  apply    write, create, delete and move scripts, each item checked against
+	           the revision the server last saw, so nothing the user changed in
+	           the meantime is overwritten
+	  build    replace an instance tree from a spec, keeping its scripts
+
+	Revisions are `ScriptEdit.fingerprint`, the same `rev` script_read hands out,
+	so a sync and an agent editing through the script tools agree on what
+	"unchanged" means.
+]]
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local HttpService = game:GetService("HttpService")
+local CollectionService = game:GetService("CollectionService")
+
+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 Serialize = require(script.Parent.Parent.Serialize)
+local Undo = require(script.Parent.Parent.Undo)
+local Instances = require(script.Parent.Instances)
+
+local Sync = {}
+
+-- Past this, a place is better synced a service at a time: every scan reads
+-- and fingerprints every script's buffer on Studio's main thread.
+local MAX_SCRIPTS = 5_000
+
+-- Where scripts are looked for by default. `Players` is left out on purpose:
+-- in edit it is empty, and in a playtest its scripts are copies the engine
+-- made from StarterPlayer, which would sync back as duplicates.
+local DEFAULT_ROOTS = {
+	"Workspace",
+	"ReplicatedFirst",
+	"ReplicatedStorage",
+	"ServerScriptService",
+	"ServerStorage",
+	"StarterGui",
+	"StarterPack",
+	"StarterPlayer",
+	"SoundService",
+	"Lighting",
+	"Teams",
+	"Chat",
+	"TextChatService",
+	"TestService",
+}
+
+-- The panel's own `copy` output. A log, not code, and it is rewritten on every
+-- `copy`, so syncing it would only ever produce noise on disk.
+local IGNORED_NAMES = {
+	["rbx-studio log"] = true,
+}
+
+-- Same limit as `script_create`: past it `.Source` refuses and only the editor
+-- path takes the text.
+local SOURCE_PROPERTY_LIMIT = 200_000
+
+export type Logger = (level: string, message: string, detail: string?) -> ()
+local log: Logger = function() end
+
+--[[
+	Hands in the panel's logger. A handler requiring the console would pull the
+	whole widget into every test harness that loads this file.
+]]
+function Sync.setup(logger: Logger)
+	log = logger
+end
+
+local function isScript(instance: Instance): boolean
+	return instance:IsA("LuaSourceContainer")
+end
+
+local function rootsOf(params: { [string]: any }): { Instance }
+	local wanted = params.roots
+	local roots: { Instance } = {}
+	if typeof(wanted) == "table" and #wanted > 0 then
+		for _, path in wanted do
+			table.insert(roots, Paths.resolve(tostring(path)))
+		end
+		return roots
+	end
+	for _, name in DEFAULT_ROOTS do
+		local service = game:FindFirstChild(name)
+		if service ~= nil then
+			table.insert(roots, service)
+		end
+	end
+	return roots
+end
+
+--[[
+	Whether Studio's own Script Sync already binds this script to a file.
+
+	Two syncs writing the same script is a race neither can see, so such scripts
+	are reported and left alone. Silent when the service is unavailable.
+]]
+local function fileSynced(target: Instance): boolean
+	local service = game:FindService("InstanceFileSyncService")
+	if service == nil then
+		return false
+	end
+	local ok, status = pcall(function()
+		return (service :: any):GetStatus(target)
+	end)
+	if not ok or status == nil then
+		return false
+	end
+	local name = tostring(status)
+	return not (string.find(name, "NotSynced") or string.find(name, "Unknown") or name == "nil")
+end
+
+
+-- Scripts under the roots, in a fixed order (see `stableOrder` in Discover).
+local function collect(roots: { Instance }): { LuaSourceContainer }
+	local found: { LuaSourceContainer } = {}
+	local seen: { [Instance]: boolean } = {}
+	local function consider(instance: Instance)
+		if seen[instance] or not isScript(instance) or IGNORED_NAMES[instance.Name] then
+			return
+		end
+		if Scope.isNoisy(instance) then
+			return
+		end
+		seen[instance] = true
+		table.insert(found, instance :: LuaSourceContainer)
+	end
+	for _, root in roots do
+		consider(root)
+		for _, descendant in root:GetDescendants() do
+			consider(descendant)
+		end
+	end
+	if #found > MAX_SCRIPTS then
+		Dispatch.fail(
+			"TOO_BROAD",
+			string.format("%d scripts, over the %d a sync handles at once.", #found, MAX_SCRIPTS),
+			"Pass `roots` to sync a few services or folders at a time."
+		)
+	end
+	local keys: { [Instance]: string } = {}
+	for _, target in found do
+		local ok, id = pcall(function()
+			return target:GetDebugId()
+		end)
+		keys[target] = target:GetFullName() .. "\0" .. (if ok then id else "")
+	end
+	table.sort(found, function(a: Instance, b: Instance): boolean
+		return keys[a] < keys[b]
+	end)
+	return found
+end
+
+--[[
+	Every script under the roots: where it is, what it is, and -- unless the
+	caller only wants the shape -- its revision.
+
+	The server lays files out by the chain of instances above each script, and
+	needs to know which links are scripts themselves (a script with scripts
+	inside becomes a folder with an `init` file). That chain is shared by every
+	script in a folder, so it comes back once, as `nodes`: each instance on any
+	chain, with its parent's position in the same list (0 for the DataModel)
+	and its sibling ordinal when its name is not unique. Scripts point into it.
+]]
+function Sync.scan(params: { [string]: any }): { [string]: any }
+	local withRevisions = params.revisions ~= false
+	local memo: Paths.NameIndex = {}
+	local nodes: { { [string]: any } } = {}
+	local indexOf: { [Instance]: number } = {}
+
+	local function nodeOf(instance: Instance): number
+		if instance == game then
+			return 0
+		end
+		local known = indexOf[instance]
+		if known ~= nil then
+			return known
+		end
+		local parent = nodeOf(instance.Parent :: Instance)
+		table.insert(nodes, {
+			path = Paths.of(instance, memo),
+			name = instance.Name,
+			className = instance.ClassName,
+			parent = parent,
+			ordinal = Paths.ordinal(instance, memo),
+		})
+		indexOf[instance] = #nodes
+		return #nodes
+	end
+
+	local items: { { [string]: any } } = {}
+	for _, target in collect(rootsOf(params)) do
+		table.insert(items, {
+			node = nodeOf(target),
+			revision = if withRevisions then ScriptEdit.revisionOf(target) else nil,
+			fileSynced = if fileSynced(target) then true else nil,
+		})
+	end
+	local roots: { string } = {}
+	for _, root in rootsOf(params) do
+		table.insert(roots, Paths.of(root, memo))
+	end
+	return { nodes = nodes, items = items, roots = roots }
+end
+
+--[[
+	Every synced script's path, one string. `watch` compares it every few
+	seconds to notice what no event reports -- a folder renamed moves every
+	script inside it -- without reading or fingerprinting a single script.
+]]
+function Sync.shape(params: { [string]: any }): { [string]: any }
+	local memo: Paths.NameIndex = {}
+	local paths: { string } = {}
+	for _, target in collect(rootsOf(params)) do
+		table.insert(paths, Paths.of(target, memo))
+	end
+	return { shape = table.concat(paths, "\n") }
+end
+
+-- Declared ahead of `revisions`, which needs it.
+local scriptAt: (path: string) -> LuaSourceContainer
+
+--[[
+	Revisions only, for `watch` to tell a real Studio edit from the echo of a
+	write it made itself -- without shipping any source back.
+]]
+function Sync.revisions(params: { [string]: any }): { [string]: any }
+	local items: { { [string]: any } } = {}
+	for _, path in (if typeof(params.paths) == "table" then params.paths else {}) :: { any } do
+		local ok, revision = pcall(function()
+			return ScriptEdit.revisionOf(scriptAt(tostring(path)))
+		end)
+		table.insert(items, if ok then { path = path, revision = revision } else { path = path, missing = true })
+	end
+	return { items = items }
+end
+
+-- Resolves a path and insists it is a script, or explains why not.
+function scriptAt(path: string): LuaSourceContainer
+	local instance = Paths.resolve(path)
+	if not isScript(instance) then
+		Dispatch.fail("NOT_A_SCRIPT", string.format("%s is a %s, not a script.", path, instance.ClassName))
+	end
+	return instance :: LuaSourceContainer
+end
+
+local function reasonOf(err: any): (string, string)
+	if typeof(err) == "table" then
+		return tostring(err.code or "FAILED"), tostring(err.message)
+	end
+	return "FAILED", tostring(err)
+end
+
+-- Source and revision of each path. Per path, so one missing script does not
+-- sink a read of three hundred.
+function Sync.read(params: { [string]: any }): { [string]: any }
+	local paths = params.paths
+	if typeof(paths) ~= "table" then
+		Dispatch.fail("BAD_PARAMS", "sync.read requires `paths`.")
+	end
+	local items: { { [string]: any } } = {}
+	for _, path in paths do
+		local ok, result = pcall(function()
+			local target = scriptAt(tostring(path))
+			local source = ScriptEdit.read(target)
+			return { path = path, source = source, revision = ScriptEdit.revisionOf(target, source), className = target.ClassName }
+		end)
+		if ok then
+			table.insert(items, result)
+		else
+			local code, message = reasonOf(result)
+			table.insert(items, { path = path, code = code, message = message })
+		end
+	end
+	return { items = items }
+end
+
+--[[
+	Walks a chain of names from the DataModel, creating what is missing.
+
+	By name rather than through `Paths.resolve`: the chain comes from a folder
+	on disk, which knows names and nothing about sibling indexes. Missing links
+	become the class the chain asks for -- a Folder, unless the file says the
+	link is a script -- and a missing SERVICE is refused, since that is a
+	misspelled top-level folder, not something to invent.
+]]
+local function ensureChain(start: any, chain: { { [string]: any } }, create: boolean): Instance?
+	local current: Instance = if typeof(start) == "string" and start ~= "" then Paths.resolve(start) else game
+	for index, link in chain do
+		local name = tostring(link.name)
+		local child = current:FindFirstChild(name)
+		if child == nil then
+			if current == game then
+				local ok, service = pcall(function()
+					return game:GetService(name)
+				end)
+				if ok and service ~= nil then
+					child = service
+				else
+					Dispatch.fail(
+						"UNKNOWN_SERVICE",
+						string.format('"%s" is not a service.', name),
+						"Top-level folders in the sync folder are service names, e.g. ServerScriptService."
+					)
+				end
+			elseif not create then
+				return nil
+			else
+				local className = if typeof(link.className) == "string" then link.className else "Folder"
+				local made = Instance.new(className)
+				made.Name = name
+				made.Parent = current
+				child = made
+			end
+		end
+		current = child :: Instance
+	end
+	return current
+end
+
+-- Refuses unless `target` is still at the revision the server last saw.
+local function assertRevision(target: LuaSourceContainer, revision: any)
+	if typeof(revision) ~= "string" then
+		return
+	end
+	local live = ScriptEdit.revisionOf(target)
+	if live ~= revision then
+		Dispatch.fail("STALE_SCRIPT", string.format("changed in Studio since the last sync (now %s)", live))
+	end
+end
+
+--[[
+	Carries out one batch of the server's decisions.
+
+	Structural changes -- creates, deletes, moves -- share one undo step, "MCP
+	sync", so a sync that put files where they should not be is one Ctrl+Z.
+	Source writes go through the script editor after that, with its own
+	per-script undo, exactly like `script_edit`.
+
+	Every item is checked against the revision the server based its decision
+	on, and fails alone: a sync is many independent files, and one the user
+	touched a second ago must not hold the other forty back. Each item reports
+	what happened, and the new revision where there is one.
+]]
+function Sync.apply(params: { [string]: any }): { [string]: any }
+	local writes = if typeof(params.writes) == "table" then params.writes else {}
+	local creates = if typeof(params.creates) == "table" then params.creates else {}
+	local deletes = if typeof(params.deletes) == "table" then params.deletes else {}
+	local moves = if typeof(params.moves) == "table" then params.moves else {}
+
+	local results = { writes = {}, creates = {}, deletes = {}, moves = {} }
+	type Late = { target: LuaSourceContainer, source: string, result: { [string]: any } }
+	local late: { Late } = {}
+
+	local structural = #creates + #deletes + #moves > 0
+	local recorded = false
+	if structural then
+		local _, didRecord = Undo.recordPartial("StudioMCP.Sync", "MCP sync", function()
+			for _, item in creates do
+				local ok, err = pcall(function()
+					local parent = ensureChain(item.parentPath, item.parents or {}, true) :: Instance
+					local name = tostring(item.name)
+					local existing = parent:FindFirstChild(name)
+					if existing ~= nil and isScript(existing) then
+						Dispatch.fail("EXISTS", string.format("%s already has a script named %s", parent:GetFullName(), name))
+					end
+					local made = Instance.new(item.className) :: LuaSourceContainer
+					made.Name = name
+					local source = if typeof(item.source) == "string" then item.source else ""
+					local result: { [string]: any } = { ok = true }
+					if #source < SOURCE_PROPERTY_LIMIT then
+						(made :: ScriptEdit.SourceContainer).Source = source
+					else
+						table.insert(late, { target = made, source = source, result = result })
+					end
+					made.Parent = parent
+					result.path = Paths.of(made)
+					result.revision = ScriptEdit.revisionOf(made, if #source < SOURCE_PROPERTY_LIMIT then source else "")
+					return result
+				end)
+				if ok then
+					table.insert(results.creates, err)
+				else
+					local code, message = reasonOf(err)
+					table.insert(results.creates, { ok = false, code = code, message = message })
+				end
+			end
+
+			for _, item in deletes do
+				local ok, err = pcall(function()
+					local target = scriptAt(tostring(item.path))
+					assertRevision(target, item.revision)
+					target:Destroy()
+				end)
+				if ok then
+					table.insert(results.deletes, { ok = true, path = item.path })
+				else
+					local code, message = reasonOf(err)
+					table.insert(results.deletes, { ok = false, path = item.path, code = code, message = message })
+				end
+			end
+
+			for _, item in moves do
+				local ok, err = pcall(function()
+					local target = scriptAt(tostring(item.path))
+					assertRevision(target, item.revision)
+					local parent = ensureChain(item.parentPath, item.parents or {}, true) :: Instance
+					target.Name = tostring(item.name)
+					target.Parent = parent
+					return Paths.of(target)
+				end)
+				if ok then
+					table.insert(results.moves, { ok = true, from = item.path, path = err })
+				else
+					local code, message = reasonOf(err)
+					table.insert(results.moves, { ok = false, from = item.path, code = code, message = message })
+				end
+			end
+			return true
+		end)
+		recorded = didRecord
+	end
+
+	-- Sources too long for `.Source`, written now that the scripts exist.
+	for _, entry in late do
+		local ok, err = pcall(function()
+			Undo.exclusive(function()
+				ScriptEdit.write(entry.target, function(current)
+					if current ~= "" then
+						Dispatch.fail("STALE_SCRIPT", "edited before its source could be written; that text was kept")
+					end
+					return entry.source
+				end)
+			end)
+		end)
+		if ok then
+			entry.result.revision = ScriptEdit.revisionOf(entry.target)
+		else
+			local code, message = reasonOf(err)
+			entry.result.ok = false
+			entry.result.code = code
+			entry.result.message = "created, but the source was not written: " .. message
+		end
+	end
+
+	if #writes > 0 then
+		Undo.exclusive(function()
+			for _, item in writes do
+				local ok, err = pcall(function()
+					local target = scriptAt(tostring(item.path))
+					local source = tostring(item.source)
+					-- Checked inside the editor's callback: the text the write
+					-- replaces is the text the check saw.
+					ScriptEdit.write(target, function(current)
+						if typeof(item.revision) == "string" and ScriptEdit.revisionOf(target, current) ~= item.revision then
+							Dispatch.fail("STALE_SCRIPT", "changed in Studio since the last sync; that text was kept")
+						end
+						return source
+					end)
+					return ScriptEdit.revisionOf(target)
+				end)
+				if ok then
+					table.insert(results.writes, { ok = true, path = item.path, revision = err })
+				else
+					local code, message = reasonOf(err)
+					table.insert(results.writes, { ok = false, path = item.path, code = code, message = message })
+				end
+			end
+			return true
+		end)
+	end
+
+	local counts = {}
+	for _, kind in { "writes", "creates", "deletes", "moves" } do
+		local done = 0
+		for _, result in (results :: any)[kind] do
+			if result.ok then
+				done += 1
+			end
+		end
+		if done > 0 then
+			table.insert(counts, string.format("%d %s", done, kind))
+		end
+	end
+	if #counts > 0 then
+		log("ok", "sync from files: " .. table.concat(counts, ", "), if recorded then "one undo step" else nil)
+	end
+
+	return {
+		writes = results.writes,
+		creates = results.creates,
+		deletes = results.deletes,
+		moves = results.moves,
+		undoStep = if recorded then "MCP sync" else nil,
+	}
+end
+
+-- Change tracking, for `watch` ----------------------------------------------
+
+--[[
+	What changed since the server last asked, so `watch` does not fingerprint
+	every script in the place twice a second.
+
+	Edits in the script editor arrive through `TextDocumentDidChange`, and every
+	other write to `Source` through the property signal. Scripts appearing,
+	disappearing or being renamed mark the whole shape as changed, and the
+	server rescans. Renaming a FOLDER changes script paths with no event on the
+	scripts at all, which is why the server also rescans the shape on a slow
+	timer rather than trusting this alone.
+
+	Only runs while someone is asking: tracking starts on the first `changes`
+	call and stops by itself once nobody has asked for a minute, so a watch
+	that ended with its process leaves nothing connected behind.
+]]
+type Tracker = {
+	token: string,
+	dirty: { [Instance]: boolean },
+	structural: boolean,
+	connections: { RBXScriptConnection },
+	watched: { [Instance]: boolean },
+	lastPolled: number,
+}
+local tracker: Tracker? = nil
+local IDLE_STOP = 60
+
+local function stopTracking()
+	local current = tracker
+	if current == nil then
+		return
+	end
+	for _, connection in current.connections do
+		connection:Disconnect()
+	end
+	tracker = nil
+end
+
+local function watchScript(current: Tracker, instance: Instance)
+	if current.watched[instance] or not isScript(instance) then
+		return
+	end
+	current.watched[instance] = true
+	table.insert(current.connections, instance:GetPropertyChangedSignal("Source"):Connect(function()
+		current.dirty[instance] = true
+	end))
+	table.insert(current.connections, instance:GetPropertyChangedSignal("Name"):Connect(function()
+		current.structural = true
+	end))
+end
+
+local function startTracking(): Tracker
+	local current: Tracker = {
+		token = HttpService:GenerateGUID(false),
+		dirty = setmetatable({}, { __mode = "k" }) :: any,
+		structural = false,
+		connections = {},
+		watched = setmetatable({}, { __mode = "k" }) :: any,
+		lastPolled = os.clock(),
+	}
+	for _, root in rootsOf({}) do
+		for _, descendant in root:GetDescendants() do
+			watchScript(current, descendant)
+		end
+	end
+	table.insert(current.connections, game.DescendantAdded:Connect(function(instance)
+		if isScript(instance) then
+			current.structural = true
+			watchScript(current, instance)
+		end
+	end))
+	table.insert(current.connections, game.DescendantRemoving:Connect(function(instance)
+		if isScript(instance) then
+			current.structural = true
+		end
+	end))
+	pcall(function()
+		table.insert(current.connections, ScriptEditorService.TextDocumentDidChange:Connect(function(document)
+			local ok, target = pcall(function()
+				return document:GetScript()
+			end)
+			if ok and target ~= nil then
+				current.dirty[target] = true
+			end
+		end))
+	end)
+	tracker = current
+
+	task.spawn(function()
+		while tracker == current do
+			task.wait(IDLE_STOP / 2)
+			if tracker == current and os.clock() - current.lastPolled > IDLE_STOP then
+				stopTracking()
+			end
+		end
+	end)
+	return current
+end
+
+--[[
+	Returns what changed since the previous call, and forgets it.
+
+	`token` names the tracking session. A token the server does not recognise
+	-- the first call, or the plugin reloaded in between and lost everything it
+	had noted -- comes back with `reset`, meaning "assume anything changed".
+]]
+function Sync.changes(params: { [string]: any }): { [string]: any }
+	local current = tracker
+	if current == nil or params.token ~= current.token then
+		current = current or startTracking()
+		current.lastPolled = os.clock()
+		current.dirty = setmetatable({}, { __mode = "k" }) :: any
+		current.structural = false
+		return { token = current.token, reset = true, dirty = {}, structural = true }
+	end
+	current.lastPolled = os.clock()
+
+	local dirty: { string } = {}
+	local memo: Paths.NameIndex = {}
+	for instance in current.dirty do
+		if instance.Parent ~= nil and not Scope.isNoisy(instance) then
+			table.insert(dirty, Paths.of(instance, memo))
+		end
+	end
+	local structural = current.structural
+	current.dirty = setmetatable({}, { __mode = "k" }) :: any
+	current.structural = false
+	return { token = current.token, reset = false, dirty = dirty, structural = structural }
+end
+
+function Sync.stop(_params: { [string]: any }): { [string]: any }
+	stopTracking()
+	return { stopped = true }
+end
+
+-- A line in the panel for work the server did that Studio cannot see, like
+-- files written to disk. Quiet: logging the call as well would say it twice.
+function Sync.log(params: { [string]: any }): { [string]: any }
+	local lines = params.lines
+	if typeof(lines) == "table" then
+		for _, line in lines do
+			if typeof(line) == "table" and typeof(line.message) == "string" then
+				log(
+					if typeof(line.level) == "string" then line.level else "dim",
+					line.message,
+					if typeof(line.detail) == "string" then line.detail else nil
+				)
+			end
+		end
+	end
+	return { logged = true }
+end
+
+-- Build files ---------------------------------------------------------------
+
+-- Attribute types `create` can write back; the list its schema accepts.
+local ATTRIBUTE_TYPES: { [string]: boolean } = {
+	BrickColor = true,
+	CFrame = true,
+	Color3 = true,
+	ColorSequence = true,
+	Font = true,
+	NumberRange = true,
+	NumberSequence = true,
+	Rect = true,
+	UDim = true,
+	UDim2 = true,
+	Vector2 = true,
+	Vector3 = true,
+}
+
+-- Classes in a subtree other than scripts, so the server can say which of their
+-- properties are worth exporting.
+function Sync.classes(params: { [string]: any }): { [string]: any }
+	local root = Paths.resolve(tostring(params.path))
+	if isScript(root) then
+		Dispatch.fail("IS_A_SCRIPT", "Scripts sync as files; export the instance tree that holds them.")
+	end
+	local seen: { [string]: boolean } = { [root.ClassName] = true }
+	for _, descendant in root:GetDescendants() do
+		if not isScript(descendant) then
+			seen[descendant.ClassName] = true
+		end
+	end
+	local classes: { string } = {}
+	for name in seen do
+		table.insert(classes, name)
+	end
+	table.sort(classes)
+	-- The chain above the root, so the server can place the build file beside
+	-- the synced scripts of the same tree.
+	local chain: { { [string]: any } } = {}
+	local link: Instance? = root
+	while link ~= nil and link ~= game do
+		table.insert(chain, 1, {
+			name = (link :: Instance).Name,
+			className = (link :: Instance).ClassName,
+			path = Paths.of(link :: Instance),
+			ordinal = Paths.ordinal(link :: Instance),
+		})
+		link = (link :: Instance).Parent
+	end
+	return { path = Paths.of(root), classes = classes, chain = chain }
+end
+
+--[[
+	An instance tree as the spec `create` takes: class, name, and every
+	property that differs from a fresh instance of the class.
+
+	Differs, because a build file is read and edited by people and agents:
+	three hundred default values per frame would bury the eight that make it
+	that frame. Each exported value is also parsed back before it is kept, so
+	a build file never contains something the build could not apply --
+	anything that does not survive is listed in `skipped` instead.
+
+	Scripts are not exported. They live in the sync folder as files, and a
+	rebuild carries the existing ones over (see `build`).
+]]
+function Sync.export(params: { [string]: any }): { [string]: any }
+	local root = Paths.resolve(tostring(params.path))
+	local propertyLists = if typeof(params.properties) == "table" then params.properties else {}
+	local defaults: { [string]: Instance | false } = {}
+	local skipped: { string } = {}
+	local scripts = 0
+	local count = 0
+
+	local function defaultOf(className: string): Instance?
+		local cached = defaults[className]
+		if cached == nil then
+			local ok, made = pcall(Instance.new, className)
+			cached = if ok then made else false
+			defaults[className] = cached
+		end
+		return if cached then cached :: Instance else nil
+	end
+
+	local function describe(instance: Instance, depth: number): { [string]: any }?
+		if isScript(instance) then
+			scripts += 1
+			return nil
+		end
+		count += 1
+		local spec: { [string]: any } = { className = instance.ClassName, name = instance.Name }
+		local default = defaultOf(instance.ClassName)
+		local properties: { [string]: any } = {}
+		local any = false
+		for _, entry in (propertyLists[instance.ClassName] or {}) :: { any } do
+			local name = tostring(entry.name)
+			local okRead, value = pcall(function()
+				return (instance :: any)[name]
+			end)
+			if not okRead then
+				continue
+			end
+			if default ~= nil then
+				local okDefault, fallback = pcall(function()
+					return (default :: any)[name]
+				end)
+				if okDefault and fallback == value then
+					continue
+				end
+			end
+			local text = Serialize.value(value)
+			if typeof(text) == "table" or text == nil then
+				table.insert(skipped, string.format("%s.%s", instance:GetFullName(), name))
+				continue
+			end
+			local parsed = Serialize.parse(text, tostring(entry.type))
+			if not parsed then
+				table.insert(skipped, string.format("%s.%s", instance:GetFullName(), name))
+				continue
+			end
+			properties[name] = text
+			any = true
+		end
+		if any then
+			spec.properties = properties
+		end
+
+		local attributes = instance:GetAttributes()
+		if next(attributes) ~= nil then
+			local exported: { [string]: any } = {}
+			local anyAttribute = false
+			for name, value in attributes do
+				local kind = typeof(value)
+				if kind == "string" or kind == "number" or kind == "boolean" then
+					exported[name] = value
+					anyAttribute = true
+				elseif ATTRIBUTE_TYPES[kind] then
+					exported[name] = { type = kind, value = Serialize.value(value) }
+					anyAttribute = true
+				else
+					-- `create` cannot type it, and one unreadable value would
+					-- stop the whole file from building.
+					table.insert(skipped, string.format("%s@%s (%s)", instance:GetFullName(), name, kind))
+				end
+			end
+			if anyAttribute then
+				spec.attributes = exported
+			end
+		end
+
+		local tags = CollectionService:GetTags(instance)
+		if #tags > 0 then
+			table.sort(tags)
+			spec.tags = { add = tags }
+		end
+
+		local children: { { [string]: any } } = {}
+		for _, child in instance:GetChildren() do
+			local described = describe(child, depth + 1)
+			if described ~= nil then
+				table.insert(children, described)
+			end
+		end
+		if #children > 0 then
+			-- By name, then class: a stable file, so an export of an unchanged
+			-- tree is byte-identical and shows up as nothing changed.
+			table.sort(children, function(a, b)
+				if a.name ~= b.name then
+					return a.name < b.name
+				end
+				return a.className < b.className
+			end)
+			spec.children = children
+		end
+		return spec
+	end
+
+	local spec = describe(root, 0)
+	for _, default in defaults do
+		if default then
+			(default :: Instance):Destroy()
+		end
+	end
+	if spec == nil then
+		Dispatch.fail("IS_A_SCRIPT", "Scripts sync as files; export the instance tree that holds them.")
+	end
+	return { path = Paths.of(root), spec = spec, instances = count, scripts = scripts, skipped = skipped }
+end
+
+--[[
+	Replaces an instance tree with a freshly built one, as one undo step.
+
+	The old tree is renamed out of the way, the new one created in its place,
+	and then the scripts are carried across: a build file holds no scripts
+	(they sync as files), so rebuilding a ScreenGui must not delete the
+	LocalScript that drives it. Each script goes back under the same chain of
+	names it sat under, or under the new root when that chain no longer exists
+	-- which is reported, since the script may now be looking in the wrong place.
+]]
+function Sync.build(params: { [string]: any }): { [string]: any }
+	local spec = params.spec
+	if typeof(spec) ~= "table" then
+		Dispatch.fail("BAD_PARAMS", "sync.build requires a `spec`.")
+	end
+	local parent = Paths.resolve(tostring(params.parent))
+	local name = tostring(spec.name or spec.className)
+
+	local carried: { { [string]: any } } = {}
+	local builtPath: string? = nil
+	local _, recorded = Undo.record("StudioMCP.Build", "MCP build", function()
+		-- The tree this file built last time, when its name changed in the file:
+		-- renaming it there must replace that tree, not add a second one.
+		local old: Instance? = nil
+		if typeof(params.replaces) == "string" then
+			local found, previous = pcall(Paths.resolve, params.replaces)
+			if found and previous.Parent == parent then
+				old = previous
+			end
+		end
+		old = old or parent:FindFirstChild(name)
+		if old ~= nil and isScript(old) then
+			Dispatch.fail("IS_A_SCRIPT", string.format("%s is a script; build files hold instance trees.", old:GetFullName()))
+		end
+		if old ~= nil then
+			old.Name = "__mcp_build_old"
+		end
+
+		local top = table.clone(spec) :: any
+		top.parent = Paths.of(parent)
+		local created = Instances.create({ instances = { top } })
+		local fresh = parent:FindFirstChild(name)
+		if fresh == nil then
+			Dispatch.fail("BUILD_FAILED", "The new tree was not created.")
+		end
+		builtPath = (created.items[1] or {}).path
+
+		if old ~= nil then
+			local previous = old :: Instance
+			for _, item in previous:GetDescendants() do
+				local descendant = item :: Instance
+				if not isScript(descendant) then
+					continue
+				end
+				-- Only the outermost scripts: a script's own children move with it.
+				local outer = true
+				local above = descendant.Parent
+				while above ~= nil and above ~= previous do
+					if isScript(above) then
+						outer = false
+						break
+					end
+					above = above.Parent
+				end
+				if not outer then
+					continue
+				end
+
+				local chain: { string } = {}
+				local link = descendant.Parent
+				while link ~= nil and link ~= previous do
+					table.insert(chain, 1, link.Name)
+					link = link.Parent
+				end
+				local destination: Instance = fresh :: Instance
+				local exact = true
+				for _, step in chain do
+					local next = destination:FindFirstChild(step)
+					if next == nil then
+						exact = false
+						break
+					end
+					destination = next
+				end
+				if not exact then
+					destination = fresh :: Instance
+				end
+				descendant.Parent = destination
+				table.insert(carried, { path = Paths.of(descendant), exact = exact })
+			end
+			previous:Destroy()
+		end
+		return true
+	end)
+
+	log("ok", string.format("built %s from a build file", builtPath or name), if recorded then "one undo step" else nil)
+	return { path = builtPath, carried = carried, undoStep = if recorded then "MCP build" else nil }
+end
+
+function Sync.register()
+	Dispatch.registerAll("sync", {
+		scan = Sync.scan,
+		shape = Sync.shape,
+		revisions = Sync.revisions,
+		read = Sync.read,
+		apply = Sync.apply,
+		changes = Sync.changes,
+		stop = Sync.stop,
+		log = Sync.log,
+		classes = Sync.classes,
+		export = Sync.export,
+		build = Sync.build,
+	})
+end
+
+return Sync