@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/commands/explorer/grep/grep-scripts.spec.lua

@@ -0,0 +1,130 @@
+--!strict
+--[[
+	@class grep-scripts.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local GrepScriptsAction = require("grep-scripts")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local router = ActionRouter.new()
+	GrepScriptsAction.register(router)
+
+	local root = Instance.new("Folder")
+	root.Name = `GrepScriptsSpec{HttpService:GenerateGUID(false)}`
+
+	-- Setting Source needs plugin security, so the specs supply each script's text
+	local sources: { [Instance]: string } = {}
+	local function addScript(className: string, name: string, source: string)
+		local script = Instance.new(className)
+		script.Name = name
+		script.Parent = root
+		sources[script] = source
+	end
+
+	addScript("ModuleScript", "Combat", "local damage = 10\r\nfunction Combat.Hit()\n\treturn DAMAGE * 2\nend")
+	addScript("Script", "Main", "print('ready')\nlocal Combat = require(script.Parent.Combat)")
+
+	local readSource = GrepScriptsAction._readSource
+	GrepScriptsAction._readSource = function(script: LuaSourceContainer): string
+		return sources[script] or ""
+	end
+
+	root.Parent = workspace
+
+	local controller = {
+		root = root,
+		rootPath = `Workspace.{root.Name}`,
+		grep = function(payload: { [string]: any }): any
+			return router:Dispatch({ type = "grepScripts", sessionId = "session-1", payload = payload })
+		end,
+		Destroy = function(_self)
+			GrepScriptsAction._readSource = readSource
+			root:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+local function getLocations(response: any): { string }
+	local locations = {}
+	for _, match in response.payload.matches do
+		local name = string.match(match.path, "[^%.]+$")
+		table.insert(locations, `{name}:{match.line}`)
+	end
+	table.sort(locations)
+	return locations
+end
+
+describe("grepScripts", function()
+	it("should find plain text case-insensitively, with line numbers", function()
+		local controller = setup()
+
+		local response = controller.grep({ root = controller.rootPath, pattern = "damage" })
+
+		expect(response.type).toEqual("grepScriptsResult")
+		expect(getLocations(response)).toEqual({ "Combat:1", "Combat:3" })
+		expect(response.payload.searched).toEqual(2)
+		controller:Destroy()
+	end)
+
+	it("should keep case with caseSensitive and drop carriage returns", function()
+		local controller = setup()
+
+		local response = controller.grep({ root = controller.rootPath, pattern = "damage", caseSensitive = true })
+
+		expect(getLocations(response)).toEqual({ "Combat:1" })
+		expect(response.payload.matches[1].text).toEqual("local damage = 10")
+		controller:Destroy()
+	end)
+
+	it("should treat the pattern plainly unless luaPattern is set", function()
+		local controller = setup()
+
+		local plain = controller.grep({ root = controller.rootPath, pattern = "require(" })
+		local pattern = controller.grep({ root = controller.rootPath, pattern = "^print%(", luaPattern = true })
+
+		expect(getLocations(plain)).toEqual({ "Main:2" })
+		expect(getLocations(pattern)).toEqual({ "Main:1" })
+		controller:Destroy()
+	end)
+
+	it("should keep a pattern's classes when matching case-insensitively", function()
+		local controller = setup()
+
+		local response = controller.grep({ root = controller.rootPath, pattern = "^%S+ DAMAGE", luaPattern = true })
+
+		expect(getLocations(response)).toEqual({ "Combat:1" })
+		controller:Destroy()
+	end)
+
+	it("should stop at the limit and say so", function()
+		local controller = setup()
+
+		local response = controller.grep({ root = controller.rootPath, pattern = "combat", limit = 1 })
+
+		expect(#response.payload.matches).toEqual(1)
+		expect(response.payload.truncated).toEqual(true)
+		controller:Destroy()
+	end)
+
+	it("should refuse an invalid Lua pattern", function()
+		local controller = setup()
+
+		local response = controller.grep({ root = controller.rootPath, pattern = "[", luaPattern = true })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("INVALID_PAYLOAD")
+		controller:Destroy()
+	end)
+end)

package/src/commands/explorer/grep/grep.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from 'vitest';
+import { formatGrepText, grepScriptsHandlerAsync } from './grep.js';
+
+describe('grepScriptsHandlerAsync', () => {
+  it('reports each match as path:line: text', async () => {
+    const session = {
+      grepScriptsAsync: vi.fn().mockResolvedValue({
+        matches: [
+          {
+            path: 'ServerScriptService.Main',
+            className: 'Script',
+            line: 4,
+            text: '\tlocal damage = 10',
+          },
+          {
+            path: 'ServerScriptService.Main',
+            className: 'Script',
+            line: 9,
+            text: 'damage += 1',
+          },
+        ],
+        searched: 12,
+        truncated: false,
+      }),
+    } as any;
+
+    const result = await grepScriptsHandlerAsync(session, {
+      pattern: 'damage',
+      caseSensitive: true,
+    });
+
+    expect(session.grepScriptsAsync).toHaveBeenCalledWith({
+      pattern: 'damage',
+      caseSensitive: true,
+      root: undefined,
+      luaPattern: undefined,
+      limit: undefined,
+    });
+    expect(result.summary).toBe('2 matching line(s) in 1 of 12 scripts');
+
+    const text = formatGrepText(result);
+    expect(text).toContain('ServerScriptService.Main');
+    expect(text).toContain('local damage = 10');
+  });
+});

package/src/commands/explorer/grep/grep.ts

@@ -0,0 +1,93 @@
+/**
+ * `explorer grep` — search the source of every script in Studio.
+ */
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type { GrepMatch } from '../../../server/web-socket-protocol.js';
+
+export interface GrepOptions {
+  pattern: string;
+  root?: string;
+  luaPattern?: boolean;
+  caseSensitive?: boolean;
+  limit?: number;
+}
+
+export interface GrepResult {
+  matches: GrepMatch[];
+  searched: number;
+  /** True when the search stopped at --limit; there may be more. */
+  truncated: boolean;
+  summary: string;
+}
+
+export async function grepScriptsHandlerAsync(
+  session: BridgeSession,
+  options: GrepOptions
+): Promise<GrepResult> {
+  const result = await session.grepScriptsAsync({
+    pattern: options.pattern,
+    root: options.root,
+    luaPattern: options.luaPattern,
+    caseSensitive: options.caseSensitive,
+    limit: options.limit,
+  });
+
+  const scripts = new Set(result.matches.map((m) => m.path)).size;
+  return {
+    ...result,
+    summary: result.truncated
+      ? `First ${result.matches.length} matching lines; raise --limit to see more`
+      : `${result.matches.length} matching line(s) in ${scripts} of ${result.searched} scripts`,
+  };
+}
+
+/** `path:line: text`, like grep. */
+export function formatGrepText(result: GrepResult): string {
+  if (result.matches.length === 0) return 'No matches';
+  const lines = result.matches.map(
+    (m) =>
+      `${OutputHelper.formatHint(m.path)}:${OutputHelper.formatDim(
+        String(m.line)
+      )}: ${m.text.trim()}`
+  );
+  lines.push(OutputHelper.formatDim(result.summary));
+  return lines.join('\n');
+}
+
+export const grepCommand = defineCommand<GrepOptions, GrepResult>({
+  group: 'explorer',
+  name: 'grep',
+  description: 'Search the source of every script for text',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {
+    pattern: arg.positional({
+      description: 'Text to find (plain and case-insensitive by default)',
+    }),
+    luaPattern: arg.flag({
+      description: 'Treat the pattern as a Lua pattern',
+    }),
+    caseSensitive: arg.flag({
+      description: 'Match case',
+      alias: 's',
+    }),
+    root: arg.option({
+      description:
+        'Dot-separated path to search under (default: the whole DataModel)',
+    }),
+    limit: arg.option({
+      description: 'Stop after this many matching lines (default: 200)',
+      type: 'number',
+      alias: 'n',
+    }),
+  },
+  cli: {
+    format: formatGrepText,
+  },
+  handler: async (session, args) => grepScriptsHandlerAsync(session, args),
+});

package/src/commands/explorer/import/import-instances.lua

@@ -0,0 +1,106 @@
+--!strict
+--[=[
+	Action that decodes a base64 binary model (.rbxm), deserializes it with
+	SerializationService, and parents the instances under `parentPath`.
+
+	Request: `{ type: "importInstances", payload: { data, parentPath } }`
+	Response: `{ type: "importInstancesResult", payload: { paths } }`
+
+	@class ImportInstancesAction
+]=]
+
+local ImportInstancesAction = {}
+
+--[=[
+	Registers the `importInstances` handler.
+]=]
+function ImportInstancesAction.register(router: any)
+	router:setResponseType("importInstances", "importInstancesResult")
+	router:register(
+		"importInstances",
+		function(payload: { [string]: any }, _requestId: string, _sessionId: string): { [string]: any }?
+			if type(payload.data) ~= "string" or type(payload.parentPath) ~= "string" then
+				return {
+					success = false,
+					code = "INVALID_PAYLOAD",
+					message = "importInstances needs data and parentPath strings",
+				}
+			end
+
+			local parent = ImportInstancesAction._resolveInstance(payload.parentPath)
+			if not parent then
+				return {
+					success = false,
+					code = "INSTANCE_NOT_FOUND",
+					message = `Instance not found at path: {payload.parentPath}`,
+				}
+			end
+
+			local decodeOk, decoded = pcall(function()
+				return game:GetService("EncodingService"):Base64Decode(buffer.fromstring(payload.data))
+			end)
+			if not decodeOk then
+				return {
+					success = false,
+					code = "DECODE_FAILED",
+					message = `Failed to base64 decode data: {decoded}`,
+				}
+			end
+
+			local deserializeOk, instances = pcall(function()
+				return game:GetService("SerializationService"):DeserializeInstancesAsync(decoded)
+			end)
+			if not deserializeOk then
+				return {
+					success = false,
+					code = "DESERIALIZE_FAILED",
+					message = `Failed to deserialize instances: {instances}`,
+				}
+			end
+
+			local paths = {}
+			for _, instance in instances do
+				instance.Parent = parent
+				table.insert(paths, instance:GetFullName())
+			end
+
+			return {
+				paths = paths,
+			}
+		end
+	)
+end
+
+--[[
+	Walks `path` down from game, falling back to GetService for top-level names
+	that are not children by that name. A leading "game" is optional.
+]]
+function ImportInstancesAction._resolveInstance(path: string): Instance?
+	local parts = string.split(path, ".")
+	local startIndex = if parts[1] == "game" then 2 else 1
+
+	local current: Instance = game
+	for index = startIndex, #parts do
+		local part = parts[index]
+
+		local ok, child = pcall(current.FindFirstChild, current, part)
+		if ok and child then
+			current = child
+			continue
+		end
+
+		if current ~= game then
+			return nil
+		end
+
+		local serviceOk, service = pcall(game.GetService, game, part)
+		if not (serviceOk and service) then
+			return nil
+		end
+		current = service
+	end
+
+	return current
+end
+
+return ImportInstancesAction

package/src/commands/explorer/import/import-instances.spec.lua

@@ -0,0 +1,84 @@
+--!strict
+--[[
+	@class import-instances.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local ImportInstancesAction = require("import-instances")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local router = ActionRouter.new()
+	ImportInstancesAction.register(router)
+
+	local parent = Instance.new("Folder")
+	parent.Name = `ImportInstancesSpec{HttpService:GenerateGUID(false)}`
+	parent.Parent = workspace
+
+	local model = Instance.new("IntValue")
+	model.Name = "Score"
+	model.Value = 42
+	local serialized = game:GetService("SerializationService"):SerializeInstancesAsync({ model })
+	model:Destroy()
+
+	local controller = {
+		parent = parent,
+		parentPath = `Workspace.{parent.Name}`,
+		data = buffer.tostring(game:GetService("EncodingService"):Base64Encode(serialized)),
+		import = function(payload: { [string]: any }): any
+			return router:Dispatch({ type = "importInstances", sessionId = "session-1", payload = payload })
+		end,
+		Destroy = function(_self)
+			parent:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+describe("importInstances", function()
+	it("should parent the deserialized instances under the parent path", function()
+		local controller = setup()
+
+		local response = controller.import({ data = controller.data, parentPath = controller.parentPath })
+
+		expect(response.type).toEqual("importInstancesResult")
+		expect(response.payload.paths).toEqual({ `{controller.parent:GetFullName()}.Score` })
+		expect((controller.parent:FindFirstChild("Score") :: IntValue).Value).toEqual(42)
+
+		controller:Destroy()
+	end)
+
+	it("should fail when the parent path does not resolve", function()
+		local controller = setup()
+
+		local response = controller.import({ data = controller.data, parentPath = "Workspace.DoesNotExist" })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("INSTANCE_NOT_FOUND")
+
+		controller:Destroy()
+	end)
+
+	it("should fail on data that is not a model", function()
+		local controller = setup()
+
+		local response = controller.import({
+			data = buffer.tostring(game:GetService("EncodingService"):Base64Encode(buffer.fromstring("nope"))),
+			parentPath = controller.parentPath,
+		})
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("DESERIALIZE_FAILED")
+
+		controller:Destroy()
+	end)
+end)

package/src/commands/explorer/import/import.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { importInstancesHandlerAsync } from './import.js';
+
+describe('importInstancesHandlerAsync', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    for (const dir of dirs) {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+    dirs.length = 0;
+  });
+
+  async function writeModelAsync(contents: string): Promise<string> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'sb-import-'));
+    dirs.push(dir);
+    const file = path.join(dir, 'model.rbxm');
+    await fs.writeFile(file, contents);
+    return file;
+  }
+
+  function createSession() {
+    return {
+      importInstancesAsync: vi
+        .fn()
+        .mockResolvedValue({ paths: ['Workspace.Map'] }),
+    } as any;
+  }
+
+  it('sends the file as base64 under Workspace by default', async () => {
+    const file = await writeModelAsync('<roblox!model');
+    const session = createSession();
+
+    const result = await importInstancesHandlerAsync(session, { file });
+
+    expect(session.importInstancesAsync).toHaveBeenCalledWith(
+      Buffer.from('<roblox!model').toString('base64'),
+      'Workspace'
+    );
+    expect(result.paths).toEqual(['Workspace.Map']);
+  });
+
+  it('uses the given parent', async () => {
+    const file = await writeModelAsync('<roblox!model');
+    const session = createSession();
+
+    await importInstancesHandlerAsync(session, {
+      file,
+      parent: 'ServerStorage',
+    });
+
+    expect(session.importInstancesAsync).toHaveBeenCalledWith(
+      expect.any(String),
+      'ServerStorage'
+    );
+  });
+});

package/src/commands/explorer/import/import.ts

@@ -0,0 +1,66 @@
+/**
+ * `explorer import` — insert a binary model (.rbxm) into a connected Studio
+ * session.
+ */
+
+import * as fs from 'fs/promises';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+
+export interface ImportResult {
+  paths: string[];
+  summary: string;
+}
+
+export interface ImportOptions {
+  file: string;
+  parent?: string;
+}
+
+interface ImportArgs {
+  file: string;
+  parent?: string;
+}
+
+export async function importInstancesHandlerAsync(
+  session: BridgeSession,
+  options: ImportOptions
+): Promise<ImportResult> {
+  const data = await fs.readFile(options.file);
+  const result = await session.importInstancesAsync(
+    data.toString('base64'),
+    options.parent ?? 'Workspace'
+  );
+
+  return {
+    paths: result.paths,
+    summary: `Imported ${result.paths.length} instance(s): ${result.paths.join(
+      ', '
+    )}`,
+  };
+}
+
+export const importCommand = defineCommand<ImportArgs, ImportResult>({
+  group: 'explorer',
+  name: 'import',
+  description: 'Insert a binary model (.rbxm) into Studio',
+  category: 'execution',
+  safety: 'mutate',
+  changesDataModel: true,
+  scope: 'session',
+  args: {
+    file: arg.positional({
+      description: 'Path to a .rbxm file',
+    }),
+    parent: arg.option({
+      description:
+        'Dot-separated path of the parent instance (default: Workspace)',
+    }),
+  },
+  handler: async (session, args) =>
+    importInstancesHandlerAsync(session, {
+      file: args.file,
+      parent: args.parent,
+    }),
+});