dominus-cli 2.0.0 → 2.1.0

package/plugin/src/Explorer.lua

@@ -1,373 +1,530 @@
---[[
-	Explorer module: serialize DataModel tree, read/write scripts, search, manage instances
-]]
-
-local ScriptEditorService = game:GetService("ScriptEditorService")
-
-local Explorer = {}
-
-local SCRIPT_CLASSES = {
-	Script = true,
-	LocalScript = true,
-	ModuleScript = true,
-}
-
-function Explorer.getPath(instance)
-	local parts = {}
-	local current = instance
-	while current and current ~= game do
-		table.insert(parts, 1, current.Name)
-		current = current.Parent
-	end
-	return table.concat(parts, ".")
-end
-
-function Explorer.resolveInstance(path)
-	local parts = string.split(path, ".")
-	local current = game
-	for _, part in parts do
-		local child = current:FindFirstChild(part)
-		if not child then
-			return nil
-		end
-		current = child
-	end
-	return current
-end
-
-function Explorer.getTree(rootPath, maxDepth)
-	maxDepth = maxDepth or 3
-
-	local root
-	if rootPath and rootPath ~= "" then
-		root = Explorer.resolveInstance(rootPath)
-		if not root then
-			return {}
-		end
-	else
-		root = game
-	end
-
-	local function serialize(instance, depth)
-		if depth > maxDepth then
-			return nil
-		end
-
-		local node = {
-			name = instance.Name,
-			className = instance.ClassName,
-			path = Explorer.getPath(instance),
-		}
-
-		local children = {}
-		for _, child in instance:GetChildren() do
-			local childNode = serialize(child, depth + 1)
-			if childNode then
-				table.insert(children, childNode)
-			end
-		end
-
-		if #children > 0 then
-			node.children = children
-		end
-
-		return node
-	end
-
-	if root == game then
-		local topLevel = {}
-		for _, service in game:GetChildren() do
-			local ok, node = pcall(serialize, service, 1)
-			if ok and node then
-				table.insert(topLevel, node)
-			end
-		end
-		return topLevel
-	else
-		local node = serialize(root, 0)
-		return node and { node } or {}
-	end
-end
-
-function Explorer.getScriptSource(path)
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	if not SCRIPT_CLASSES[instance.ClassName] then
-		return { success = false, error = "Not a script: " .. path }
-	end
-
-	local ok, source = pcall(function()
-		return ScriptEditorService:GetEditorSource(instance)
-	end)
-
-	if not ok then
-		-- Fallback to .Source property
-		ok, source = pcall(function()
-			return instance.Source
-		end)
-	end
-
-	if not ok then
-		return { success = false, error = "Could not read source: " .. tostring(source) }
-	end
-
-	local lines = select(2, source:gsub("\n", "\n")) + 1
-
-	return {
-		path = path,
-		className = instance.ClassName,
-		source = source,
-		lineCount = lines,
-	}
-end
-
-function Explorer.setScriptSource(path, newSource)
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	if not SCRIPT_CLASSES[instance.ClassName] then
-		return { success = false, error = "Not a script: " .. path }
-	end
-
-	local ok, err = pcall(function()
-		ScriptEditorService:UpdateSourceAsync(instance, function()
-			return newSource
-		end)
-	end)
-
-	if not ok then
-		return { success = false, error = "Failed to update source: " .. tostring(err) }
-	end
-
-	return { success = true }
-end
-
-function Explorer.insertInstance(className, parentPath, name, properties)
-	local parent = Explorer.resolveInstance(parentPath)
-	if not parent then
-		return { success = false, error = "Parent not found: " .. parentPath }
-	end
-
-	local ok, instance = pcall(function()
-		local obj = Instance.new(className)
-		obj.Name = name
-
-		if properties then
-			for key, value in properties do
-				pcall(function()
-					obj[key] = value
-				end)
-			end
-		end
-
-		obj.Parent = parent
-		return obj
-	end)
-
-	if not ok then
-		return { success = false, error = "Failed to create instance: " .. tostring(instance) }
-	end
-
-	return { success = true, path = Explorer.getPath(instance) }
-end
-
-function Explorer.deleteInstance(path)
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	local ok, err = pcall(function()
-		instance:Destroy()
-	end)
-
-	if not ok then
-		return { success = false, error = "Failed to delete: " .. tostring(err) }
-	end
-
-	return { success = true }
-end
-
-function Explorer.searchScripts(query, maxResults)
-	maxResults = maxResults or 20
-	local results = {}
-	local queryLower = string.lower(query)
-
-	local function searchIn(instance)
-		if #results >= maxResults then
-			return
-		end
-
-		if SCRIPT_CLASSES[instance.ClassName] then
-			local ok, source = pcall(function()
-				return ScriptEditorService:GetEditorSource(instance)
-			end)
-
-			if not ok then
-				ok, source = pcall(function()
-					return instance.Source
-				end)
-			end
-
-			if ok and source then
-				local matches = {}
-				local lineNum = 0
-				for line in source:gmatch("[^\n]+") do
-					lineNum = lineNum + 1
-					if string.find(string.lower(line), queryLower, 1, true) then
-						table.insert(matches, { line = lineNum, text = line })
-						if #matches >= 5 then
-							break
-						end
-					end
-				end
-
-				if #matches > 0 then
-					table.insert(results, {
-						path = Explorer.getPath(instance),
-						className = instance.ClassName,
-						matches = matches,
-					})
-				end
-			end
-		end
-
-		for _, child in instance:GetChildren() do
-			if #results >= maxResults then
-				return
-			end
-			pcall(searchIn, child)
-		end
-	end
-
-	pcall(searchIn, game)
-
-	return { results = results }
-end
-
-function Explorer.findReplaceScripts(spec)
-	local find = spec.find
-	local replace = spec.replace
-	local usePattern = spec.usePattern or false
-	local dryRun = spec.dryRun or false
-
-	if not find or find == "" then
-		return { success = false, error = "Missing 'find' parameter" }
-	end
-
-	local root = game
-	if spec.root and spec.root ~= "" then
-		root = Explorer.resolveInstance(spec.root)
-		if not root then
-			local ok, svc = pcall(function()
-				return game:GetService(spec.root)
-			end)
-			if ok then
-				root = svc
-			else
-				return { success = false, error = "Root not found: " .. spec.root }
-			end
-		end
-	end
-
-	local ChangeHistoryService = game:GetService("ChangeHistoryService")
-	local recording = nil
-	if not dryRun then
-		recording = ChangeHistoryService:TryBeginRecording("Dominus: Find/replace in scripts")
-	end
-
-	local modified = {}
-	local totalMatches = 0
-	local totalFiles = 0
-
-	local function processScript(instance)
-		if not SCRIPT_CLASSES[instance.ClassName] then
-			return
-		end
-
-		local ok, source = pcall(function()
-			return ScriptEditorService:GetEditorSource(instance)
-		end)
-		if not ok then
-			ok, source = pcall(function()
-				return instance.Source
-			end)
-		end
-		if not ok or not source then
-			return
-		end
-
-		local count = 0
-		if usePattern then
-			_, count = source:gsub(find, "")
-		else
-			_, count = source:gsub(find, "", nil)
-			-- plain text: count occurrences with plain find
-			count = 0
-			local startPos = 1
-			while true do
-				local foundPos = source:find(find, startPos, true)
-				if not foundPos then
-					break
-				end
-				count = count + 1
-				startPos = foundPos + #find
-			end
-		end
-
-		if count > 0 then
-			totalMatches = totalMatches + count
-			totalFiles = totalFiles + 1
-
-			local path = Explorer.getPath(instance)
-			table.insert(modified, { path = path, matches = count })
-
-			if not dryRun then
-				local newSource
-				if usePattern then
-					newSource = source:gsub(find, replace)
-				else
-					newSource =
-						source:gsub(find:gsub("([%(%)%.%%%+%-%*%?%[%]%^%$])", "%%%1"), replace:gsub("%%", "%%%%"))
-				end
-
-				pcall(function()
-					ScriptEditorService:UpdateSourceAsync(instance, function()
-						return newSource
-					end)
-				end)
-			end
-		end
-	end
-
-	local function walk(instance)
-		processScript(instance)
-		for _, child in instance:GetChildren() do
-			pcall(walk, child)
-		end
-	end
-
-	pcall(walk, root)
-
-	if recording then
-		if totalFiles > 0 then
-			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
-		else
-			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
-		end
-	end
-
-	return {
-		success = true,
-		modified = modified,
-		totalMatches = totalMatches,
-		totalFiles = totalFiles,
-	}
-end
-
-return Explorer
+--[[
+	Explorer module: serialize DataModel tree, read/write scripts, search, manage instances
+]]
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+
+local Explorer = {}
+
+local SCRIPT_CLASSES = {
+	Script = true,
+	LocalScript = true,
+	ModuleScript = true,
+}
+
+function Explorer.getPath(instance)
+	local parts = {}
+	local current = instance
+	while current and current ~= game do
+		table.insert(parts, 1, current.Name)
+		current = current.Parent
+	end
+	return table.concat(parts, ".")
+end
+
+function Explorer.getRef(instance)
+	return InstanceRegistry.toRef(instance)
+end
+
+function Explorer.resolveTarget(target)
+	return InstanceRegistry.resolve(target)
+end
+
+function Explorer.resolveInstance(path)
+	local parts = string.split(path, ".")
+	local current = game
+	for _, part in parts do
+		local child = current:FindFirstChild(part)
+		if not child then
+			return nil
+		end
+		current = child
+	end
+	return current
+end
+
+function Explorer.getTree(rootPath, maxDepth)
+	maxDepth = maxDepth or 3
+
+	local root
+	if rootPath and rootPath ~= "" then
+		root = Explorer.resolveInstance(rootPath)
+		if not root then
+			return {}
+		end
+	else
+		root = game
+	end
+
+	local function serialize(instance, depth)
+		if depth > maxDepth then
+			return nil
+		end
+
+		local node = {
+			name = instance.Name,
+			className = instance.ClassName,
+			path = Explorer.getPath(instance),
+		}
+
+		local children = {}
+		for _, child in instance:GetChildren() do
+			local childNode = serialize(child, depth + 1)
+			if childNode then
+				table.insert(children, childNode)
+			end
+		end
+
+		if #children > 0 then
+			node.children = children
+		end
+
+		return node
+	end
+
+	if root == game then
+		local topLevel = {}
+		for _, service in game:GetChildren() do
+			local ok, node = pcall(serialize, service, 1)
+			if ok and node then
+				table.insert(topLevel, node)
+			end
+		end
+		return topLevel
+	else
+		local node = serialize(root, 0)
+		return node and { node } or {}
+	end
+end
+
+function Explorer.getScriptSource(path)
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	if not SCRIPT_CLASSES[instance.ClassName] then
+		return { success = false, error = "Not a script: " .. path }
+	end
+
+	local ok, source = pcall(function()
+		return ScriptEditorService:GetEditorSource(instance)
+	end)
+
+	if not ok then
+		-- Fallback to .Source property
+		ok, source = pcall(function()
+			return instance.Source
+		end)
+	end
+
+	if not ok then
+		return { success = false, error = "Could not read source: " .. tostring(source) }
+	end
+
+	local lines = select(2, source:gsub("\n", "\n")) + 1
+
+	return {
+		path = path,
+		className = instance.ClassName,
+		source = source,
+		lineCount = lines,
+	}
+end
+
+function Explorer.setScriptSource(path, newSource)
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	if not SCRIPT_CLASSES[instance.ClassName] then
+		return { success = false, error = "Not a script: " .. path }
+	end
+
+	local ok, err = pcall(function()
+		ScriptEditorService:UpdateSourceAsync(instance, function()
+			return newSource
+		end)
+	end)
+
+	if not ok then
+		return { success = false, error = "Failed to update source: " .. tostring(err) }
+	end
+
+	return { success = true }
+end
+
+function Explorer.insertInstance(className, parentPath, name, properties)
+	local parent = Explorer.resolveInstance(parentPath)
+	if not parent then
+		return { success = false, error = "Parent not found: " .. parentPath }
+	end
+
+	local ok, instance = pcall(function()
+		local obj = Instance.new(className)
+		obj.Name = name
+
+		if properties then
+			for key, value in properties do
+				pcall(function()
+					obj[key] = value
+				end)
+			end
+		end
+
+		obj.Parent = parent
+		return obj
+	end)
+
+	if not ok then
+		return { success = false, error = "Failed to create instance: " .. tostring(instance) }
+	end
+
+	return { success = true, path = Explorer.getPath(instance) }
+end
+
+function Explorer.deleteInstance(path)
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	local ok, err = pcall(function()
+		instance:Destroy()
+	end)
+
+	if not ok then
+		return { success = false, error = "Failed to delete: " .. tostring(err) }
+	end
+
+	return { success = true }
+end
+
+function Explorer.searchScripts(query, maxResults)
+	maxResults = maxResults or 20
+	local results = {}
+	local queryLower = string.lower(query)
+
+	local function searchIn(instance)
+		if #results >= maxResults then
+			return
+		end
+
+		if SCRIPT_CLASSES[instance.ClassName] then
+			local ok, source = pcall(function()
+				return ScriptEditorService:GetEditorSource(instance)
+			end)
+
+			if not ok then
+				ok, source = pcall(function()
+					return instance.Source
+				end)
+			end
+
+			if ok and source then
+				local matches = {}
+				local lineNum = 0
+				for line in source:gmatch("[^\n]+") do
+					lineNum = lineNum + 1
+					if string.find(string.lower(line), queryLower, 1, true) then
+						table.insert(matches, { line = lineNum, text = line })
+						if #matches >= 5 then
+							break
+						end
+					end
+				end
+
+				if #matches > 0 then
+					table.insert(results, {
+						path = Explorer.getPath(instance),
+						className = instance.ClassName,
+						matches = matches,
+					})
+				end
+			end
+		end
+
+		for _, child in instance:GetChildren() do
+			if #results >= maxResults then
+				return
+			end
+			pcall(searchIn, child)
+		end
+	end
+
+	pcall(searchIn, game)
+
+	return { results = results }
+end
+
+function Explorer.findReplaceScripts(spec)
+	local find = spec.find
+	local replace = spec.replace
+	local usePattern = spec.usePattern or false
+	local dryRun = spec.dryRun or false
+
+	if not find or find == "" then
+		return { success = false, error = "Missing 'find' parameter" }
+	end
+
+	local root = game
+	if spec.root and spec.root ~= "" then
+		root = Explorer.resolveInstance(spec.root)
+		if not root then
+			local ok, svc = pcall(function()
+				return game:GetService(spec.root)
+			end)
+			if ok then
+				root = svc
+			else
+				return { success = false, error = "Root not found: " .. spec.root }
+			end
+		end
+	end
+
+	local ChangeHistoryService = game:GetService("ChangeHistoryService")
+	local recording = nil
+	if not dryRun then
+		recording = ChangeHistoryService:TryBeginRecording("Dominus: Find/replace in scripts")
+	end
+
+	local modified = {}
+	local totalMatches = 0
+	local totalFiles = 0
+
+	local function processScript(instance)
+		if not SCRIPT_CLASSES[instance.ClassName] then
+			return
+		end
+
+		local ok, source = pcall(function()
+			return ScriptEditorService:GetEditorSource(instance)
+		end)
+		if not ok then
+			ok, source = pcall(function()
+				return instance.Source
+			end)
+		end
+		if not ok or not source then
+			return
+		end
+
+		local count = 0
+		if usePattern then
+			_, count = source:gsub(find, "")
+		else
+			_, count = source:gsub(find, "", nil)
+			-- plain text: count occurrences with plain find
+			count = 0
+			local startPos = 1
+			while true do
+				local foundPos = source:find(find, startPos, true)
+				if not foundPos then
+					break
+				end
+				count = count + 1
+				startPos = foundPos + #find
+			end
+		end
+
+		if count > 0 then
+			totalMatches = totalMatches + count
+			totalFiles = totalFiles + 1
+
+			local path = Explorer.getPath(instance)
+			table.insert(modified, { path = path, matches = count })
+
+			if not dryRun then
+				local newSource
+				if usePattern then
+					newSource = source:gsub(find, replace)
+				else
+					newSource =
+						source:gsub(find:gsub("([%(%)%.%%%+%-%*%?%[%]%^%$])", "%%%1"), replace:gsub("%%", "%%%%"))
+				end
+
+				pcall(function()
+					ScriptEditorService:UpdateSourceAsync(instance, function()
+						return newSource
+					end)
+				end)
+			end
+		end
+	end
+
+	local function walk(instance)
+		processScript(instance)
+		for _, child in instance:GetChildren() do
+			pcall(walk, child)
+		end
+	end
+
+	pcall(walk, root)
+
+	if recording then
+		if totalFiles > 0 then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+		else
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		end
+	end
+
+	return {
+		success = true,
+		modified = modified,
+		totalMatches = totalMatches,
+		totalFiles = totalFiles,
+	}
+end
+
+local function sourceHash(source)
+	local hash = 5381
+	for index = 1, #source do
+		hash = (hash * 33 + string.byte(source, index)) % 4294967296
+	end
+	return string.format("%d:%08x", #source, hash)
+end
+
+function Explorer.getTreeV2(spec)
+	local root = game
+	if spec.root then
+		local resolved, err = InstanceRegistry.resolve(spec.root)
+		if not resolved then
+			return { success = false, error = err }
+		end
+		root = resolved
+	end
+	local maxDepth = math.clamp(spec.maxDepth or 3, 0, 12)
+	local maxNodes = math.clamp(spec.maxNodes or 1000, 1, 5000)
+	local nodeCount = 0
+	local truncated = false
+
+	local function serialize(instance, depth)
+		if depth > maxDepth or nodeCount >= maxNodes then
+			truncated = true
+			return nil
+		end
+		nodeCount += 1
+		local node = {
+			name = instance.Name,
+			className = instance.ClassName,
+			ref = InstanceRegistry.toRef(instance),
+		}
+		local children = instance:GetChildren()
+		table.sort(children, function(a, b)
+			if a.Name == b.Name then
+				return a.ClassName < b.ClassName
+			end
+			return a.Name < b.Name
+		end)
+		for _, child in children do
+			local childNode = serialize(child, depth + 1)
+			if childNode then
+				node.children = node.children or {}
+				table.insert(node.children, childNode)
+			end
+			if nodeCount >= maxNodes then
+				break
+			end
+		end
+		return node
+	end
+
+	if root == game then
+		local roots = {}
+		local services = game:GetChildren()
+		table.sort(services, function(a, b)
+			return a.Name < b.Name
+		end)
+		for _, service in services do
+			local node = serialize(service, 0)
+			if node then
+				table.insert(roots, node)
+			end
+			if nodeCount >= maxNodes then
+				break
+			end
+		end
+		return { success = true, roots = roots, nodeCount = nodeCount, truncated = truncated }
+	end
+
+	return { success = true, roots = { serialize(root, 0) }, nodeCount = nodeCount, truncated = truncated }
+end
+
+function Explorer.readScriptV2(spec)
+	local instance, err = InstanceRegistry.resolve(spec.target)
+	if not instance then
+		return { success = false, error = err }
+	end
+	if not SCRIPT_CLASSES[instance.ClassName] then
+		return { success = false, error = "Target is not a LuaSourceContainer" }
+	end
+	local ok, source = pcall(function()
+		return ScriptEditorService:GetEditorSource(instance)
+	end)
+	if not ok then
+		return { success = false, error = "Could not read script source: " .. tostring(source) }
+	end
+	return {
+		success = true,
+		target = InstanceRegistry.toRef(instance),
+		className = instance.ClassName,
+		source = source,
+		lineCount = select(2, source:gsub("\n", "\n")) + 1,
+		revision = sourceHash(source),
+	}
+end
+
+function Explorer.updateScriptV2(spec)
+	local instance, err = InstanceRegistry.resolve(spec.target)
+	if not instance then
+		return { success = false, error = err }
+	end
+	if not SCRIPT_CLASSES[instance.ClassName] then
+		return { success = false, error = "Target is not a LuaSourceContainer" }
+	end
+	if type(spec.source) ~= "string" then
+		return { success = false, error = "source must be a string" }
+	end
+	if #spec.source > 750000 then
+		return { success = false, error = "source exceeds 750,000 characters" }
+	end
+	if type(spec.expectedRevision) ~= "string" then
+		return { success = false, error = "expectedRevision is required; call studio_read_script first" }
+	end
+
+	local conflictRevision = nil
+	local ok, updateErr = pcall(function()
+		ScriptEditorService:UpdateSourceAsync(instance, function(oldSource)
+			local currentRevision = sourceHash(oldSource)
+			if currentRevision ~= spec.expectedRevision then
+				conflictRevision = currentRevision
+				return nil
+			end
+			return spec.source
+		end)
+	end)
+	if conflictRevision then
+		return {
+			success = false,
+			conflict = true,
+			error = "Script changed since it was read",
+			currentRevision = conflictRevision,
+		}
+	end
+	if not ok then
+		return { success = false, error = "Script update failed: " .. tostring(updateErr) }
+	end
+
+	local readback = Explorer.readScriptV2({ target = InstanceRegistry.toRef(instance) })
+	return {
+		success = true,
+		target = readback.target,
+		revision = readback.revision,
+		lineCount = readback.lineCount,
+	}
+end
+
+return Explorer