@chrrxs/robloxstudio-mcp 2.23.1 → 3.0.1

package/studio-plugin/src/modules/handlers/QueryHandlers.ts

@@ -1,874 +0,0 @@
-import Utils from "../Utils";
-
-const { getInstancePath, getInstanceByPath, readScriptSource } = Utils;
-
-interface TreeNode {
-	name: string;
-	className: string;
-	path?: string;
-	children: TreeNode[];
-	hasSource?: boolean;
-	scriptType?: string;
-	enabled?: boolean;
-}
-
-function getFileTree(requestData: Record<string, unknown>) {
-	const path = (requestData.path as string) ?? "";
-	const startInstance = getInstanceByPath(path);
-
-	if (!startInstance) {
-		return { error: `Path not found: ${path}` };
-	}
-
-	function buildTree(instance: Instance, depth: number): TreeNode {
-		if (depth > 10) {
-			return { name: instance.Name, className: instance.ClassName, children: [] };
-		}
-
-		const node: TreeNode = {
-			name: instance.Name,
-			className: instance.ClassName,
-			path: getInstancePath(instance),
-			children: [],
-		};
-
-		if (instance.IsA("LuaSourceContainer")) {
-			node.hasSource = true;
-			node.scriptType = instance.ClassName;
-			if (instance.IsA("BaseScript")) {
-				node.enabled = instance.Enabled;
-			}
-		}
-
-		for (const child of instance.GetChildren()) {
-			node.children.push(buildTree(child, depth + 1));
-		}
-
-		return node;
-	}
-
-	return {
-		tree: buildTree(startInstance, 0),
-		timestamp: tick(),
-	};
-}
-
-function searchFiles(requestData: Record<string, unknown>) {
-	const query = requestData.query as string;
-	const searchType = (requestData.searchType as string) ?? "name";
-
-	if (!query) return { error: "Query is required" };
-
-	const results: { name: string; className: string; path: string; hasSource: boolean; enabled?: boolean }[] = [];
-
-	function searchRecursive(instance: Instance) {
-		let match = false;
-
-		if (searchType === "name") {
-			match = instance.Name.lower().find(query.lower())[0] !== undefined;
-		} else if (searchType === "type") {
-			match = instance.ClassName.lower().find(query.lower())[0] !== undefined;
-		} else if (searchType === "content" && instance.IsA("LuaSourceContainer")) {
-			match = readScriptSource(instance).lower().find(query.lower())[0] !== undefined;
-		}
-
-		if (match) {
-			const entry: { name: string; className: string; path: string; hasSource: boolean; enabled?: boolean } = {
-				name: instance.Name,
-				className: instance.ClassName,
-				path: getInstancePath(instance),
-				hasSource: instance.IsA("LuaSourceContainer"),
-			};
-			if (instance.IsA("BaseScript")) {
-				entry.enabled = instance.Enabled;
-			}
-			results.push(entry);
-		}
-
-		for (const child of instance.GetChildren()) {
-			searchRecursive(child);
-		}
-	}
-
-	searchRecursive(game);
-
-	return { results, query, searchType, count: results.size() };
-}
-
-function getPlaceInfo(_requestData: Record<string, unknown>) {
-	const dataModelName = game.Name;
-	let placeName = dataModelName;
-
-	if (game.PlaceId > 0) {
-		const MarketplaceService = game.GetService("MarketplaceService");
-		const [ok, info] = pcall(() => MarketplaceService.GetProductInfo(game.PlaceId));
-		if (ok && info !== undefined) {
-			const name = (info as { Name?: string }).Name;
-			if (typeIs(name, "string") && name !== "") {
-				placeName = name;
-			}
-		}
-	}
-
-	return {
-		placeName,
-		dataModelName,
-		placeId: game.PlaceId,
-		gameId: game.GameId,
-		jobId: game.JobId,
-		workspace: {
-			name: game.Workspace.Name,
-			className: game.Workspace.ClassName,
-		},
-	};
-}
-
-function getServices(requestData: Record<string, unknown>) {
-	const serviceName = requestData.serviceName as string | undefined;
-
-	if (serviceName) {
-		const [ok, service] = pcall(() => game.GetService(serviceName as keyof Services));
-		if (ok && service) {
-			return {
-				service: {
-					name: service.Name,
-					className: service.ClassName,
-					path: getInstancePath(service as Instance),
-					childCount: (service as Instance).GetChildren().size(),
-				},
-			};
-		} else {
-			return { error: `Service not found: ${serviceName}` };
-		}
-	} else {
-		const services: { name: string; className: string; path: string; childCount: number }[] = [];
-		const commonServices = [
-			"Workspace", "Players", "StarterGui", "StarterPack", "StarterPlayer",
-			"ReplicatedStorage", "ServerStorage", "ServerScriptService",
-			"HttpService", "TeleportService", "DataStoreService",
-		];
-
-		for (const svcName of commonServices) {
-			const [ok, service] = pcall(() => game.GetService(svcName as keyof Services));
-			if (ok && service) {
-				services.push({
-					name: service.Name,
-					className: service.ClassName,
-					path: getInstancePath(service as Instance),
-					childCount: (service as Instance).GetChildren().size(),
-				});
-			}
-		}
-
-		return { services };
-	}
-}
-
-function searchObjects(requestData: Record<string, unknown>) {
-	const query = requestData.query as string;
-	const searchType = (requestData.searchType as string) ?? "name";
-	const propertyName = requestData.propertyName as string | undefined;
-
-	if (!query) return { error: "Query is required" };
-
-	const results: { name: string; className: string; path: string }[] = [];
-
-	function searchRecursive(instance: Instance) {
-		let match = false;
-
-		if (searchType === "name") {
-			match = instance.Name.lower().find(query.lower())[0] !== undefined;
-		} else if (searchType === "class") {
-			match = instance.ClassName.lower().find(query.lower())[0] !== undefined;
-		} else if (searchType === "property" && propertyName) {
-			const [success, value] = pcall(() => tostring((instance as unknown as Record<string, unknown>)[propertyName]));
-			if (success) {
-				match = (value as string).lower().find(query.lower())[0] !== undefined;
-			}
-		}
-
-		if (match) {
-			results.push({
-				name: instance.Name,
-				className: instance.ClassName,
-				path: getInstancePath(instance),
-			});
-		}
-
-		for (const child of instance.GetChildren()) {
-			searchRecursive(child);
-		}
-	}
-
-	searchRecursive(game);
-
-	return { results, query, searchType, count: results.size() };
-}
-
-function getInstanceProperties(requestData: Record<string, unknown>) {
-	const instancePath = requestData.instancePath as string;
-	const excludeSource = (requestData.excludeSource as boolean) ?? false;
-	if (!instancePath) return { error: "Instance path is required" };
-
-	const instance = getInstanceByPath(instancePath);
-	if (!instance) return { error: `Instance not found: ${instancePath}` };
-
-	const properties: Record<string, unknown> = {};
-	const [success, result] = pcall(() => {
-		const basicProps = ["Name", "ClassName", "Parent"];
-		for (const prop of basicProps) {
-			const [propSuccess, propValue] = pcall(() => {
-				const val = (instance as unknown as Record<string, unknown>)[prop];
-				if (prop === "Parent" && val) return getInstancePath(val as Instance);
-				if (val === undefined) return "nil";
-				return tostring(val);
-			});
-			if (propSuccess) properties[prop] = propValue;
-		}
-
-		const commonProps = [
-			"Size", "Position", "Rotation", "CFrame", "Anchored", "CanCollide",
-			"Transparency", "BrickColor", "Material", "Color", "Text", "TextColor3",
-			"BackgroundColor3", "Image", "ImageColor3", "Visible", "Active", "ZIndex",
-			"BorderSizePixel", "BackgroundTransparency", "ImageTransparency",
-			"TextTransparency", "Value", "Enabled", "Brightness", "Range", "Shadows",
-			"Face", "SurfaceType",
-		];
-
-		for (const prop of commonProps) {
-			const [propSuccess, propValue] = pcall(() => {
-				const val = (instance as unknown as Record<string, unknown>)[prop];
-				if (typeOf(val) === "UDim2") {
-					const udim = val as UDim2;
-					return {
-						X: { Scale: udim.X.Scale, Offset: udim.X.Offset },
-						Y: { Scale: udim.Y.Scale, Offset: udim.Y.Offset },
-						_type: "UDim2",
-					};
-				}
-				return tostring(val);
-			});
-			if (propSuccess) properties[prop] = propValue;
-		}
-
-		if (instance.IsA("LuaSourceContainer")) {
-			if (!excludeSource) {
-				properties.Source = readScriptSource(instance);
-			} else {
-				const src = readScriptSource(instance);
-				properties.SourceLength = src.size();
-				properties.LineCount = Utils.splitLines(src)[0].size();
-			}
-			if (instance.IsA("BaseScript")) {
-				properties.Enabled = tostring(instance.Enabled);
-			}
-		}
-
-		if (instance.IsA("Part")) {
-			properties.Shape = tostring(instance.Shape);
-		}
-
-		if (instance.IsA("BasePart")) {
-			properties.TopSurface = tostring(instance.TopSurface);
-			properties.BottomSurface = tostring(instance.BottomSurface);
-		}
-
-		if (instance.IsA("MeshPart")) {
-			properties.MeshId = tostring(instance.MeshId);
-			properties.TextureID = tostring(instance.TextureID);
-		}
-
-		if (instance.IsA("SpecialMesh")) {
-			properties.MeshId = tostring(instance.MeshId);
-			properties.TextureId = tostring(instance.TextureId);
-			properties.MeshType = tostring(instance.MeshType);
-		}
-
-		if (instance.IsA("Sound")) {
-			properties.SoundId = tostring(instance.SoundId);
-			properties.TimeLength = tostring(instance.TimeLength);
-			properties.IsPlaying = tostring(instance.IsPlaying);
-		}
-
-		if (instance.IsA("Animation")) {
-			properties.AnimationId = tostring(instance.AnimationId);
-		}
-
-		if (instance.IsA("Decal") || instance.IsA("Texture")) {
-			properties.Texture = tostring((instance as Decal | Texture).Texture);
-		}
-
-		if (instance.IsA("Shirt")) {
-			properties.ShirtTemplate = tostring(instance.ShirtTemplate);
-		} else if (instance.IsA("Pants")) {
-			properties.PantsTemplate = tostring(instance.PantsTemplate);
-		} else if (instance.IsA("ShirtGraphic")) {
-			properties.Graphic = tostring(instance.Graphic);
-		}
-
-		properties.ChildCount = tostring(instance.GetChildren().size());
-	});
-
-	if (success) {
-		return { instancePath, className: instance.ClassName, properties };
-	} else {
-		return { error: `Failed to get properties: ${result}` };
-	}
-}
-
-function getInstanceChildren(requestData: Record<string, unknown>) {
-	const instancePath = requestData.instancePath as string;
-	if (!instancePath) return { error: "Instance path is required" };
-
-	const instance = getInstanceByPath(instancePath);
-	if (!instance) return { error: `Instance not found: ${instancePath}` };
-
-	const children: { name: string; className: string; path: string; hasChildren: boolean; hasSource: boolean; enabled?: boolean }[] = [];
-	for (const child of instance.GetChildren()) {
-		const entry: { name: string; className: string; path: string; hasChildren: boolean; hasSource: boolean; enabled?: boolean } = {
-			name: child.Name,
-			className: child.ClassName,
-			path: getInstancePath(child),
-			hasChildren: child.GetChildren().size() > 0,
-			hasSource: child.IsA("LuaSourceContainer"),
-		};
-		if (child.IsA("BaseScript")) {
-			entry.enabled = child.Enabled;
-		}
-		children.push(entry);
-	}
-
-	return { instancePath, children, count: children.size() };
-}
-
-function searchByProperty(requestData: Record<string, unknown>) {
-	const propertyName = requestData.propertyName as string;
-	const propertyValue = requestData.propertyValue as string;
-
-	if (!propertyName || !propertyValue) {
-		return { error: "Property name and value are required" };
-	}
-
-	const results: { name: string; className: string; path: string; propertyValue: string }[] = [];
-
-	function searchRecursive(instance: Instance) {
-		const [success, value] = pcall(() => tostring((instance as unknown as Record<string, unknown>)[propertyName]));
-		if (success && (value as string).lower().find(propertyValue.lower())[0] !== undefined) {
-			results.push({
-				name: instance.Name,
-				className: instance.ClassName,
-				path: getInstancePath(instance),
-				propertyValue: value as string,
-			});
-		}
-		for (const child of instance.GetChildren()) {
-			searchRecursive(child);
-		}
-	}
-
-	searchRecursive(game);
-	return { propertyName, propertyValue, results, count: results.size() };
-}
-
-function getClassInfo(requestData: Record<string, unknown>) {
-	const className = requestData.className as string;
-	if (!className) return { error: "Class name is required" };
-
-	let [success, tempInstance] = pcall(() => new Instance(className as keyof CreatableInstances));
-	let isService = false;
-
-	if (!success) {
-		const [serviceSuccess, serviceInstance] = pcall(() =>
-			game.GetService(className as keyof Services),
-		);
-		if (serviceSuccess && serviceInstance) {
-			success = true;
-			tempInstance = serviceInstance as unknown as Instance;
-			isService = true;
-		}
-	}
-
-	if (!success) return { error: `Invalid class name: ${className}` };
-
-	const classInfo: {
-		className: string;
-		isService: boolean;
-		properties: string[];
-		methods: string[];
-		events: string[];
-	} = { className, isService, properties: [], methods: [], events: [] };
-
-	const commonProps = [
-		"Name", "ClassName", "Parent", "Size", "Position", "Rotation", "CFrame",
-		"Anchored", "CanCollide", "Transparency", "BrickColor", "Material", "Color",
-		"Text", "TextColor3", "BackgroundColor3", "Image", "ImageColor3", "Visible",
-		"Active", "ZIndex", "BorderSizePixel", "BackgroundTransparency",
-		"ImageTransparency", "TextTransparency", "Value", "Enabled", "Brightness",
-		"Range", "Shadows",
-	];
-
-	for (const prop of commonProps) {
-		const [propSuccess] = pcall(() => (tempInstance as unknown as Record<string, unknown>)[prop]);
-		if (propSuccess) classInfo.properties.push(prop);
-	}
-
-	const commonMethods = [
-		"Destroy", "Clone", "FindFirstChild", "FindFirstChildOfClass",
-		"GetChildren", "IsA", "IsAncestorOf", "IsDescendantOf", "WaitForChild",
-	];
-
-	for (const method of commonMethods) {
-		const [methodSuccess] = pcall(() => (tempInstance as unknown as Record<string, unknown>)[method]);
-		if (methodSuccess) classInfo.methods.push(method);
-	}
-
-	if (!isService) {
-		(tempInstance as Instance).Destroy();
-	}
-
-	return classInfo;
-}
-
-function getProjectStructure(requestData: Record<string, unknown>) {
-	const startPath = (requestData.path as string) ?? "";
-	const maxDepth = (requestData.maxDepth as number) ?? 3;
-	const showScriptsOnly = (requestData.scriptsOnly as boolean) ?? false;
-
-	if (startPath === "" || startPath === "game") {
-		const services: Record<string, unknown>[] = [];
-		const mainServices = [
-			"Workspace", "ServerScriptService", "ServerStorage", "ReplicatedStorage",
-			"StarterGui", "StarterPack", "StarterPlayer", "Players",
-		];
-
-		for (const serviceName of mainServices) {
-			const [svcOk, service] = pcall(() => game.GetService(serviceName as keyof Services));
-			if (svcOk && service) {
-				services.push({
-					name: service.Name,
-					className: service.ClassName,
-					path: getInstancePath(service as Instance),
-					childCount: (service as Instance).GetChildren().size(),
-					hasChildren: (service as Instance).GetChildren().size() > 0,
-				});
-			}
-		}
-
-		return {
-			type: "service_overview",
-			services,
-			timestamp: tick(),
-			note: "Use path parameter to explore specific locations (e.g., 'game.ServerScriptService')",
-		};
-	}
-
-	const startInstance = getInstanceByPath(startPath);
-	if (!startInstance) return { error: `Path not found: ${startPath}` };
-
-	function getStructure(instance: Instance, depth: number): Record<string, unknown> {
-		if (depth > maxDepth) {
-			return {
-				name: instance.Name,
-				className: instance.ClassName,
-				path: getInstancePath(instance),
-				childCount: instance.GetChildren().size(),
-				hasMore: true,
-				note: "Max depth reached - use this path to explore further",
-			};
-		}
-
-		const node: Record<string, unknown> = {
-			name: instance.Name,
-			className: instance.ClassName,
-			path: getInstancePath(instance),
-			children: [] as Record<string, unknown>[],
-		};
-
-		if (instance.IsA("LuaSourceContainer")) {
-			node.hasSource = true;
-			node.scriptType = instance.ClassName;
-			if (instance.IsA("BaseScript")) {
-				node.enabled = instance.Enabled;
-			}
-		}
-
-		if (instance.IsA("GuiObject")) {
-			node.visible = instance.Visible;
-			if (instance.IsA("Frame") || instance.IsA("ScreenGui")) {
-				node.guiType = "container";
-			} else if (instance.IsA("TextLabel") || instance.IsA("TextButton")) {
-				node.guiType = "text";
-				const textInst = instance as TextLabel | TextButton;
-				if (textInst.Text !== "") node.text = textInst.Text;
-			} else if (instance.IsA("ImageLabel") || instance.IsA("ImageButton")) {
-				node.guiType = "image";
-			}
-		}
-
-		let children = instance.GetChildren();
-		if (showScriptsOnly) {
-			children = children.filter(
-				(child) => child.IsA("BaseScript") || child.IsA("Folder") || child.IsA("ModuleScript"),
-			);
-		}
-
-		const nodeChildren = node.children as Record<string, unknown>[];
-		const childCount = children.size();
-		if (childCount > 20 && depth < maxDepth) {
-			const classGroups = new Map<string, Instance[]>();
-			for (const child of children) {
-				const cn = child.ClassName;
-				if (!classGroups.has(cn)) classGroups.set(cn, []);
-				classGroups.get(cn)!.push(child);
-			}
-
-			const childSummary: Record<string, unknown>[] = [];
-			classGroups.forEach((classChildren, cn) => {
-				childSummary.push({
-					className: cn,
-					count: classChildren.size(),
-					examples: [classChildren[0]?.Name, classChildren[1]?.Name],
-				});
-			});
-			node.childSummary = childSummary;
-
-			classGroups.forEach((classChildren, cn) => {
-				const limit = math.min(3, classChildren.size());
-				for (let i = 0; i < limit; i++) {
-					nodeChildren.push(getStructure(classChildren[i], depth + 1));
-				}
-				if (classChildren.size() > 3) {
-					nodeChildren.push({
-						name: `... ${classChildren.size() - 3} more ${cn} objects`,
-						className: "MoreIndicator",
-						path: `${getInstancePath(instance)} [${cn} children]`,
-						note: "Use specific path to explore these objects",
-					});
-				}
-			});
-		} else {
-			for (const child of children) {
-				nodeChildren.push(getStructure(child, depth + 1));
-			}
-		}
-
-		return node;
-	}
-
-	const result = getStructure(startInstance, 0);
-	result.requestedPath = startPath;
-	result.maxDepth = maxDepth;
-	result.scriptsOnly = showScriptsOnly;
-	result.timestamp = tick();
-
-	return result;
-}
-
-// Split a Lua pattern on TOP-LEVEL "|" into alternatives. Lua patterns have no
-// alternation operator, so "foo|bar" would otherwise be matched as the literal
-// text "foo|bar" and silently never hit. "%|" stays a literal pipe, and "%bxy"
-// keeps both balanced-match delimiter characters.
-function splitLuaAlternation(pattern: string): string[] {
-	const parts: string[] = [];
-	let current = "";
-	let i = 1;
-	const n = pattern.size();
-	let inCharClass = false;
-	while (i <= n) {
-		const c = string.sub(pattern, i, i);
-		if (c === "%") {
-			if (string.sub(pattern, i + 1, i + 1) === "b") {
-				current += string.sub(pattern, i, math.min(i + 3, n));
-				i += 4;
-				continue;
-			}
-			// Preserve an escape pair (e.g. %|, %., %d) intact.
-			current += string.sub(pattern, i, i + 1);
-			i += 2;
-		} else if (c === "[") {
-			inCharClass = true;
-			current += c;
-			i += 1;
-		} else if (c === "]") {
-			inCharClass = false;
-			current += c;
-			i += 1;
-		} else if (c === "|" && !inCharClass) {
-			parts.push(current);
-			current = "";
-			i += 1;
-		} else {
-			current += c;
-			i += 1;
-		}
-	}
-	parts.push(current);
-	return parts;
-}
-
-// Return the earliest match across alternatives (mirrors regex alternation).
-function findFirstPattern(line: string, alternatives: string[]): [number | undefined, number | undefined] {
-	let bestStart: number | undefined;
-	let bestEnd: number | undefined;
-	for (const alt of alternatives) {
-		if (alt === "") continue;
-		const [s, e] = string.find(line, alt);
-		if (s !== undefined && (bestStart === undefined || s < bestStart)) {
-			bestStart = s;
-			bestEnd = e as number;
-		}
-	}
-	return [bestStart, bestEnd];
-}
-
-function grepScripts(requestData: Record<string, unknown>) {
-	const pattern = requestData.pattern as string;
-	if (!pattern) return { error: "pattern is required" };
-
-	const usePattern = (requestData.usePattern as boolean) ?? false;
-	if (usePattern && requestData.caseSensitive === false) {
-		return {
-			error: "Case-insensitive Lua pattern search is not supported. Omit caseSensitive or pass caseSensitive: true with usePattern: true, or use literal search.",
-		};
-	}
-
-	const caseSensitive = usePattern ? true : ((requestData.caseSensitive as boolean) ?? false);
-	const contextLines = (requestData.contextLines as number) ?? 0;
-	const maxResults = (requestData.maxResults as number) ?? 100;
-	const maxResultsPerScript = (requestData.maxResultsPerScript as number) ?? 0;
-	const filesOnly = (requestData.filesOnly as boolean) ?? false;
-	const searchPath = (requestData.path as string) ?? "";
-	const classFilter = requestData.classFilter as string | undefined;
-
-	const startInstance = searchPath !== "" ? getInstanceByPath(searchPath) : game;
-	if (!startInstance) return { error: `Path not found: ${searchPath}` };
-
-	// Prepare pattern for matching
-	const searchPattern = caseSensitive ? pattern : pattern.lower();
-	// Pre-split top-level "|" alternation once (pattern mode only).
-	const patternAlternatives = usePattern ? splitLuaAlternation(searchPattern) : undefined;
-
-	interface LineMatch {
-		line: number;
-		column: number;
-		text: string;
-		before: string[];
-		after: string[];
-	}
-
-	interface ScriptResult {
-		instancePath: string;
-		name: string;
-		className: string;
-		enabled?: boolean;
-		matches: LineMatch[];
-	}
-
-	const results: ScriptResult[] = [];
-	let totalMatches = 0;
-	let scriptsSearched = 0;
-	let hitLimit = false;
-
-	function searchInstance(instance: Instance) {
-		if (hitLimit) return;
-
-		if (instance.IsA("LuaSourceContainer")) {
-			// Apply class filter
-			if (classFilter) {
-				if (!instance.ClassName.lower().find(classFilter.lower())[0]) return;
-			}
-
-			scriptsSearched++;
-			const source = readScriptSource(instance);
-			const [lines] = Utils.splitLines(source);
-			const scriptMatches: LineMatch[] = [];
-			let scriptMatchCount = 0;
-
-			for (let i = 0; i < lines.size(); i++) {
-				if (hitLimit) break;
-				if (maxResultsPerScript > 0 && scriptMatchCount >= maxResultsPerScript) break;
-
-				const line = lines[i];
-				const searchLine = caseSensitive ? line : line.lower();
-
-				let matchStart: number | undefined;
-				let matchEnd: number | undefined;
-
-				if (usePattern) {
-					[matchStart, matchEnd] = findFirstPattern(searchLine, patternAlternatives!);
-				} else {
-					[matchStart, matchEnd] = string.find(searchLine, searchPattern, 1, true);
-				}
-
-				if (matchStart !== undefined) {
-					scriptMatchCount++;
-					totalMatches++;
-
-					if (totalMatches > maxResults) {
-						hitLimit = true;
-						break;
-					}
-
-					if (!filesOnly) {
-						// Gather context lines
-						const before: string[] = [];
-						const after: string[] = [];
-
-						if (contextLines > 0) {
-							const beforeStart = math.max(0, i - contextLines);
-							for (let j = beforeStart; j < i; j++) {
-								before.push(lines[j]);
-							}
-							const afterEnd = math.min(lines.size() - 1, i + contextLines);
-							for (let j = i + 1; j <= afterEnd; j++) {
-								after.push(lines[j]);
-							}
-						}
-
-						scriptMatches.push({
-							line: i + 1, // 1-indexed
-							column: matchStart,
-							text: line,
-							before,
-							after,
-						});
-					}
-				}
-			}
-
-			if (scriptMatchCount > 0) {
-				const scriptResult: ScriptResult = {
-					instancePath: getInstancePath(instance),
-					name: instance.Name,
-					className: instance.ClassName,
-					matches: scriptMatches,
-				};
-				if (instance.IsA("BaseScript")) {
-					scriptResult.enabled = instance.Enabled;
-				}
-				results.push(scriptResult);
-			}
-		}
-
-		for (const child of instance.GetChildren()) {
-			if (hitLimit) return;
-			searchInstance(child);
-		}
-	}
-
-	searchInstance(startInstance);
-
-	return {
-		results,
-		pattern,
-		totalMatches: hitLimit ? `>${maxResults}` : totalMatches,
-		scriptsSearched,
-		scriptsMatched: results.size(),
-		truncated: hitLimit,
-		options: { caseSensitive, contextLines, usePattern, filesOnly, maxResults, maxResultsPerScript },
-	};
-}
-
-function getDescendants(requestData: Record<string, unknown>) {
-	const instancePath = requestData.instancePath as string;
-	if (!instancePath) return { error: "Instance path is required" };
-
-	const maxDepth = (requestData.maxDepth as number) ?? 10;
-	const classFilter = requestData.classFilter as string | undefined;
-
-	const instance = getInstanceByPath(instancePath);
-	if (!instance) return { error: `Instance not found: ${instancePath}` };
-
-	const descendants: { name: string; className: string; path: string; depth: number }[] = [];
-
-	function collect(inst: Instance, depth: number) {
-		if (depth > maxDepth) return;
-		for (const child of inst.GetChildren()) {
-			if (classFilter && !child.IsA(classFilter as keyof Instances)) continue;
-			descendants.push({
-				name: child.Name,
-				className: child.ClassName,
-				path: getInstancePath(child),
-				depth,
-			});
-			collect(child, depth + 1);
-		}
-	}
-
-	collect(instance, 1);
-
-	return { instancePath, descendants, count: descendants.size(), maxDepth };
-}
-
-function compareInstances(requestData: Record<string, unknown>) {
-	const instancePathA = requestData.instancePathA as string;
-	const instancePathB = requestData.instancePathB as string;
-
-	if (!instancePathA || !instancePathB) {
-		return { error: "Both instancePathA and instancePathB are required" };
-	}
-
-	const instA = getInstanceByPath(instancePathA);
-	if (!instA) return { error: `Instance not found: ${instancePathA}` };
-
-	const instB = getInstanceByPath(instancePathB);
-	if (!instB) return { error: `Instance not found: ${instancePathB}` };
-
-	const commonProps = [
-		"Name", "ClassName",
-		"Size", "Position", "Rotation", "CFrame", "Anchored", "CanCollide",
-		"Transparency", "BrickColor", "Material", "Color", "Text", "TextColor3",
-		"BackgroundColor3", "Image", "ImageColor3", "Visible", "Active", "ZIndex",
-		"BorderSizePixel", "BackgroundTransparency", "ImageTransparency",
-		"TextTransparency", "Value", "Enabled", "Brightness", "Range", "Shadows",
-	];
-
-	const matching: Record<string, string> = {};
-	const differing: Record<string, { a: string; b: string }> = {};
-	const onlyA: string[] = [];
-	const onlyB: string[] = [];
-
-	for (const prop of commonProps) {
-		const [okA, valA] = pcall(() => tostring((instA as unknown as Record<string, unknown>)[prop]));
-		const [okB, valB] = pcall(() => tostring((instB as unknown as Record<string, unknown>)[prop]));
-
-		if (okA && okB) {
-			if (valA === valB) {
-				matching[prop] = valA as string;
-			} else {
-				differing[prop] = { a: valA as string, b: valB as string };
-			}
-		} else if (okA) {
-			onlyA.push(prop);
-		} else if (okB) {
-			onlyB.push(prop);
-		}
-	}
-
-	return {
-		instancePathA,
-		instancePathB,
-		classNameA: instA.ClassName,
-		classNameB: instB.ClassName,
-		matching,
-		differing,
-		onlyA,
-		onlyB,
-	};
-}
-
-export = {
-	getFileTree,
-	searchFiles,
-	getPlaceInfo,
-	getServices,
-	searchObjects,
-	getInstanceProperties,
-	getInstanceChildren,
-	searchByProperty,
-	getClassInfo,
-	getProjectStructure,
-	grepScripts,
-	getDescendants,
-	compareInstances,
-};