@el4cteo/rbx-studio-mcp 0.7.0 → 0.7.2

package/scripts/test-bridge.mjs

@@ -322,6 +322,46 @@ function twoStudios() {
   second.destroy();
   await settle();
   assert.equal(await count(), 0, "a stream that dies without a goodbye is dropped");
+
+  // A command far bigger than one socket read goes down the stream as ONE
+  // event, and its answer comes back. The plugin half of this -- joining the
+  // reads back together -- is covered by the frameReader cases in
+  // tests/sseframes.luau; this pins the bridge half over real sockets.
+  const source = "local x = 1\n".repeat(100_000);
+  const events = [];
+  const plugin = await new Promise((resolve) => {
+    const req = request(
+      { host: "127.0.0.1", port, path: "/events", method: "POST", headers: { "x-roblox-studio-mcp": "test" } },
+      (res) => {
+        let pending = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          pending += chunk;
+          let cut;
+          while ((cut = pending.indexOf("\n\n")) !== -1) {
+            const block = pending.slice(0, cut);
+            pending = pending.slice(cut + 2);
+            if (!block.startsWith("data: ")) continue;
+            const frame = JSON.parse(block.slice(6));
+            if (typeof frame.id !== "string") continue;
+            events.push(frame);
+            void fetch(`http://127.0.0.1:${port}/result?studioId=big`, {
+              method: "POST",
+              headers: { "x-roblox-studio-mcp": "test" },
+              body: JSON.stringify({ id: frame.id, ok: true, data: { length: frame.params.source.length } }),
+            });
+          }
+        });
+        resolve(req);
+      },
+    );
+    req.end(JSON.stringify({ studioId: "big", placeName: "p", placeId: 1 }));
+  });
+  const answer = await server.bridge.call("script.create", { source }, { studioId: "big" });
+  assert.equal(answer.length, source.length, "a 1.2MB command arrives whole and is answered");
+  assert.equal(events.length, 1, "as exactly one event");
+  plugin.destroy();
+
   await server.close();
 }
 

package/scripts/test-failover.mjs

@@ -20,7 +20,15 @@ import { startBridgeServer } from "../dist/bridge/server.js";
 import { CLIENT_HEADER } from "../dist/lib/protocol.js";
 import { PEER_HEADER } from "../dist/bridge/remote.js";
 
-const PORT = 44799;
+// A free port, not a fixed one: a fixed port fails the whole suite whenever
+// anything else on the machine happens to hold it.
+const PORT = await new Promise((resolve, reject) => {
+  const probe = createServer().listen(0, "127.0.0.1", () => {
+    const { port } = probe.address();
+    probe.close(() => resolve(port));
+  });
+  probe.once("error", reject);
+});
 
 /** Waits for `check` to hold, or gives up loudly rather than hanging the suite. */
 async function until(check, what, timeoutMs = 20_000) {
@@ -133,102 +141,102 @@ function handshake(port, studioId) {
   await owner.close();
 }
 
-// POST /hello carries the panel's spawned marker all the way to the roster.
-//
-// The shipped bug: every layer marked the agent the panel starts -- the spawn's
-// environment, the MCP config handed to the agent, the hello body -- and this
-// route typed the body with three fields and dropped the fourth. So the panel
-// said "2 MCP clients connected" on every prompt and kept a stopped agent in
-// `clients` until the stale sweep. Tested at the route, because the route is
-// the layer that was wrong while the bridge underneath it was right.
-{
-  const owner = await startBridgeServer({ port: PORT });
-
-  const hello = async (id, body) => {
-    const sent = await fetch(`http://127.0.0.1:${PORT}/hello`, {
-      method: "POST",
-      headers: {
-        [CLIENT_HEADER]: "test",
-        [PEER_HEADER]: id,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
-    });
-    return (await sent.json()).clients;
-  };
-
-  const alone = await hello("a-stranger", { name: "codex", version: "1", pid: 1 });
-  const withAgent = await hello("panel-agent", {
-    name: "claude-code",
-    version: "1",
-    pid: 2,
-    spawned: true,
-  });
-  assert.equal(withAgent, alone, "an agent the panel started is not another client");
-  // A second stranger does count, or the filter would be hiding everyone.
-  const withStranger = await hello("another-stranger", { name: "opencode", pid: 3 });
-  assert.equal(withStranger, alone + 1, "a client nobody asked for still counts");
-
-  // A keepalive that says nothing must not erase what the first hello said, and
-  // must not re-announce the client as if it had just arrived.
-  assert.equal(
-    await hello("a-stranger", { pid: 1 }),
-    withStranger,
-    "a nameless keepalive is not a new client",
-  );
-
-  await owner.close();
-}
-
-// An owner that dies WHILE answering is still OWNER_GONE, not a raw Node error.
-//
-// The shipped bug: only the fetch was guarded, so a socket cut after the
-// headers threw "TypeError: fetch failed / SocketError: other side closed"
-// straight past the catch. It surfaced right under the takeover notice, which
-// is the exact moment a handover cuts a live response.
-//
-// The fake owner declares a Content-Length it never delivers, then hangs up.
-// That distinction is the whole test: a socket destroyed BEFORE the headers
-// makes Node reject the fetch itself, which the old code already caught -- the
-// bug only shows when the reply has started and stops halfway. Two earlier
-// versions of this test cut the socket too early, passed with the bug present,
-// and proved nothing.
-{
-  const halfDead = createServer((req, res) => {
-    if (req.url === "/identity") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ server: "roblox-studio-mcp", protocolVersion: 1, pid: 1 }));
-      return;
-    }
-    res.writeHead(200, { "Content-Type": "application/json", "Content-Length": "5000" });
-    res.write('{"ok":true,"data":"' + "x".repeat(100));
-    setTimeout(() => res.socket.destroy(), 150);
-  });
-  await new Promise((resolve) => halfDead.listen(PORT, "127.0.0.1", resolve));
-
-  const peer = await startBridgeServer({ port: PORT });
-  assert.equal(peer.owner, false, "the peer proxies to whatever holds the port");
-
-  let raised;
-  try {
-    await peer.bridge.call("studio.status", {});
-  } catch (cause) {
-    raised = cause;
-  }
-
-  assert.ok(raised, "a truncated answer must not resolve as success");
-  assert.equal(
-    raised.code,
-    "OWNER_GONE",
-    `a body cut short is the owner going away, not a raw ${raised?.name}`,
-  );
-  assert.ok(
-    /try the call again/.test(raised.hint ?? ""),
-    "and says what to do about it, which a raw socket error never does",
-  );
-
-  await peer.close();
-  await new Promise((resolve) => halfDead.close(resolve));
-}
-
+// POST /hello carries the panel's spawned marker all the way to the roster.
+//
+// The shipped bug: every layer marked the agent the panel starts -- the spawn's
+// environment, the MCP config handed to the agent, the hello body -- and this
+// route typed the body with three fields and dropped the fourth. So the panel
+// said "2 MCP clients connected" on every prompt and kept a stopped agent in
+// `clients` until the stale sweep. Tested at the route, because the route is
+// the layer that was wrong while the bridge underneath it was right.
+{
+  const owner = await startBridgeServer({ port: PORT });
+
+  const hello = async (id, body) => {
+    const sent = await fetch(`http://127.0.0.1:${PORT}/hello`, {
+      method: "POST",
+      headers: {
+        [CLIENT_HEADER]: "test",
+        [PEER_HEADER]: id,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+    return (await sent.json()).clients;
+  };
+
+  const alone = await hello("a-stranger", { name: "codex", version: "1", pid: 1 });
+  const withAgent = await hello("panel-agent", {
+    name: "claude-code",
+    version: "1",
+    pid: 2,
+    spawned: true,
+  });
+  assert.equal(withAgent, alone, "an agent the panel started is not another client");
+  // A second stranger does count, or the filter would be hiding everyone.
+  const withStranger = await hello("another-stranger", { name: "opencode", pid: 3 });
+  assert.equal(withStranger, alone + 1, "a client nobody asked for still counts");
+
+  // A keepalive that says nothing must not erase what the first hello said, and
+  // must not re-announce the client as if it had just arrived.
+  assert.equal(
+    await hello("a-stranger", { pid: 1 }),
+    withStranger,
+    "a nameless keepalive is not a new client",
+  );
+
+  await owner.close();
+}
+
+// An owner that dies WHILE answering is still OWNER_GONE, not a raw Node error.
+//
+// The shipped bug: only the fetch was guarded, so a socket cut after the
+// headers threw "TypeError: fetch failed / SocketError: other side closed"
+// straight past the catch. It surfaced right under the takeover notice, which
+// is the exact moment a handover cuts a live response.
+//
+// The fake owner declares a Content-Length it never delivers, then hangs up.
+// That distinction is the whole test: a socket destroyed BEFORE the headers
+// makes Node reject the fetch itself, which the old code already caught -- the
+// bug only shows when the reply has started and stops halfway. Two earlier
+// versions of this test cut the socket too early, passed with the bug present,
+// and proved nothing.
+{
+  const halfDead = createServer((req, res) => {
+    if (req.url === "/identity") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ server: "roblox-studio-mcp", protocolVersion: 1, pid: 1 }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json", "Content-Length": "5000" });
+    res.write('{"ok":true,"data":"' + "x".repeat(100));
+    setTimeout(() => res.socket.destroy(), 150);
+  });
+  await new Promise((resolve) => halfDead.listen(PORT, "127.0.0.1", resolve));
+
+  const peer = await startBridgeServer({ port: PORT });
+  assert.equal(peer.owner, false, "the peer proxies to whatever holds the port");
+
+  let raised;
+  try {
+    await peer.bridge.call("studio.status", {});
+  } catch (cause) {
+    raised = cause;
+  }
+
+  assert.ok(raised, "a truncated answer must not resolve as success");
+  assert.equal(
+    raised.code,
+    "OWNER_GONE",
+    `a body cut short is the owner going away, not a raw ${raised?.name}`,
+  );
+  assert.ok(
+    /try the call again/.test(raised.hint ?? ""),
+    "and says what to do about it, which a raw socket error never does",
+  );
+
+  await peer.close();
+  await new Promise((resolve) => halfDead.close(resolve));
+}
+
 process.stdout.write("failover: ok\n");

package/scripts/test-live.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Drives a real, connected Studio through the running bridge and checks the
+ * paths no fake can: big payloads over the actual stream, and scripts that
+ * survive a create -> read -> edit -> delete round trip.
+ *
+ * Not part of `npm test`, because it needs Studio open with the plugin. It
+ * exists because the worst transport bug this project had -- any command the
+ * stream delivered in more than one piece was dropped, so a big `script_create`
+ * timed out -- passed every offline test and only showed up against Studio.
+ *
+ * Everything it makes is named `__mcp_live_*` under ServerScriptService and is
+ * deleted before it exits, pass or fail.
+ *
+ * Usage: node scripts/test-live.mjs [--port 44755] [--sizes 1000,16000,64000,256000]
+ */
+import { expectedPluginBuildId } from "../dist/lib/pluginbuild.js";
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? fallback : args[at + 1];
+};
+const port = Number.parseInt(flag("port", "44755"), 10);
+const sizes = flag("sizes", "1000,16000,64000,256000").split(",").map(Number);
+const base = `http://127.0.0.1:${port}`;
+const HEADERS = {
+  "x-roblox-studio-mcp": "test-live",
+  "x-roblox-studio-mcp-peer": `test-live-${process.pid}`,
+  "content-type": "application/json",
+};
+const PREFIX = "__mcp_live_";
+
+async function call(op, params, timeoutMs = 20_000) {
+  const response = await fetch(`${base}/call`, {
+    method: "POST",
+    headers: HEADERS,
+    body: JSON.stringify({ op, params, timeoutMs }),
+  });
+  const body = await response.json();
+  if (!body.ok) throw new Error(`${op}: [${body.error?.code}] ${body.error?.message}`);
+  return body.data;
+}
+
+/** Luau source of about `size` bytes, with quotes and non-ASCII so escaping is exercised. */
+function sourceOf(size) {
+  const lines = [];
+  let length = 0;
+  for (let index = 0; length < size; index += 1) {
+    const line = `local value${index} = "line ${index}: \\"quoted\\" ünïcode ✓"`;
+    lines.push(line);
+    length += line.length + 1;
+  }
+  return lines.join("\n");
+}
+
+let sessions;
+try {
+  sessions = await (await fetch(`${base}/sessions`, { headers: HEADERS })).json();
+} catch {
+  process.stderr.write(`Nothing is listening on port ${port}. Start the MCP server and open Studio.\n`);
+  process.exit(1);
+}
+const studio = sessions.list[0];
+if (studio === undefined) {
+  process.stderr.write("The bridge is up but no Studio is connected.\n");
+  process.exit(1);
+}
+if (studio.buildId !== expectedPluginBuildId()) {
+  process.stderr.write(
+    `warning: Studio runs plugin build ${studio.buildId}, this checkout is ` +
+      `${expectedPluginBuildId()}. Results describe the plugin Studio has loaded.\n`,
+  );
+}
+process.stdout.write(`Studio: ${studio.placeName} (${studio.transport})\n`);
+
+const created = [];
+let failures = 0;
+const check = (ok, what) => {
+  process.stdout.write(`${ok ? "ok  " : "FAIL"}  ${what}\n`);
+  if (!ok) failures += 1;
+};
+
+try {
+  for (const size of sizes) {
+    const name = `${PREFIX}${size}`;
+    const source = sourceOf(size);
+    const started = Date.now();
+    try {
+      await call("script.create", {
+        scripts: [{ parent: "ServerScriptService", name, className: "ModuleScript", source }],
+      });
+      created.push(`ServerScriptService.${name}`);
+      const read = await call("script.read", { paths: [`ServerScriptService.${name}`] });
+      const item = read.items[0];
+      check(item?.source === source, `${size} bytes: create + read back identical (${Date.now() - started}ms)`);
+
+      const edited = await call("script.edit", {
+        edits: [{ path: `ServerScriptService.${name}`, find: "local value0 =", replace: "local first =", revision: item.revision }],
+      });
+      check(edited.items[0]?.edits === 1, `${size} bytes: conditional edit applied`);
+    } catch (cause) {
+      check(false, `${size} bytes: ${cause.message}`);
+    }
+  }
+} finally {
+  if (created.length > 0) {
+    await call("instances.delete", { paths: created }).catch((cause) => {
+      process.stderr.write(`cleanup failed, delete ${created.join(", ")} by hand: ${cause.message}\n`);
+    });
+  }
+}
+
+process.stdout.write(failures === 0 ? "live: ok\n" : `live: ${failures} failure(s)\n`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/test-tools.mjs

@@ -0,0 +1,39 @@
+/**
+ * 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");

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);