dominus-cli 2.2.1 → 2.4.0

package/plugin/src/Metadata.lua

@@ -0,0 +1,411 @@
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local ValueCodec = require(script.Parent.ValueCodec)
+
+local Metadata = {}
+
+local MAX_TARGETS = 100
+local MAX_ITEMS_PER_TARGET = 100
+local MAX_METHOD_CALLS = 50
+
+local ATTRIBUTE_TYPES = {
+	string = true,
+	boolean = true,
+	number = true,
+	UDim = true,
+	UDim2 = true,
+	BrickColor = true,
+	Color3 = true,
+	Vector2 = true,
+	Vector3 = true,
+	CFrame = true,
+	NumberSequence = true,
+	ColorSequence = true,
+	NumberRange = true,
+	Rect = true,
+	Font = true,
+}
+
+local METHOD_POLICY = {
+	GetAttribute = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetAttributes = { kind = "read", className = "Instance", params = {} },
+	GetTags = { kind = "read", className = "Instance", params = {} },
+	HasTag = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetFullName = { kind = "read", className = "Instance", params = {} },
+	IsA = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	IsAncestorOf = { kind = "read", className = "Instance", params = { { type = "Instance" } } },
+	IsDescendantOf = { kind = "read", className = "Instance", params = { { type = "Instance" } } },
+	FindFirstChild = {
+		kind = "read",
+		className = "Instance",
+		params = { { type = "string" }, { type = "boolean", optional = true } },
+	},
+	FindFirstChildOfClass = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstChildWhichIsA = {
+		kind = "read",
+		className = "Instance",
+		params = { { type = "string" }, { type = "boolean", optional = true } },
+	},
+	FindFirstAncestor = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstAncestorOfClass = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstAncestorWhichIsA = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetChildren = { kind = "read", className = "Instance", params = {} },
+	GetDescendants = { kind = "read", className = "Instance", params = {} },
+	GetPivot = { kind = "read", className = "PVInstance", params = {} },
+	GetScale = { kind = "read", className = "Model", params = {} },
+	GetBoundingBox = { kind = "read", className = "Model", params = {} },
+	AddTag = { kind = "write", className = "Instance", params = { { type = "string", tag = true } } },
+	RemoveTag = { kind = "write", className = "Instance", params = { { type = "string", tag = true } } },
+	SetAttribute = {
+		kind = "write",
+		className = "Instance",
+		params = { { type = "string", attributeName = true }, { type = "Attribute", allowNil = true } },
+	},
+	PivotTo = { kind = "write", className = "PVInstance", params = { { type = "CFrame" } } },
+	ScaleTo = { kind = "write", className = "Model", params = { { type = "number" } } },
+}
+
+local function resolve(ref, label)
+	local instance, err = InstanceRegistry.resolve(ref)
+	if not instance then
+		error(label .. ": " .. tostring(err))
+	end
+	return instance
+end
+
+local function validateName(value, label)
+	assert(type(value) == "string", label .. " must be a string")
+	assert(#value > 0 and #value <= 100, label .. " must contain 1 to 100 characters")
+	assert(not value:find("[%c]"), label .. " cannot contain control characters")
+	return value
+end
+
+local function validateTag(value)
+	return validateName(value, "Tag")
+end
+
+local function validateAttributeName(value)
+	return validateName(value, "Attribute name")
+end
+
+local function prepareAttributeChanges(set, remove, label)
+	set = set or {}
+	remove = remove or {}
+	assert(type(set) == "table" and type(remove) == "table", "set and remove must be arrays")
+	assert(#set + #remove > 0, label .. " has no attribute updates")
+	assert(#set + #remove <= MAX_ITEMS_PER_TARGET, "Too many attribute updates in " .. label)
+
+	local changes = {}
+	local seen = {}
+	for itemIndex, item in set do
+		assert(type(item) == "table" and type(item.value) == "table", "Set item " .. itemIndex .. " is invalid")
+		local name = validateAttributeName(item.name)
+		assert(not seen[name], "Attribute " .. name .. " appears more than once")
+		local typeName = item.value.type
+		assert(ATTRIBUTE_TYPES[typeName], "Unsupported attribute type: " .. tostring(typeName))
+		seen[name] = true
+		table.insert(changes, { name = name, value = ValueCodec.decodeTyped(typeName, item.value.value) })
+	end
+	for _, nameValue in remove do
+		local name = validateAttributeName(nameValue)
+		assert(not seen[name], "Attribute " .. name .. " cannot be set and removed together")
+		seen[name] = true
+		table.insert(changes, { name = name, remove = true })
+	end
+	return changes
+end
+
+local function applyPreparedAttributeChanges(target, changes)
+	for _, change in changes do
+		if change.remove then
+			target:SetAttribute(change.name, nil)
+		else
+			target:SetAttribute(change.name, change.value)
+		end
+	end
+end
+
+local function prepareTagChanges(add, remove, label)
+	add = add or {}
+	remove = remove or {}
+	assert(type(add) == "table" and type(remove) == "table", "add and remove must be arrays")
+	assert(#add + #remove > 0, label .. " has no tag updates")
+	assert(#add + #remove <= MAX_ITEMS_PER_TARGET, "Too many tag updates in " .. label)
+
+	local seen = {}
+	for _, tagValue in add do
+		local tag = validateTag(tagValue)
+		assert(not seen[tag], "Tag " .. tag .. " appears more than once")
+		seen[tag] = "add"
+	end
+	for _, tagValue in remove do
+		local tag = validateTag(tagValue)
+		assert(not seen[tag], "Tag " .. tag .. " cannot be added and removed together")
+		seen[tag] = "remove"
+	end
+	return add, remove
+end
+
+local function applyPreparedTagChanges(target, add, remove)
+	for _, tag in add do
+		target:AddTag(tag)
+	end
+	for _, tag in remove do
+		target:RemoveTag(tag)
+	end
+end
+
+local function sortedTags(instance)
+	local tags = instance:GetTags()
+	table.sort(tags)
+	return tags
+end
+
+local function encodedAttributes(instance)
+	local attributes = instance:GetAttributes()
+	local names = {}
+	for name in attributes do
+		table.insert(names, name)
+	end
+	table.sort(names)
+
+	local encoded = {}
+	for _, name in names do
+		table.insert(encoded, {
+			name = name,
+			value = ValueCodec.encodeTyped(attributes[name]),
+		})
+	end
+	return encoded
+end
+
+local function metadataFor(instance)
+	return {
+		ref = InstanceRegistry.toRef(instance),
+		name = instance.Name,
+		className = instance.ClassName,
+		tags = sortedTags(instance),
+		attributes = encodedAttributes(instance),
+	}
+end
+
+local function beginRecording(name)
+	local recording = ChangeHistoryService:TryBeginRecording(name)
+	if not recording then
+		error("Another plugin recording is already active")
+	end
+	return recording
+end
+
+function Metadata.get(spec)
+	assert(type(spec.targets) == "table" and #spec.targets > 0, "targets must contain at least one instance reference")
+	assert(#spec.targets <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " instances can be inspected at once")
+	local results = {}
+	for index, targetRef in spec.targets do
+		table.insert(results, metadataFor(resolve(targetRef, "Target " .. index)))
+	end
+	return { success = true, results = results }
+end
+
+function Metadata.setAttributes(spec)
+	assert(type(spec.operations) == "table" and #spec.operations > 0, "operations must contain at least one attribute update")
+	assert(#spec.operations <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " attribute operations are allowed")
+
+	local prepared = {}
+	for index, operation in spec.operations do
+		assert(type(operation) == "table", "Operation " .. index .. " must be an object")
+		table.insert(prepared, {
+			target = resolve(operation.target, "Operation " .. index .. " target"),
+			changes = prepareAttributeChanges(operation.set, operation.remove, "Operation " .. index),
+		})
+	end
+
+	local recording = beginRecording("Dominus 2: Update attributes")
+	local ok, err = pcall(function()
+		for _, operation in prepared do
+			applyPreparedAttributeChanges(operation.target, operation.changes)
+		end
+	end)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		return { success = false, error = tostring(err), rolledBack = true }
+	end
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+
+	local results = {}
+	for _, operation in prepared do
+		table.insert(results, metadataFor(operation.target))
+	end
+	return { success = true, operationCount = #prepared, results = results }
+end
+
+function Metadata.updateTags(spec)
+	assert(type(spec.operations) == "table" and #spec.operations > 0, "operations must contain at least one tag update")
+	assert(#spec.operations <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " tag operations are allowed")
+
+	local prepared = {}
+	for index, operation in spec.operations do
+		assert(type(operation) == "table", "Operation " .. index .. " must be an object")
+		local add, remove = prepareTagChanges(operation.add, operation.remove, "Operation " .. index)
+		table.insert(prepared, {
+			target = resolve(operation.target, "Operation " .. index .. " target"),
+			add = add,
+			remove = remove,
+		})
+	end
+
+	local recording = beginRecording("Dominus 2: Update tags")
+	local ok, err = pcall(function()
+		for _, operation in prepared do
+			applyPreparedTagChanges(operation.target, operation.add, operation.remove)
+		end
+	end)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		return { success = false, error = tostring(err), rolledBack = true }
+	end
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+
+	local results = {}
+	for _, operation in prepared do
+		table.insert(results, metadataFor(operation.target))
+	end
+	return { success = true, operationCount = #prepared, results = results }
+end
+
+function Metadata.applyAttributeChangesWithinRecording(target, set, remove)
+	local changes = prepareAttributeChanges(set, remove, "Mutation operation")
+	applyPreparedAttributeChanges(target, changes)
+	return encodedAttributes(target)
+end
+
+function Metadata.applyTagChangesWithinRecording(target, add, remove)
+	local preparedAdd, preparedRemove = prepareTagChanges(add, remove, "Mutation operation")
+	applyPreparedTagChanges(target, preparedAdd, preparedRemove)
+	return sortedTags(target)
+end
+
+local function publicPolicy(methodName, policy)
+	local params = {}
+	for _, param in policy.params do
+		table.insert(params, {
+			type = param.type,
+			optional = param.optional or false,
+		})
+	end
+	return {
+		name = methodName,
+		kind = policy.kind,
+		className = policy.className,
+		parameters = params,
+	}
+end
+
+function Metadata.listCallableMethods(spec)
+	local target = resolve(spec.target, "Target")
+	local methods = {}
+	for methodName, policy in METHOD_POLICY do
+		if target:IsA(policy.className) then
+			table.insert(methods, publicPolicy(methodName, policy))
+		end
+	end
+	table.sort(methods, function(left, right)
+		return left.name < right.name
+	end)
+	return {
+		success = true,
+		target = InstanceRegistry.toRef(target),
+		methods = methods,
+		blockedByDefault = true,
+	}
+end
+
+local function decodeArgument(argument, parameter, label)
+	assert(type(argument) == "table" and type(argument.type) == "string", label .. " must be a typed value")
+	if parameter.type == "Attribute" then
+		if argument.type == "nil" and parameter.allowNil then
+			return nil
+		end
+		assert(ATTRIBUTE_TYPES[argument.type], label .. " must be a supported Roblox attribute type")
+		return ValueCodec.decodeTyped(argument.type, argument.value)
+	end
+	assert(argument.type == parameter.type, label .. " must have type " .. parameter.type)
+	local decoded = ValueCodec.decodeTyped(argument.type, argument.value)
+	if parameter.tag then
+		validateTag(decoded)
+	elseif parameter.attributeName then
+		validateAttributeName(decoded)
+	end
+	return decoded
+end
+
+function Metadata.invoke(spec)
+	assert(type(spec.calls) == "table" and #spec.calls > 0, "calls must contain at least one method call")
+	assert(#spec.calls <= MAX_METHOD_CALLS, "At most " .. MAX_METHOD_CALLS .. " method calls are allowed")
+
+	local prepared = {}
+	local hasWrites = false
+	for index, call in spec.calls do
+		assert(type(call) == "table", "Call " .. index .. " must be an object")
+		local methodName = call.method
+		local policy = METHOD_POLICY[methodName]
+		assert(policy, "Method is not allowed by Dominus: " .. tostring(methodName))
+		local target = resolve(call.target, "Call " .. index .. " target")
+		assert(target:IsA(policy.className), methodName .. " requires " .. policy.className .. ", got " .. target.ClassName)
+		local arguments = call.arguments or {}
+		assert(type(arguments) == "table", "Call " .. index .. " arguments must be an array")
+		local minimum = 0
+		for _, parameter in policy.params do
+			if not parameter.optional then
+				minimum += 1
+			end
+		end
+		assert(#arguments >= minimum and #arguments <= #policy.params, methodName .. " received the wrong number of arguments")
+
+		local decoded = {}
+		for argumentIndex, argument in arguments do
+			decoded[argumentIndex] = decodeArgument(argument, policy.params[argumentIndex], "Argument " .. argumentIndex)
+		end
+		table.insert(prepared, {
+			target = target,
+			method = methodName,
+			policy = policy,
+			arguments = decoded,
+			argumentCount = #arguments,
+		})
+		hasWrites = hasWrites or policy.kind == "write"
+	end
+
+	local recording = hasWrites and beginRecording("Dominus 2: Invoke safe instance methods") or nil
+	local results = {}
+	local ok, err = pcall(function()
+		for _, call in prepared do
+			local method = call.target[call.method]
+			assert(type(method) == "function", call.method .. " is unavailable on " .. call.target.ClassName)
+			local returned = table.pack(method(call.target, table.unpack(call.arguments, 1, call.argumentCount)))
+			local values = {}
+			for resultIndex = 1, returned.n do
+				table.insert(values, ValueCodec.encodeTyped(returned[resultIndex]))
+			end
+			table.insert(results, {
+				target = InstanceRegistry.toRef(call.target),
+				method = call.method,
+				kind = call.policy.kind,
+				results = values,
+			})
+		end
+	end)
+	if not ok then
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		end
+		return { success = false, error = tostring(err), rolledBack = recording ~= nil }
+	end
+	if recording then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	end
+	return { success = true, callCount = #results, mutationRecorded = recording ~= nil, results = results }
+end
+
+return Metadata

package/plugin/src/Mutation.lua

@@ -1,6 +1,7 @@
 local ChangeHistoryService = game:GetService("ChangeHistoryService")
 
 local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local Metadata = require(script.Parent.Metadata)
 local ValueCodec = require(script.Parent.ValueCodec)
 
 local Mutation = {}
@@ -44,6 +45,7 @@ function Mutation.apply(spec)
 	end
 
 	local results = {}
+	local created = {}
 	local ok, err = pcall(function()
 		for index, operation in operations do
 			assert(type(operation) == "table", "Operation " .. index .. " must be an object")
@@ -54,17 +56,53 @@ function Mutation.apply(spec)
 					target = InstanceRegistry.toRef(target),
 					properties = setProperties(target, operation.properties),
 				})
+			elseif operation.op == "setAttributes" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				table.insert(results, {
+					op = operation.op,
+					target = InstanceRegistry.toRef(target),
+					attributes = Metadata.applyAttributeChangesWithinRecording(target, operation.set, operation.remove),
+				})
+			elseif operation.op == "updateTags" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				table.insert(results, {
+					op = operation.op,
+					target = InstanceRegistry.toRef(target),
+					tags = Metadata.applyTagChangesWithinRecording(target, operation.add, operation.remove),
+				})
 			elseif operation.op == "create" then
 				local parent = resolve(operation.parent, "Operation " .. index .. " parent")
 				assert(type(operation.className) == "string", "create.className must be a string")
 				assert(type(operation.name) == "string", "create.name must be a string")
 				local instance = Instance.new(operation.className)
+				table.insert(created, instance)
 				instance.Name = operation.name
 				if operation.properties then
 					setProperties(instance, operation.properties)
 				end
 				instance.Parent = parent
 				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(instance) })
+			elseif operation.op == "clone" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				assert(target ~= game and target.Parent ~= game, "Services cannot be cloned")
+				local parent = operation.parent and resolve(operation.parent, "Operation " .. index .. " parent") or target.Parent
+				assert(parent ~= nil, "Clone target has no parent")
+				local clone = target:Clone()
+				assert(clone ~= nil, "Clone target is not Archivable")
+				table.insert(created, clone)
+				if operation.name then
+					clone.Name = operation.name
+				end
+				if operation.properties then
+					setProperties(clone, operation.properties)
+				end
+				if operation.offset then
+					assert(clone:IsA("PVInstance"), "Only Models and BaseParts can be spatially offset")
+					local offset = ValueCodec.decodeForCurrent(Vector3.zero, operation.offset)
+					clone:PivotTo(clone:GetPivot() + offset)
+				end
+				clone.Parent = parent
+				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(clone) })
 			elseif operation.op == "move" then
 				local target = resolve(operation.target, "Operation " .. index .. " target")
 				local parent = resolve(operation.parent, "Operation " .. index .. " parent")
@@ -79,6 +117,13 @@ function Mutation.apply(spec)
 
 	if not ok then
 		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		for _, instance in created do
+			pcall(function()
+				if instance.Parent == nil then
+					instance:Destroy()
+				end
+			end)
+		end
 		return { success = false, error = tostring(err), rolledBack = true }
 	end
 

package/plugin/src/ValueCodec.lua

@@ -208,6 +208,122 @@ function ValueCodec.encode(value)
 	return tostring(value)
 end
 
+local TYPED_DEFAULTS = {
+	UDim = function()
+		return UDim.new()
+	end,
+	UDim2 = function()
+		return UDim2.new()
+	end,
+	Vector2 = function()
+		return Vector2.zero
+	end,
+	Vector3 = function()
+		return Vector3.zero
+	end,
+	Color3 = function()
+		return Color3.new()
+	end,
+	BrickColor = function()
+		return BrickColor.new("Medium stone grey")
+	end,
+	Rect = function()
+		return Rect.new()
+	end,
+	NumberRange = function()
+		return NumberRange.new(0)
+	end,
+	CFrame = function()
+		return CFrame.new()
+	end,
+	NumberSequence = function()
+		return NumberSequence.new(0)
+	end,
+	ColorSequence = function()
+		return ColorSequence.new(Color3.new())
+	end,
+	Font = function()
+		return Font.new("rbxasset://fonts/families/SourceSansPro.json")
+	end,
+}
+
+function ValueCodec.decodeTyped(typeName, value)
+	assert(type(typeName) == "string", "Typed value requires a type")
+	if typeName == "nil" then
+		return nil
+	end
+	if typeName == "string" or typeName == "number" or typeName == "boolean" then
+		return ValueCodec.decodeForCurrent(typeName == "string" and "" or typeName == "number" and 0 or false, value)
+	end
+	if typeName == "Instance" then
+		local resolved, err = InstanceRegistry.resolve(value)
+		if not resolved then
+			error(err)
+		end
+		return resolved
+	end
+	local createDefault = TYPED_DEFAULTS[typeName]
+	if not createDefault then
+		error("Unsupported typed value: " .. typeName)
+	end
+	return ValueCodec.decodeForCurrent(createDefault(), value)
+end
+
+local function encodeSerializable(value, depth, state, seen)
+	if depth > 5 then
+		return "<maximum depth reached>"
+	end
+	if type(value) ~= "table" then
+		return ValueCodec.encode(value)
+	end
+	if seen[value] then
+		return "<cycle>"
+	end
+	seen[value] = true
+
+	local count = 0
+	local maxIndex = 0
+	local isArray = true
+	for key in value do
+		count += 1
+		state.count += 1
+		if state.count > state.limit then
+			seen[value] = nil
+			return "<result truncated>"
+		end
+		if type(key) ~= "number" or key < 1 or key % 1 ~= 0 then
+			isArray = false
+		else
+			maxIndex = math.max(maxIndex, key)
+		end
+	end
+
+	local result = {}
+	if isArray and maxIndex == count then
+		for index = 1, maxIndex do
+			result[index] = encodeSerializable(value[index], depth + 1, state, seen)
+		end
+	else
+		for key, child in value do
+			result[tostring(key)] = encodeSerializable(child, depth + 1, state, seen)
+		end
+	end
+	seen[value] = nil
+	return result
+end
+
+function ValueCodec.encodeSerializable(value, limit)
+	return encodeSerializable(value, 0, { count = 0, limit = limit or 500 }, {})
+end
+
+function ValueCodec.encodeTyped(value, limit)
+	local encoded = { type = typeof(value) }
+	if value ~= nil then
+		encoded.value = ValueCodec.encodeSerializable(value, limit)
+	end
+	return encoded
+end
+
 function ValueCodec.setProperty(instance, propertyName, value)
 	if propertyName == "Parent" or propertyName == "ClassName" or propertyName == "Source" then
 		error("Property cannot be changed through setProperties: " .. propertyName)