@el4cteo/rbx-studio-mcp 0.7.1 → 0.7.5

package/scripts/test-plugin.mjs

@@ -1,85 +1,103 @@
-/**
- * Runs the plugin's unit tests outside Roblox Studio.
- *
- * The modules under test import their dependencies with `require(script.Parent.X)`,
- * which only resolves inside Studio. Rather than mock the engine, this bundles
- * the real module source with a stub for its one dependency and runs the result
- * through the standalone Luau interpreter, so the tests exercise the shipped
- * code rather than a copy of it.
- *
- * Needs the `luau` binary on PATH, in ./tools, or named by the LUAU variable.
- * Get one from https://github.com/luau-lang/luau/releases.
- *
- * Usage: node scripts/test-plugin.mjs
- */
-import { spawnSync } from "node:child_process";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { locateLuau, missingLuau } from "./locate-luau.mjs";
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const luau = locateLuau("LUAU", ["luau.exe", "luau"]);
-if (luau === null) {
-  process.stderr.write(missingLuau("luau", "LUAU"));
-  process.exit(1);
-}
-
-/** Modules under test, paired with the test file that exercises each. */
-const suites = [
-  { module: "plugin/src/TextEdit.luau", test: "tests/textedit.luau" },
-  { module: "plugin/src/Format.luau", test: "tests/format.luau" },
-];
-
-/**
- * The stub stands in for Dispatch. It has to raise the same structured table the
- * real one does, because the tests assert on `code` -- that contract is what the
- * MCP server turns into an actionable error for the agent.
- */
-const DISPATCH_STUB = `local Dispatch = {}
-function Dispatch.fail(code, message, hint)
-\terror({ code = code, message = message, hint = hint }, 0)
-end
-`;
-
-/** Drops the module's own requires; the stub above is already in scope. */
-const stripRequires = (source) =>
-  source.replace(/^local \w+ = require\(script[^\n]*\n/gm, "");
-
-let failures = 0;
-
-for (const suite of suites) {
-  const moduleSource = stripRequires(readFileSync(join(root, suite.module), "utf8"));
-  const testSource = readFileSync(join(root, suite.test), "utf8");
-
-  const bundle = [
-    DISPATCH_STUB,
-    "local Module = (function()",
-    moduleSource,
-    "end)()",
-    "local run = function(...)",
-    testSource,
-    "end",
-    "run(Module)",
-    "",
-  ].join("\n");
-
-  const bundlePath = join(mkdtempSync(join(tmpdir(), "studio-mcp-test-")), "bundle.luau");
-  writeFileSync(bundlePath, bundle, "utf8");
-
-  const result = spawnSync(luau, [bundlePath], { stdio: "inherit" });
-  if (result.error) {
-    process.stderr.write(
-      `could not run '${luau}': ${result.error.message}\n` +
-        "Set LUAU to the path of a Luau interpreter.\n",
-    );
-    process.exit(1);
-  }
-  if (result.status !== 0) {
-    process.stderr.write(`FAIL ${suite.test}\n`);
-    failures += 1;
-  }
-}
-
-process.exit(failures === 0 ? 0 : 1);
+/**
+ * Runs the plugin's unit tests outside Roblox Studio.
+ *
+ * The modules under test import their dependencies with `require(script.Parent.X)`,
+ * which only resolves inside Studio. Rather than mock the engine, this bundles
+ * the real module source with a stub for its one dependency and runs the result
+ * through the standalone Luau interpreter, so the tests exercise the shipped
+ * code rather than a copy of it.
+ *
+ * Needs the `luau` binary on PATH, in ./tools, or named by the LUAU variable.
+ * Get one from https://github.com/luau-lang/luau/releases.
+ *
+ * Usage: node scripts/test-plugin.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const luau = locateLuau("LUAU", ["luau.exe", "luau"]);
+if (luau === null) {
+  process.stderr.write(missingLuau("luau", "LUAU"));
+  process.exit(1);
+}
+
+/** Modules under test, paired with the test file that exercises each. */
+const suites = [
+  { module: "plugin/src/handlers/Playtest.luau", test: "tests/playtests.luau", prelude: "tests/playtests-stub.luau" },
+  { module: "plugin/src/Commands.luau", test: "tests/playtests-commands.luau", prelude: "tests/playtests-stub.luau", dependency: "plugin/src/handlers/Playtest.luau" },
+  { module: "plugin/src/RemoteTrace.luau", test: "tests/remote-trace.luau", prelude: "tests/remote-trace-stub.luau" },
+  { module: "plugin/src/ExecRuntime.luau", test: "tests/exec-runtime.luau", prelude: "tests/exec-runtime-stub.luau" },
+  { module: "plugin/src/ClientRelay.luau", test: "tests/client-relay.luau", prelude: "tests/client-relay-stub.luau" },
+  { module: "plugin/src/TextEdit.luau", test: "tests/textedit.luau" },
+  { module: "plugin/src/Format.luau", test: "tests/format.luau" },
+];
+
+/**
+ * The stub stands in for Dispatch. It has to raise the same structured table the
+ * real one does, because the tests assert on `code` -- that contract is what the
+ * MCP server turns into an actionable error for the agent.
+ */
+const DISPATCH_STUB = `local Dispatch = {}
+function Dispatch.fail(code, message, hint)
+\terror({ code = code, message = message, hint = hint }, 0)
+end
+`;
+
+/** Drops the module's own requires; the stub above is already in scope. */
+const stripRequires = (source) =>
+  source.replace(/^local \w+ = require\(script[^\n]*\n/gm, "");
+
+let failures = 0;
+
+for (const suite of suites) {
+  const moduleSource = stripRequires(readFileSync(join(root, suite.module), "utf8"));
+  const testSource = readFileSync(join(root, suite.test), "utf8");
+
+  const bundle = [
+    DISPATCH_STUB,
+    suite.prelude ? readFileSync(join(root, suite.prelude), "utf8") : "",
+    suite.dependency ? `local Playtest = (function()\n${stripRequires(readFileSync(join(root, suite.dependency), "utf8"))}\nend)()` : "",
+    "local function loadModule()",
+    moduleSource,
+    "end",
+    "local Module = loadModule()",
+    "local run = function(...)",
+    testSource,
+    "end",
+    "run(Module)",
+    "",
+  ].join("\n");
+
+  const bundlePath = join(mkdtempSync(join(tmpdir(), "studio-mcp-test-")), "bundle.luau");
+  writeFileSync(bundlePath, bundle, "utf8");
+
+  const result = spawnSync(luau, [bundlePath], { stdio: "inherit" });
+  if (result.error) {
+    process.stderr.write(
+      `could not run '${luau}': ${result.error.message}\n` +
+        "Set LUAU to the path of a Luau interpreter.\n",
+    );
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.stderr.write(`FAIL ${suite.test}\n`);
+    failures += 1;
+  }
+}
+
+// Embedded LocalScript bodies must compile too; the module compiler sees strings.
+for (const name of ["Exec", "Input", "Debug"]) {
+  const source = readFileSync(join(root, `plugin/src/handlers/${name}.luau`), "utf8");
+  const relay = source.match(/\[==\[([\s\S]*?)\]==\]/)?.[1];
+  if (!relay) throw new Error(`Missing ${name} relay`);
+  const path = join(mkdtempSync(join(tmpdir(), "studio-mcp-relay-")), "compile.luau");
+  writeFileSync(path, `local chunk, err = loadstring(${JSON.stringify(relay)})\nassert(chunk, err)\n`);
+  if (spawnSync(luau, [path], {stdio:"inherit"}).status !== 0) failures += 1;
+}
+
+process.exit(failures === 0 ? 0 : 1);

package/scripts/test-tools.mjs

@@ -0,0 +1,151 @@
+/**
+ * Offline checks for tool output shaping that needs no Studio.
+ *
+ * Usage: node scripts/test-tools.mjs
+ */
+import assert from "node:assert/strict";
+import { CHARACTER_LIMIT } from "../dist/lib/format.js";
+import { clipListing, numbered } from "../dist/tools/scripts.js";
+
+const item = (path, lineCount) => ({ path, className: "ModuleScript", lineCount, startLine: 1, source: "" });
+const listing = (path, lines) =>
+  `${path}  (ModuleScript, ${lines} lines)\n` +
+  numbered(Array.from({ length: lines }, (_, index) => `local v${index} = ${index}`).join("\n"), 1);
+
+// Small reads pass through untouched.
+{
+  const blocks = [listing("A", 3)];
+  assert.equal(clipListing(blocks, [item("A", 3)], null), blocks[0]);
+}
+
+// A big read is cut on a whole line and names the exact next window.
+{
+  const out = clipListing([listing("Big", 5000), listing("After", 5)], [item("Big", 5000), item("After", 5)], null);
+  assert.ok(out.length <= CHARACTER_LIMIT, "fits the limit");
+  const match = /Big stops at line (\d+) of 5000\. Continue with \{ path: "Big", startLine: (\d+) \}/.exec(out);
+  assert.ok(match, "names where to continue");
+  assert.equal(Number(match[2]), Number(match[1]) + 1);
+  const lastShown = out.split("\n\n[clipped")[0].split("\n").pop();
+  assert.match(lastShown, new RegExp(`^\s*${match[1]}│ local v${Number(match[1]) - 1} = ${Number(match[1]) - 1}$`), "last line is whole");
+  assert.match(out, /1 more script\(s\) after it were not shown/);
+}
+
+// Failures are never the part that gets clipped away.
+{
+  const out = clipListing([listing("Big", 5000)], [item("Big", 5000)], "Could not read 1 path(s):\n  - Nope");
+  assert.ok(out.startsWith("Could not read 1 path(s)"));
+}
+
+process.stdout.write("tools: ok\n");
+
+// Exercise the public schemas and forwarding through the real tool handlers.
+const { z } = await import("zod");
+const { registerExecTools } = await import("../dist/tools/exec.js");
+const { registerInputTools } = await import("../dist/tools/input.js");
+const registered = new Map();
+const calls = [];
+const context = {
+  server: { registerTool(name, spec, handler) { registered.set(name, { spec, handler }); } },
+  bridge: { async call(op, params, options) {
+    calls.push({op, params, options});
+    return op === "exec.run" ? {ok:true,returned:["nil",{answer:42}],output:[],milliseconds:1} : {delivered:true,steps:1,player:"Alice"};
+  } },
+};
+registerExecTools(context);
+registerInputTools(context);
+const execute = registered.get("execute_luau");
+const parsed = z.object(execute.spec.inputSchema).parse({source:"return nil",target:"client",player:"Alice",timeoutSeconds:2});
+await execute.handler(parsed);
+assert.equal(calls.at(-1).params.target, "client");
+assert.equal(calls.at(-1).params.player, "Alice");
+assert.equal(calls.at(-1).options.timeoutMs, 12000);
+await execute.handler(z.object(execute.spec.inputSchema).parse({source:"return 1"}));
+assert.equal(calls.at(-1).params.target, "studio");
+assert.equal(calls.at(-1).options.timeoutMs, 60000);
+const input = registered.get("input");
+for (const step of [{kind:"click",target:"PlayerGui.HUD.BuyButton"},{kind:"text",target:"PlayerGui.HUD.NameBox",text:"hello"},{kind:"click",x:100,y:200}]) {
+ await input.handler(z.object(input.spec.inputSchema).parse({steps:[step]}));
+ assert.deepEqual(calls.at(-1).params.steps[0], step);
+}
+assert.deepEqual([...registered.keys()].sort(), ["execute_luau", "input", "viewport"]);
+process.stdout.write("client tool schemas: ok\n");
+
+const { registerDebugTools } = await import("../dist/tools/debug.js");
+registerDebugTools(context);
+const debug = registered.get("debug");
+const remoteArgs = z.object(debug.spec.inputSchema).parse({op:"remotes",path:"ReplicatedStorage",player:"Alice",seconds:3});
+await debug.handler(remoteArgs);
+assert.equal(calls.at(-1).op, "debug.remotes");
+assert.deepEqual(calls.at(-1).params, {path:"ReplicatedStorage",player:"Alice",seconds:3});
+assert.equal(calls.at(-1).options.timeoutMs, 18000);
+assert.throws(() => z.object(debug.spec.inputSchema).parse({op:"remotes",seconds:16}));
+assert.deepEqual([...registered.keys()].sort(), ["debug", "execute_luau", "input", "viewport"]);
+process.stdout.write("remote trace schema: ok\n");
+
+const { registerPlaytestTools } = await import("../dist/tools/playtest.js");
+registerPlaytestTools(context);
+const playtest = registered.get("playtest");
+for (const guidance of ["AGENTS.md", "CLAUDE.md", "user instructions", "project guidance", "even when ON", "Do not bypass"]) {
+ assert.ok(playtest.spec.description.includes(guidance), `playtest guidance preserves ${guidance}`);
+}
+const normalCall = context.bridge.call;
+context.bridge.call = async (op, params) => {
+ if (["play", "run", "multiplayer"].includes(params.op)) {
+  const { ToolError } = await import("../dist/lib/errors.js");
+  throw new ToolError("PLAYTEST_DISABLED", "Playtests are disabled by the user.", "Do not start or simulate a playtest. Continue using edit-mode tools and static inspection where possible.\nRun `playtests on` in the Studio MCP panel to re-enable playtesting.");
+ }
+ return {changed:false,state:{playtestsAllowed:false}};
+};
+for (const op of ["play", "run", "multiplayer"]) {
+ const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op}));
+ assert.equal(result.isError, true);
+ assert.match(result.content[0].text, /PLAYTEST_DISABLED/);
+ assert.match(result.content[0].text, /playtests on/);
+}
+const stateResult = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:"state"}));
+assert.ok(!stateResult.isError);
+context.bridge.call = normalCall;
+process.stdout.write("playtest lock errors and instruction precedence: ok\n");
+
+// OFF affects simulation starts, not the ordinary edit-mode tool paths.
+const { registerDiscoverTools } = await import("../dist/tools/discover.js");
+const { registerScriptTools } = await import("../dist/tools/scripts.js");
+const { registerScreenshotTools } = await import("../dist/tools/screenshot.js");
+registerDiscoverTools(context);
+registerScriptTools(context);
+registerScreenshotTools(context);
+const editOps = [];
+context.bridge.sessions = async () => ({list:[{studioId:"edit",context:"edit"}],activeId:"edit"});
+context.bridge.call = async (op, params) => {
+ editOps.push(op);
+ if (op === "playtest.control") {
+  if (["play", "run", "multiplayer"].includes(params.op)) throw new Error("PLAYTEST_DISABLED");
+  return {changed:false,state:{playtestsAllowed:false}};
+ }
+ const results = {
+  "exec.run": {ok:true,returned:[42],output:[],milliseconds:1},
+  "discover.tree": {items:[],total:0,offset:0},
+  "discover.inspect": {items:[],failures:[]},
+  "script.read": {items:[],failures:[]},
+  "viewport.ui": {findings:[],checked:0,hidden:0,root:"StarterGui",screen:"800x600"},
+  "capture.screenshot": {encoding:"png",data:"AA==",width:1,height:1,sourceWidth:1,sourceHeight:1,bytes:1,context:"edit"},
+ };
+ assert.ok(op in results, `unexpected edit-mode operation ${op}`);
+ return results[op];
+};
+for (const [name, args, expected] of [
+ ["execute_luau",{source:"return 42",target:"studio"},"exec.run"],
+ ["tree",{},"discover.tree"],
+ ["inspect",{paths:["Workspace"],detail:"concise"},"discover.inspect"],
+ ["script_read",{paths:["ServerScriptService.Example"]},"script.read"],
+ ["viewport",{op:"ui",path:"StarterGui"},"viewport.ui"],
+ ["screenshot",{},"capture.screenshot"],
+]) {
+ const tool = registered.get(name);
+ const result = await tool.handler(z.object(tool.spec.inputSchema).parse(args));
+ assert.ok(!result.isError, `${name} remains usable with playtests OFF: ${JSON.stringify(result)}`);
+ assert.equal(editOps.at(-1),expected);
+}
+assert.ok(!editOps.includes("playtest.control"), "edit-mode tools never start or probe a simulation");
+context.bridge.call = normalCall;
+process.stdout.write("playtest lock leaves edit-mode tools available: ok\n");

package/scripts/test-transport.mjs

@@ -1,58 +1,71 @@
-/**
- * Exercises the plugin's SSE frame parser outside Studio.
- *
- * `Transport.luau` cannot be loaded whole by the interpreter -- it reaches for
- * HttpService at module scope -- and `parseFrames` is a local, so neither the
- * existing bundling harness nor a plain require can get at it. It is lifted out
- * of the real file by name instead, so this cannot quietly drift from what ships:
- * rename or delete the function and the extraction fails the test run.
- *
- * The bug it covers cost a session to find and would have been invisible in
- * review. Two SSE writes in the same tick arrive as one chunk, and the old
- * parser JSON-decoded the whole chunk, so BOTH frames were dropped. It showed up
- * as a client-count badge that would not come back down; the part that mattered
- * is that a command sharing a chunk with a keepalive would have vanished the
- * same way, losing a tool call with no error at either end.
- *
- * Usage: node scripts/test-transport.mjs
- */
-import { spawnSync } from "node:child_process";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { locateLuau, missingLuau } from "./locate-luau.mjs";
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const luau = locateLuau("LUAU", ["luau.exe", "luau"]);
-if (luau === null) {
-  process.stderr.write(missingLuau("luau", "LUAU"));
-  process.exit(1);
-}
-
-/** Lifts one top-level `local function` out of a module, body and all. */
-function extractFunction(source, name) {
-  // Normalised first: the plugin sources are CRLF and every anchor here is LF.
-  const text = source.split(String.fromCharCode(13, 10)).join(String.fromCharCode(10));
-  const opener = `local function ${name}(`;
-  const start = text.indexOf(opener);
-  if (start === -1) throw new Error(`${name} is not in Transport.luau any more`);
-  const closer = String.fromCharCode(10) + 'end' + String.fromCharCode(10);
-  const end = text.indexOf(closer, start);
-  if (end === -1) throw new Error(`could not find the end of ${name}`);
-  return text.slice(start, end + closer.length).replace(opener, `function ${name}(`);
-}
-const transport = readFileSync(join(root, "plugin", "src", "Transport.luau"), "utf8");
-const stub = readFileSync(join(root, "tests", "jsonstub.luau"), "utf8").replace(/^return Net$/m, "");
-const cases = readFileSync(join(root, "tests", "sseframes.luau"), "utf8");
-
-const bundle = [stub, extractFunction(transport, "parseFrames"), cases].join("\n");
-const bundlePath = join(mkdtempSync(join(tmpdir(), "studio-mcp-sse-")), "bundle.luau");
-writeFileSync(bundlePath, bundle, "utf8");
-
-const result = spawnSync(luau, [bundlePath], { stdio: "inherit" });
-if (result.error) {
-  process.stderr.write(`could not run '${luau}': ${result.error.message}\n`);
-  process.exit(1);
-}
-process.exit(result.status ?? 1);
+/**
+ * Exercises the plugin's SSE frame parser outside Studio.
+ *
+ * `Transport.luau` cannot be loaded whole by the interpreter -- it reaches for
+ * HttpService at module scope -- and `parseFrames` is a local, so neither the
+ * existing bundling harness nor a plain require can get at it. It is lifted out
+ * of the real file by name instead, so this cannot quietly drift from what ships:
+ * rename or delete the function and the extraction fails the test run.
+ *
+ * The bug it covers cost a session to find and would have been invisible in
+ * review. Two SSE writes in the same tick arrive as one chunk, and the old
+ * parser JSON-decoded the whole chunk, so BOTH frames were dropped. It showed up
+ * as a client-count badge that would not come back down; the part that mattered
+ * is that a command sharing a chunk with a keepalive would have vanished the
+ * same way, losing a tool call with no error at either end.
+ *
+ * Usage: node scripts/test-transport.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const luau = locateLuau("LUAU", ["luau.exe", "luau"]);
+if (luau === null) {
+  process.stderr.write(missingLuau("luau", "LUAU"));
+  process.exit(1);
+}
+
+/** Lifts one top-level `local function` out of a module, body and all. */
+function extractFunction(source, name) {
+  // Normalised first: the plugin sources are CRLF and every anchor here is LF.
+  const text = source.split(String.fromCharCode(13, 10)).join(String.fromCharCode(10));
+  const opener = `local function ${name}(`;
+  const start = text.indexOf(opener);
+  if (start === -1) throw new Error(`${name} is not in Transport.luau any more`);
+  const closer = String.fromCharCode(10) + 'end' + String.fromCharCode(10);
+  const end = text.indexOf(closer, start);
+  if (end === -1) throw new Error(`could not find the end of ${name}`);
+  return text.slice(start, end + closer.length).replace(opener, `function ${name}(`);
+}
+const transport = readFileSync(join(root, "plugin", "src", "Transport.luau"), "utf8");
+const stub = readFileSync(join(root, "tests", "jsonstub.luau"), "utf8").replace(/^return Net$/m, "");
+const cases = readFileSync(join(root, "tests", "sseframes.luau"), "utf8");
+
+/** Lifts one top-level `local NAME = ...` constant, so a lifted function can see it. */
+function extractConstant(source, name) {
+  const match = new RegExp(`^local ${name}\\b[^\\r\\n]*`, "m").exec(source);
+  if (match === null) throw new Error(`${name} is not in Transport.luau any more`);
+  return match[0];
+}
+
+const bundle = [
+  stub,
+  extractConstant(transport, "MAX_PENDING"),
+  extractFunction(transport, "parseFrames"),
+  extractFunction(transport, "frameReader"),
+  cases,
+].join("\n");
+const bundlePath = join(mkdtempSync(join(tmpdir(), "studio-mcp-sse-")), "bundle.luau");
+writeFileSync(bundlePath, bundle, "utf8");
+
+const result = spawnSync(luau, [bundlePath], { stdio: "inherit" });
+if (result.error) {
+  process.stderr.write(`could not run '${luau}': ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);