@el4cteo/rbx-studio-mcp 0.7.8 → 0.8.0

package/scripts/test-tools.mjs

@@ -1,216 +1,259 @@
-/**
- * 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 sessions() { return {list:[]}; }, 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);
-}
-// Issue #4: ordinary decimal holds/waits retain padding and yield whole milliseconds.
-for (const steps of [
- [{kind:"key",key:"E",hold:0.1,after:4.1}, ...Array.from({length:24}, () => ({kind:"key",key:"Left",hold:0.05,after:1.065}))],
- [{kind:"key",key:"E",hold:0.05,after:1.0651}],
-]) {
- await input.handler(z.object(input.spec.inputSchema).parse({steps}));
- const raw = (35 + steps.reduce((sum, step) => sum + step.hold + step.after + 0.5, 0)) * 1000;
- assert.equal(calls.at(-1).options.timeoutMs, Math.ceil(raw));
- assert.ok(Number.isInteger(calls.at(-1).options.timeoutMs));
- assert.deepEqual(calls.at(-1).params.steps, steps, "step timing itself is unchanged");
-}
-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");
-
-// A successful start includes the newly attached runtime session and player
-// names, using the same discovery path as stop. The editor ID is excluded.
-{
- let started = false;
- let operation = "play";
- const originalSessions = context.bridge.sessions;
- const originalCall = context.bridge.call;
- context.bridge.sessions = async () => ({list: started
-   ? [{studioId:"editor",context:"edit"},{studioId:"runtime",context:"playtest server"}]
-   : [{studioId:"editor",context:"edit"}]});
- context.bridge.call = async (op, params, options) => {
-  assert.equal(op, "playtest.control");
-  if (params.op === operation) {
-   started = true;
-   return {changed:true,state:{testPending:true,isRunning:false}};
-  }
-  assert.equal(options.studioId, "runtime");
-  return {changed:false,state:{players:operation === "multiplayer" ? [{name:"Alice",userId:123},{name:"Bob",userId:456}] : [{name:"Alice",userId:123}]}};
- };
- for (operation of ["play", "multiplayer"]) {
-  started = false;
-  const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:operation,studioId:"editor"}));
-  assert.match(result.content[0].text, /"studioId": "runtime"/);
-  assert.match(result.content[0].text, /"name": "Alice"/);
- }
- context.bridge.sessions = originalSessions;
- context.bridge.call = originalCall;
-}
-process.stdout.write("playtest runtime identity: 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");
-
-const { registerPerfTools } = await import("../dist/tools/perf.js");
-registerPerfTools(context);
-const consoleTool = registered.get("console");
-const consoleArgs = z.object(consoleTool.spec.inputSchema).parse({target:"client",player:"Alice",studioId:"runtime",since:"cursor-1",limit:10});
-context.bridge.call = async (op, params, options) => {
- assert.equal(op, "perf.console");
- assert.equal(params.target, "client");
- assert.equal(params.player, "Alice");
- assert.equal(params.since, "cursor-1");
- assert.equal(options.studioId, "runtime");
- return {items:[],total:0,dropped:0,evicted:2,nextCursor:"cursor-2",capturing:true};
-};
-const consoleResult = await consoleTool.handler(consoleArgs);
-assert.match(consoleResult.content[0].text, /2 older lines were evicted/);
-assert.match(consoleResult.content[0].text, /nextCursor: cursor-2/);
-context.bridge.call = async () => ({
- items: Array.from({length:60}, (_, index) => ({level:"print",message:`${index} ${"x".repeat(1000)}`})),
- total:60,dropped:0,nextCursor:"cursor-3",
-});
-const boundedConsole = await consoleTool.handler(z.object(consoleTool.spec.inputSchema).parse({}));
-assert.ok(boundedConsole.content[0].text.length < 25_000);
-assert.match(boundedConsole.content[0].text, /older matching lines omitted/);
-process.stdout.write("client console schema and cursor forwarding: ok\n");
+/**
+ * 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 sessions() { return {list:[]}; }, 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);
+}
+// Issue #4: ordinary decimal holds/waits retain padding and yield whole milliseconds.
+for (const steps of [
+ [{kind:"key",key:"E",hold:0.1,after:4.1}, ...Array.from({length:24}, () => ({kind:"key",key:"Left",hold:0.05,after:1.065}))],
+ [{kind:"key",key:"E",hold:0.05,after:1.0651}],
+]) {
+ await input.handler(z.object(input.spec.inputSchema).parse({steps}));
+ const raw = (35 + steps.reduce((sum, step) => sum + step.hold + step.after + 0.5, 0)) * 1000;
+ assert.equal(calls.at(-1).options.timeoutMs, Math.ceil(raw));
+ assert.ok(Number.isInteger(calls.at(-1).options.timeoutMs));
+ assert.deepEqual(calls.at(-1).params.steps, steps, "step timing itself is unchanged");
+}
+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");
+
+// A successful start includes the newly attached runtime session and player
+// names, using the same discovery path as stop. The editor ID is excluded.
+{
+ let started = false;
+ let operation = "play";
+ const originalSessions = context.bridge.sessions;
+ const originalCall = context.bridge.call;
+ context.bridge.sessions = async () => ({list: started
+   ? [{studioId:"editor",context:"edit"},{studioId:"runtime",context:"playtest server"}]
+   : [{studioId:"editor",context:"edit"}]});
+ context.bridge.call = async (op, params, options) => {
+  assert.equal(op, "playtest.control");
+  if (params.op === operation) {
+   started = true;
+   return {changed:true,state:{testPending:true,isRunning:false}};
+  }
+  assert.equal(options.studioId, "runtime");
+  return {changed:false,state:{players:operation === "multiplayer" ? [{name:"Alice",userId:123},{name:"Bob",userId:456}] : [{name:"Alice",userId:123}]}};
+ };
+ for (operation of ["play", "multiplayer"]) {
+  started = false;
+  const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:operation,studioId:"editor"}));
+  assert.match(result.content[0].text, /"studioId": ?"runtime"/);
+  assert.match(result.content[0].text, /"name": ?"Alice"/);
+ }
+ context.bridge.sessions = originalSessions;
+ context.bridge.call = originalCall;
+}
+process.stdout.write("playtest runtime identity: 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");
+
+const { registerPerfTools } = await import("../dist/tools/perf.js");
+registerPerfTools(context);
+const consoleTool = registered.get("console");
+const consoleArgs = z.object(consoleTool.spec.inputSchema).parse({target:"client",player:"Alice",studioId:"runtime",since:"cursor-1",limit:10});
+context.bridge.call = async (op, params, options) => {
+ assert.equal(op, "perf.console");
+ assert.equal(params.target, "client");
+ assert.equal(params.player, "Alice");
+ assert.equal(params.since, "cursor-1");
+ assert.equal(options.studioId, "runtime");
+ return {items:[],total:0,dropped:0,evicted:2,nextCursor:"cursor-2",capturing:true};
+};
+const consoleResult = await consoleTool.handler(consoleArgs);
+assert.match(consoleResult.content[0].text, /2 older lines were evicted/);
+assert.match(consoleResult.content[0].text, /nextCursor: cursor-2/);
+context.bridge.call = async () => ({
+ items: Array.from({length:60}, (_, index) => ({level:"print",message:`${index} ${"x".repeat(1000)}`})),
+ total:60,dropped:0,nextCursor:"cursor-3",
+});
+const boundedConsole = await consoleTool.handler(z.object(consoleTool.spec.inputSchema).parse({}));
+assert.ok(boundedConsole.content[0].text.length < 25_000);
+assert.match(boundedConsole.content[0].text, /older matching lines omitted/);
+process.stdout.write("client console schema and cursor forwarding: ok\n");
+
+// `create` must not advertise a recursive schema -- Gemini / Vertex AI reject a
+// `$ref` with HTTP 400 -- yet a bad nested child is still refused by name.
+{
+ const { registerInstanceTools } = await import("../dist/tools/instances.js");
+ const tools = new Map();
+ registerInstanceTools({ server: { registerTool(name, spec, handler) { tools.set(name, { spec, handler }); } }, bridge: { async call() { throw new Error("must not reach Studio"); } } });
+ const create = tools.get("create");
+ const schema = JSON.stringify(z.toJSONSchema(z.object(create.spec.inputSchema)));
+ assert.ok(!schema.includes("$ref") && !schema.includes("$defs") && !schema.includes("definitions"), "create schema is not recursive");
+ const bad = await create.handler(z.object(create.spec.inputSchema).parse({ instances: [{ parent: "Workspace", className: "Model", children: [{ className: "Part", children: [{ name: "NoClass" }] }] }] }));
+ assert.equal(bad.isError, true);
+ assert.match(bad.content[0].text, /BAD_PARAMS\] instances\[0\]\.children\[0\]\.children\[0\]\.className/);
+ process.stdout.write("create schema without recursion, nested validation: ok\n");
+}
+
+// Compact JSON: short structures on one line, and always parsed back identical.
+{
+ const { stringify } = await import("../dist/lib/format.js");
+ const value = { rows: [{ path: "Workspace.A", className: "Part" }], nested: { list: [1, "two", null, undefined], skip: undefined, when: new Date(0) }, long: "x".repeat(150) };
+ assert.deepEqual(JSON.parse(stringify(value)), JSON.parse(JSON.stringify(value)));
+ assert.match(stringify(value), /\n  "rows": \[\{"path":"Workspace.A","className":"Part"\}\],\n/, "a short row stays on one line");
+ assert.equal(stringify([]), "[]");
+ assert.equal(stringify(undefined), "null");
+ process.stdout.write("compact json: ok\n");
+}
+
+// Screenshot scaling: box filter averages everything under a pixel; enlarging copies blocks.
+{
+ const { boxResample, upscaleNearest } = await import("../dist/lib/png.js");
+ const stripes = Buffer.from([0,0,0, 200,200,200, 0,0,0, 200,200,200, 0,0,0, 200,200,200, 0,0,0, 200,200,200]);
+ assert.deepEqual([...boxResample(stripes, 4, 2, 2).rgb], [100,100,100, 100,100,100], "averages, never samples");
+ const W = 1661, H = 719, line = Buffer.alloc(W * H * 3);
+ for (let y = 0; y < H; y += 1) line[(y * W + 831) * 3] = 255;
+ const scaled = boxResample(line, W, H, 800);
+ assert.equal(scaled.width, 800);
+ assert.equal(scaled.height, 346);
+ let red = 0; for (let i = 0; i < scaled.rgb.length; i += 3) red = Math.max(red, scaled.rgb[i]);
+ assert.ok(red > 100, "a one-pixel line survives a 2x reduction");
+ assert.equal(boxResample(stripes, 4, 2, 8).width, 4, "never scales up");
+ assert.deepEqual([...upscaleNearest(Buffer.from([1,2,3,4,5,6]), 2, 1, 2).rgb], [1,2,3,1,2,3,4,5,6,4,5,6,1,2,3,1,2,3,4,5,6,4,5,6]);
+ process.stdout.write("screenshot scaling: ok\n");
+}

package/dist/tools/anim.js

@@ -1,159 +0,0 @@
-import { z } from "zod";
-import { json, table, text, textOf } from "../lib/format.js";
-import { defineTool } from "../lib/tool.js";
-/** Downloads go to Roblox's asset servers, which are not always quick. */
-const TIMEOUT_MS = 45_000;
-export function registerAnimTools(context) {
-    const { bridge } = context;
-    defineTool(context, {
-        name: "animation",
-        title: "Read and build animations",
-        description: "Reads an animation's actual keyframes, and builds new ones that play " +
-            "immediately in the open Studio.\n\n" +
-            "Animations are the one part of a place no other tool can see. " +
-            "`inspect` on an Animation instance returns an asset id and stops there " +
-            "— the poses live on Roblox's servers. `read` downloads them, so you can " +
-            "answer 'how long is it', 'which joints does it move', and 'does it end " +
-            "where it started' without opening the Animation Editor and scrubbing.\n\n" +
-            "`read` takes an asset id, an rbxassetid:// string, or the path of an " +
-            "Animation instance in the place — whichever you already have. It reports " +
-            "which RIG the animation was made for, which is the thing most worth " +
-            "knowing: an R15 animation on an R6 character does nothing at all — no " +
-            "error, no movement — and the asset id gives no hint either way.\n\n" +
-            "`build` goes the other way: give it keyframes and it returns a content " +
-            "id you can put straight into an Animation's AnimationId. Nothing is " +
-            "uploaded and nothing is moderated — the id works in this Studio session " +
-            "and nowhere else, which makes it the right way to try an idea and the " +
-            "wrong way to ship one.\n\n" +
-            "`preview` puts an animation ONTO a rig in the open place and freezes it " +
-            "at a chosen moment, so `screenshot` can show you the pose. It works in " +
-            "edit mode — no playtest. Ask for several moments in turn to compare " +
-            "poses across the animation; the rig stays posed until `stop`.\n\n" +
-            "Poses are written the way a CFrame property is: \"0, 1, 0\" for a " +
-            "position, \"0, 1, 0 | 0, 45, 0\" to rotate as well.\n\n" +
-            "The id `build` returns is a bare hash, not an rbxassetid:// URL. Use it " +
-            "exactly as given — prefixing it stops it working.",
-        inputSchema: {
-            op: z
-                .enum(["read", "preview", "build", "stop"])
-                .default("read")
-                .describe("'read' downloads an existing animation, 'preview' poses a rig at one " +
-                "moment of it so you can screenshot it, 'build' makes a new one " +
-                "playable here, 'stop' clears a preview."),
-            assetId: z
-                .union([z.number(), z.string()])
-                .optional()
-                .describe('read only: animation asset id (12345), "rbxassetid://12345", or the ' +
-                'path of an Animation instance ("Workspace.Rig.Animate.run").'),
-            keyframes: z
-                .array(z.object({
-                time: z.number().min(0).describe("Seconds from the start of the animation."),
-                name: z.string().optional().describe('Keyframe name, e.g. "Start" or a marker name.'),
-                poses: z
-                    .record(z.string(), z.string())
-                    .optional()
-                    .describe('Joint name → CFrame, e.g. { "Right Arm": "0, 0.5, 0 | 0, 0, 45" }. ' +
-                    "Joint names must match the rig's parts."),
-            }))
-                .max(200)
-                .optional()
-                .describe("build only: the keyframes, in any order — they are sorted by time."),
-            name: z.string().optional().describe("build only: name for the sequence."),
-            root: z
-                .string()
-                .optional()
-                .describe('build only: the rig part every pose hangs from. Defaults to "HumanoidRootPart", ' +
-                "which is right for an R15 or R6 character."),
-            priority: z
-                .enum(["Idle", "Movement", "Action", "Core"])
-                .optional()
-                .describe("build only: which animations this one plays over."),
-            loop: z.boolean().optional().describe("build only: whether it repeats."),
-            rig: z
-                .string()
-                .optional()
-                .describe('The model, e.g. "Workspace.Dummy". For preview/stop it is the rig to ' +
-                "pose, and needs a Humanoid or an AnimationController inside it. For " +
-                "`build` it is optional and is read for its joint layout — pass it for " +
-                "anything that is not a standard R6 or R15 character (a custom rig, a " +
-                "weapon, a door, a Blender import), or the poses may be attached in the " +
-                "wrong order and the animation will move nothing."),
-            at: z
-                .number()
-                .min(0)
-                .optional()
-                .describe("preview only: the moment to freeze on, in seconds. Ask for several " +
-                "in turn to compare poses across the animation."),
-            hold: z
-                .boolean()
-                .default(true)
-                .describe("preview only: freeze on that frame. Turn off to let it play, but then " +
-                "a screenshot catches whatever pose it happens to be in."),
-            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
-        },
-        readOnly: false,
-        destructive: false,
-    }, async (args) => {
-        if (args.op === "preview" || args.op === "stop") {
-            if (!args.rig)
-                return text("preview needs a `rig` — the model to pose.");
-            const posed = await bridge.call("anim.preview", { op: args.op, rig: args.rig, assetId: args.assetId, at: args.at, hold: args.hold }, { studioId: args.studioId, timeoutMs: TIMEOUT_MS });
-            return json(posed);
-        }
-        if (args.op === "build") {
-            if (!args.keyframes || args.keyframes.length === 0) {
-                return text("build needs a non-empty `keyframes` array.");
-            }
-            const built = await bridge.call("anim.build", {
-                keyframes: args.keyframes,
-                name: args.name,
-                root: args.root,
-                rig: args.rig,
-                priority: args.priority,
-                loop: args.loop,
-            }, { studioId: args.studioId, timeoutMs: TIMEOUT_MS });
-            return json(built, "Set this as an Animation's AnimationId with `modify`, exactly as it appears " +
-                "— it is a bare hash, and adding rbxassetid:// in front of it stops it " +
-                "working. Local to this Studio session: not uploaded, gone on restart.\n\n" +
-                "`hierarchy` says which joint layout the poses were nested against — the " +
-                "rig you named, or the R6/R15 standard guessed from the joint names. " +
-                "Anything in `unmatchedJoints` is a name that layout does not contain: " +
-                "those poses were attached to the root and will almost certainly do " +
-                "nothing. Pass `rig` to fix it.");
-        }
-        if (args.assetId === undefined) {
-            return text("read needs an `assetId` — a number, an rbxassetid:// string, or a path to an Animation.");
-        }
-        const found = await bridge.call("anim.read", { assetId: args.assetId }, { studioId: args.studioId, timeoutMs: TIMEOUT_MS });
-        /*
-         * A summary first, then the timeline. The three facts at the top are what
-         * the question was, and burying them under forty rows of keyframes would
-         * make the tool technically complete and practically unreadable.
-         */
-        const lines = [
-            `${found.name ?? found.assetId} — ${found.rig} rig, ${found.duration}s, ` +
-                `${found.keyframeCount} keyframes, ${found.jointCount} joints moved`,
-            `Priority ${found.priority}${found.looping ? ", loops" : ", does not loop"}` +
-                (found.rigNote !== undefined ? ` — ${found.rigNote}` : ""),
-            "",
-            `Joints: ${found.joints.join(", ") || "none"}` +
-                (found.jointsSampled ? ` … and ${found.jointCount - found.joints.length} more` : ""),
-        ];
-        if (found.rig === "R6" || found.rig === "R15") {
-            lines.push("", `This is an ${found.rig} animation. It will do NOTHING on an ${found.rig === "R6" ? "R15" : "R6"} character — no error, no movement, because the joint names do not exist ` +
-                "on the other rig. Check the character's rig type before using it.");
-        }
-        if (found.looping && found.endsWhereItStarted === false) {
-            lines.push("", "WARNING: this animation loops, but these joints do not end where they " +
-                `started: ${(found.driftingJoints ?? []).join(", ")}. That is what a ` +
-                "visible jump at the loop point looks like.");
-        }
-        lines.push("", textOf(table(["index", "time", "name", "poseCount"], found.keyframes, {
-            more: found.truncated
-                ? `poses expanded for the first 40 keyframes only`
-                : undefined,
-        })));
-        return text(lines.join("\n"));
-    });
-}
-//# sourceMappingURL=anim.js.map