@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

package/scripts/test-live-sync.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * `sync` against a real Studio, through the real MCP layer.
+ *
+ * Everything happens inside ServerStorage.__mcp_live_sync and a temp folder;
+ * both are removed before exit, pass or fail. Checks the things an offline fake
+ * cannot: the plugin's scan, the editor write path, identity kept across a
+ * rename, build files round-tripping real property values, and watch mode
+ * reacting to real file and editor events.
+ *
+ * Usage: node scripts/test-live-sync.mjs [--port 44755] [--studio-id ID]
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { existsSync, mkdtempSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? undefined : args[at + 1];
+};
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const FIXTURE = "ServerStorage.__mcp_live_sync";
+const dir = mkdtempSync(join(tmpdir(), "rbx-live-sync-"));
+const base = `ServerStorage/__mcp_live_sync`;
+const file = (relative) => join(dir, ...`${base}/${relative}`.split("/"));
+
+const client = new Client({ name: "test-live-sync", version: "0" });
+await client.connect(
+  new StdioClientTransport({
+    command: process.execPath,
+    args: [join(root, "dist", "index.js"), ...(flag("port") ? ["--port", flag("port")] : [])],
+    stderr: "inherit",
+  }),
+);
+
+let failures = 0;
+const studioId = flag("studio-id");
+
+async function call(name, params = {}) {
+  const started = performance.now();
+  try {
+    const result = await client.callTool(
+      { name, arguments: { ...(studioId ? { studioId } : {}), ...params } },
+      undefined,
+      { timeout: 180_000 },
+    );
+    const text = (result.content ?? []).filter((part) => part.type === "text").map((part) => part.text).join("\n");
+    return { text, isError: result.isError === true, ms: Math.round(performance.now() - started) };
+  } catch (cause) {
+    return { text: cause.message, isError: true, ms: Math.round(performance.now() - started) };
+  }
+}
+
+function report(label, good, detail = "") {
+  if (!good) failures += 1;
+  process.stdout.write(`${good ? "ok  " : "FAIL"}  ${label.padEnd(52)} ${detail.replace(/\s+/g, " ").slice(0, good ? 90 : 400)}\n`);
+}
+
+async function check(label, name, params, expect = /./) {
+  const reply = await call(name, params);
+  report(label, !reply.isError && expect.test(reply.text), `${reply.ms}ms ${reply.text}`);
+  return reply.text;
+}
+
+/** Runs Luau in the edit session and returns what it returned, as text. */
+async function luau(source) {
+  const reply = await call("execute_luau", { source });
+  if (reply.isError) throw new Error(reply.text);
+  return reply.text;
+}
+
+const sync = (op, extra = {}) => ({ op, dir, roots: [FIXTURE], ...extra });
+// The first lines that differ, for a readable failure.
+const diffOf = (before, after) => {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const at = a.findIndex((line, index) => line !== b[index]);
+  return `line ${at + 1}: ${a[at]?.trim()}  ->  ${b[at]?.trim()}`;
+};
+const read = (relative) => readFileSync(file(relative), "utf8");
+const until = async (probe, seconds = 8) => {
+  const deadline = Date.now() + seconds * 1000;
+  for (;;) {
+    if (await probe()) return true;
+    if (Date.now() > deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+};
+
+try {
+  await luau(`
+    local old = game.ServerStorage:FindFirstChild("__mcp_live_sync")
+    if old then old:Destroy() end
+    local fixture = Instance.new("Folder"); fixture.Name = "__mcp_live_sync"
+    local shared = Instance.new("Folder"); shared.Name = "Shared"; shared.Parent = fixture
+    local util = Instance.new("ModuleScript"); util.Name = "Util"; util.Source = "return 1\\n"; util:SetAttribute("Marker", "util"); util.Parent = shared
+    local main = Instance.new("Script"); main.Name = "Main"; main.Source = "print('main')\\n"; main.Parent = fixture
+    local helper = Instance.new("ModuleScript"); helper.Name = "Helper"; helper.Source = "return 'helper'\\n"; helper.Parent = main
+    local gui = Instance.new("ScreenGui"); gui.Name = "Gui"; gui.ResetOnSpawn = false; gui.Parent = fixture
+    local panel = Instance.new("Frame"); panel.Name = "Panel"; panel.Size = UDim2.new(0, 200, 0, 100); panel.BackgroundColor3 = Color3.new(1, 0.5, 0); panel.Parent = gui
+    local title = Instance.new("TextLabel"); title.Name = "Title"; title.Text = "Hello"; title.Parent = panel
+    local client = Instance.new("LocalScript"); client.Name = "GuiClient"; client.Source = "-- gui\\n"; client:SetAttribute("Marker", "gui"); client.Parent = panel
+    fixture.Parent = game.ServerStorage
+    return "ready"`);
+
+  // Pull: the tree lands on disk, Rojo-style.
+  await check("pull: first sync writes every script", "sync", sync("pull"), /4 created on disk/);
+  report("pull: script with children is a folder + init", existsSync(file("Main/init.server.luau")) && read("Main/Helper.luau") === "return 'helper'\n");
+  report("pull: LocalScript and ModuleScript extensions", existsSync(file("Gui/Panel/GuiClient.client.luau")) && read("Shared/Util.luau") === "return 1\n");
+  await check("status: nothing to do right after", "sync", sync("status"), /nothing to do/);
+
+  // Push: a file edit reaches the editor buffer.
+  writeFileSync(file("Shared/Util.luau"), "return 2\n");
+  await check("push: edited file", "sync", sync("push"), /1 written to Studio/);
+  await check("push: Studio has the new text", "script_read", { paths: [`${FIXTURE}.Shared.Util`] }, /return 2/);
+
+  // Pull: an editor edit reaches the file.
+  await check("studio edit through script_edit", "script_edit", { edits: [{ path: `${FIXTURE}.Main.Helper`, find: "'helper'", replace: "'studio'" }] });
+  await check("sync: Studio edit comes back", "sync", sync("sync"), /1 written to disk/);
+  report("file has the Studio edit", read("Main/Helper.luau") === "return 'studio'\n", read("Main/Helper.luau"));
+
+  // New file in a new folder: a new script, under a new Folder.
+  writeFileSync(file("Shared/New.luau"), "return 'new'\n");
+  await check("new file becomes a script", "sync", sync("sync"), /1 created in Studio/);
+  const created = await luau(`return game.ServerStorage.__mcp_live_sync.Shared.New.Source`);
+  report("new script has the file's text", created.includes("return 'new'"), created);
+
+  // Rename a file: the SAME script is renamed (its attribute survives).
+  renameSync(file("Shared/Util.luau"), file("Shared/Tools.luau"));
+  await check("renamed file moves the script", "sync", sync("sync"), /1 moved in Studio/);
+  const marker = await luau(`local s = game.ServerStorage.__mcp_live_sync.Shared:FindFirstChild("Tools"); return if s then s:GetAttribute("Marker") else "missing"`);
+  report("same instance: attribute kept across rename", marker.includes("util"), marker);
+
+  // Both sides changed: a conflict that touches neither side.
+  writeFileSync(file("Shared/Tools.luau"), "return 'disk'\n");
+  await luau(`game:GetService("ScriptEditorService"):UpdateSourceAsync(game.ServerStorage.__mcp_live_sync.Shared.Tools, function() return "return 'editor'\\n" end) return 1`);
+  await check("conflict is reported", "sync", sync("sync"), /Conflicts[\s\S]*Tools\.luau/);
+  report("conflict left the file alone", read("Shared/Tools.luau") === "return 'disk'\n");
+  await check("prefer disk settles it", "sync", sync("sync", { prefer: "disk" }), /1 written to Studio/);
+  await check("Studio took the disk side", "script_read", { paths: [`${FIXTURE}.Shared.Tools`] }, /return 'disk'/);
+
+  // Delete a file: the script is deleted (undoably).
+  unlinkSync(file("Shared/New.luau"));
+  await check("deleted file deletes the script", "sync", sync("sync"), /1 deleted in Studio[\s\S]*MCP sync/);
+  const gone = await luau(`return game.ServerStorage.__mcp_live_sync.Shared:FindFirstChild("New") == nil`);
+  report("script is gone", gone.includes("true"), gone);
+
+  // Build files: export, edit, rebuild -- scripts carried across.
+  await check("export a ScreenGui", "sync", { op: "export", dir, roots: [FIXTURE], paths: [`${FIXTURE}.Gui`] }, /Gui\.build\.json/);
+  const spec = JSON.parse(read("Gui.build.json"));
+  const title = spec.children[0].children.find((child) => child.name === "Title");
+  report("export holds non-default values only", spec.properties?.ResetOnSpawn === false && title?.properties?.Text === "Hello" && !("Visible" in (title.properties ?? {})), JSON.stringify(spec).slice(0, 300));
+  report("export leaves scripts out", !JSON.stringify(spec).includes("GuiClient"));
+  title.properties.Text = "Rebuilt";
+  writeFileSync(file("Gui.build.json"), `${JSON.stringify(spec, null, 2)}\n`);
+  await check("build rebuilds from the edited file", "sync", { op: "build", dir, roots: [FIXTURE] }, /Gui\.build\.json/);
+  const rebuilt = await luau(`
+    local gui = game.ServerStorage.__mcp_live_sync.Gui
+    local client = gui.Panel:FindFirstChild("GuiClient")
+    return gui.Panel.Title.Text .. "|" .. tostring(client and client:GetAttribute("Marker")) .. "|" .. tostring(gui.Panel.BackgroundColor3)`);
+  report("rebuilt text, same script, colour kept", rebuilt.includes("Rebuilt|gui|1, 0.5") || rebuilt.includes("Rebuilt|gui|1, 0.50"), rebuilt);
+
+  // Build files must round-trip every kind of value exactly, and references
+  // inside a rebuilt tree must point into the NEW tree, not the old one.
+  await luau(`
+    local fixture = game.ServerStorage.__mcp_live_sync
+    local model = Instance.new("Model"); model.Name = "Rig"
+    local a = Instance.new("Part"); a.Name = "A"; a.Anchored = true; a.Material = Enum.Material.Neon; a.BrickColor = BrickColor.new("Bright red")
+    a.CFrame = CFrame.new(1, 2, 3) * CFrame.Angles(0, math.rad(45), 0); a.Size = Vector3.new(2, 3, 4); a.Parent = model
+    local b = Instance.new("Part"); b.Name = "B"; b.Shape = Enum.PartType.Ball; b.Color = Color3.fromRGB(10, 200, 30); b.Position = Vector3.new(5, 2, 3); b.Parent = model
+    local weld = Instance.new("WeldConstraint"); weld.Name = "Weld"; weld.Part0 = a; weld.Part1 = b; weld.Parent = model
+    local pointer = Instance.new("ObjectValue"); pointer.Name = "Pointer"; pointer.Value = b; pointer.Parent = model
+    model.PrimaryPart = a
+    local gui = Instance.new("Frame"); gui.Name = "Card"; gui.Size = UDim2.new(0.5, 10, 0, 40); gui.Parent = model
+    local corner = Instance.new("UICorner"); corner.CornerRadius = UDim.new(0, 12); corner.Parent = gui
+    local gradient = Instance.new("UIGradient")
+    gradient.Color = ColorSequence.new({ ColorSequenceKeypoint.new(0, Color3.new(1, 0, 0)), ColorSequenceKeypoint.new(1, Color3.new(0, 0, 1)) })
+    gradient.Transparency = NumberSequence.new({ NumberSequenceKeypoint.new(0, 0), NumberSequenceKeypoint.new(1, 0.5) })
+    gradient.Rotation = 90; gradient.Parent = gui
+    local label = Instance.new("TextLabel"); label.Name = "Label"; label.Text = "Tag"; label.RichText = true
+    label.FontFace = Font.new("rbxasset://fonts/families/GothamSSm.json", Enum.FontWeight.Bold, Enum.FontStyle.Italic); label.Parent = gui
+    local image = Instance.new("ImageLabel"); image.Name = "Icon"; image.Image = "rbxassetid://123456"; image.ScaleType = Enum.ScaleType.Slice
+    image.SliceCenter = Rect.new(4, 4, 12, 12); image.Parent = gui
+    model.Parent = fixture
+    return 1`);
+  await check("export a tree of many value types", "sync", { op: "export", dir, roots: [FIXTURE], paths: [`${FIXTURE}.Rig`] }, /Rig\.build\.json/);
+  const exportedRig = read("Rig.build.json");
+  report(
+    "references export as paths into the tree",
+    exportedRig.includes(`"Part0": "${FIXTURE}.Rig.A"`) && exportedRig.includes(`"PrimaryPart": "${FIXTURE}.Rig.A"`),
+    exportedRig.slice(0, 200),
+  );
+  const missing = ["FontFace", "\"Size\": \"2, 3, 4\"", "\"Shape\"", '"Color"', '"Transparency"', "SliceCenter", "CornerRadius", "Material", "CFrame", "Part0", "Part1", "RichText", "rbxassetid://123456"]
+    .filter((needle) => !exportedRig.includes(needle));
+  report("every value type made it into the file", missing.length === 0, missing.join(", "));
+  // Rebuild from the untouched file, then export again: nothing may drift.
+  await check("rebuild from the same file", "sync", { op: "build", dir, roots: [FIXTURE], files: [`${base}/Rig.build.json`], prefer: "disk" }, /Rig\.build\.json/);
+  await check("export the rebuilt tree", "sync", { op: "export", dir, roots: [FIXTURE], paths: [`${FIXTURE}.Rig`] }, /Rig\.build\.json/);
+  const again = read("Rig.build.json");
+  report("round trip is lossless", again === exportedRig, again === exportedRig ? "" : diffOf(exportedRig, again));
+  const wired = await luau(`
+    local rig = game.ServerStorage.__mcp_live_sync.Rig
+    local weld = rig.Weld
+    return tostring(weld.Part0 == rig.A and weld.Part1 == rig.B and rig.Pointer.Value == rig.B and rig.PrimaryPart == rig.A)
+      .. "|" .. tostring(#game.ServerStorage.__mcp_live_sync:GetChildren())`);
+  report("references point into the new tree, old tree gone", wired.includes("true|4"), wired);
+
+  // Watch: both directions within seconds, with no call in between.
+  await check("watch starts", "sync", sync("watch"), /Watching/);
+  writeFileSync(file("Main/Helper.luau"), "return 'watched'\n");
+  const toStudio = await until(async () => (await luau(`return game.ServerStorage.__mcp_live_sync.Main.Helper.Source`)).includes("watched"));
+  report("watch: file edit reaches Studio", toStudio);
+  await luau(`game:GetService("ScriptEditorService"):UpdateSourceAsync(game.ServerStorage.__mcp_live_sync.Main.Helper, function() return "return 'from studio'\\n" end) return 1`);
+  const toDisk = await until(async () => read("Main/Helper.luau") === "return 'from studio'\n");
+  report("watch: Studio edit reaches the file", toDisk, read("Main/Helper.luau"));
+  await check("watch: status shows it running", "sync", sync("status"), /Watching since/);
+  await check("watch stops", "sync", sync("stop"), /Stopped watching/);
+} catch (cause) {
+  report("run", false, String(cause?.stack ?? cause));
+} finally {
+  await call("sync", { op: "stop", dir }).catch(() => undefined);
+  await luau(`local f = game.ServerStorage:FindFirstChild("__mcp_live_sync") if f then f:Destroy() end return 1`).catch(() => undefined);
+  rmSync(dir, { recursive: true, force: true });
+  await client.close();
+}
+
+process.stdout.write(failures === 0 ? "\nlive sync: ok\n" : `\nlive sync: ${failures} failure(s)\n`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/test-live-tools.mjs

@@ -138,7 +138,12 @@ try {
   await ok("inspect: named properties", "inspect", { paths: [`${FIXTURE}.A`], properties: ["Name", "Position"] }, /Position/);
   await ok("script_read", "script_read", { paths: [`${FIXTURE}.Mod`] }, /rev [0-9a-f]+/);
   await ok("script_read: a window", "script_read", { paths: [{ path: `${FIXTURE}.Mod`, startLine: 2, endLine: 3 }] }, /lines 2-3 of 5/);
-  await ok("script_grep", "script_grep", { pattern: "add", literal: true, path: FIXTURE }, /Mod:2/);
+  await ok("script_grep", "script_grep", { pattern: "add", literal: true, path: FIXTURE }, /Mod +rev=[0-9a-f]+-[0-9a-f]+\n2: /);
+  await ok("script_grep: patterns", "script_grep", { patterns: ["add", "return"], path: FIXTURE }, /\[patterns 1\]/);
+  await ok("script_grep: counts", "script_grep", { patterns: ["add", "nothing-here"], path: FIXTURE, mode: "counts" }, /"lines": ?0/);
+  await ok("script_grep: files", "script_grep", { pattern: "add", literal: true, path: FIXTURE, mode: "files" }, /Mod \| ModuleScript \| [0-9a-f]+-/);
+  await ok("find: properties", "find", { path: FIXTURE, className: "Part", properties: ["Anchored", "NotAProperty"] }, /"Anchored":\s*true[\s\S]*NotAProperty/);
+  await ok("console: drain", "console", { mode: "drain", limit: 5 }, /nextCursor/);
   await ok("api: describe", "api", { op: "describe", className: "Part" }, /superclass/);
   await ok("api: classes", "api", { op: "classes", contains: "Constraint" }, /HingeConstraint/);
   await ok("console", "console", { limit: 5 });

package/scripts/test-plugin.mjs

@@ -28,8 +28,18 @@ if (luau === null) {
 
 /** Modules under test, paired with the test file that exercises each. */
 const suites = [
+  { module: "plugin/src/Dispatch.luau", test: "tests/deadlines.luau", prelude: "tests/deadlines-stub.luau" },
+  { module: "plugin/src/ScriptEdit.luau", test: "tests/scriptedit.luau", prelude: "tests/scriptedit-stub.luau" },
+  { module: "plugin/src/Undo.luau", test: "tests/undo.luau", prelude: "tests/undo-stub.luau" },
+  {
+    module: "plugin/src/handlers/Scripts.luau",
+    test: "tests/scripts.luau",
+    prelude: "tests/scripts-stub.luau",
+    dependencies: [{ name: "TextEdit", path: "plugin/src/TextEdit.luau" }],
+  },
   { 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/Commands.luau", test: "tests/chat-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" },
@@ -45,6 +55,8 @@ const suites = [
  * MCP server turns into an actionable error for the agent.
  */
 const DISPATCH_STUB = `local Dispatch = {}
+function Dispatch.checkDeadline() end
+function Dispatch.deadline() return nil end
 function Dispatch.fail(code, message, hint)
 \terror({ code = code, message = message, hint = hint }, 0)
 end
@@ -63,6 +75,11 @@ for (const suite of suites) {
   const bundle = [
     DISPATCH_STUB,
     suite.prelude ? readFileSync(join(root, suite.prelude), "utf8") : "",
+    // Real modules loaded as the module's own dependencies, not stubbed.
+    ...(suite.dependencies ?? []).map(
+      (dependency) =>
+        `local ${dependency.name} = (function()\n${stripRequires(readFileSync(join(root, dependency.path), "utf8"))}\nend)()`,
+    ),
     suite.dependency ? `local Playtest = (function()\n${stripRequires(readFileSync(join(root, suite.dependency), "utf8"))}\nend)()` : "",
     "local function loadModule()",
     moduleSource,

package/scripts/test-results.mjs

@@ -0,0 +1,41 @@
+/** Response budgets, cursors that survive clipping, and grouped grep rendering. */
+import assert from "node:assert/strict";
+import { z } from "zod";
+import { CHARACTER_LIMIT, decodeCursor, json, page, table } from "../dist/lib/format.js";
+import { registerScriptTools } from "../dist/tools/scripts.js";
+const output = result => result.content.filter(c => c.type === "text").map(c => c.text).join("\n");
+const rows = Array.from({length: 20}, (_, i) => ({path: "P" + i, data: "x".repeat(4000)}));
+for (const result of [table(["path", "data"], rows, {offset: 10, total: 30}), page(rows, {offset: 10, total: 30})]) {
+ const rendered = output(result);
+ assert.ok(rendered.length <= CHARACTER_LIMIT);
+ const cursor = rendered.match(/cursor: "([^"]+)"/)?.[1];
+ const next = decodeCursor(cursor);
+ assert.ok(next > 10 && next < 30, "budget cursor must not skip unseen rows");
+ assert.ok(rendered.includes("P" + (next - 11)) && !rendered.includes("P" + (next - 10)));
+}
+for (const value of [{data: "\u0000".repeat(100000)}, Array.from({length: 5000}, () => ({nested: {data: "x".repeat(10000)}}))]) {
+ const rendered = output(json(value));
+ assert.ok(rendered.length <= CHARACTER_LIMIT);
+ assert.equal(JSON.parse(rendered).truncated, true, "large JSON must stay valid");
+}
+const registered = new Map();
+const context = {server: {registerTool: (name, spec, handler) => registered.set(name, {spec, handler})}, bridge: {}};
+registerScriptTools(context);
+const call = (name, args) => {const tool = registered.get(name); return tool.handler(z.object(tool.spec.inputSchema).parse(args));};
+context.bridge.call = async (op, params) => {
+ assert.equal(op, "script.grep"); assert.deepEqual(params.patterns, ["alpha", "beta"]);
+ return {searched: 1, total: 2, offset: 0, items: [
+  {path: "Script", revision: "r1", line: 2, text: "alpha", before: ["one"], after: ["beta", "four"], needles: [1]},
+  {path: "Script", revision: "r1", line: 3, text: "beta", before: ["one", "alpha"], after: ["four"], needles: [2]},
+ ]};
+};
+const grep = output(await call("script_grep", {patterns: ["alpha", "beta"], contextLines: 2}));
+assert.equal(grep.match(/rev=r1/g).length, 1);
+assert.equal(grep.match(/alpha/g).length, 1); assert.equal(grep.match(/beta/g).length, 1);
+assert.equal(grep.match(/four/g).length, 1);
+context.bridge.call = async () => ({searched: 1, total: 20, offset: 0, items: Array.from({length: 20}, (_, i) => ({path: "Big", line: i + 1, text: "x".repeat(4000)}))});
+const clipped = output(await call("script_grep", {pattern: "x"}));
+assert.ok(clipped.length <= CHARACTER_LIMIT && clipped.includes("cursor:"));
+assert.ok(decodeCursor(clipped.match(/cursor: "([^"]+)"/)[1]) < 20);
+
+console.log("results: budgets, clipped cursors and merged search context pass");

package/scripts/test-sync-more.mjs

@@ -0,0 +1,228 @@
+/**
+ * `sync`, offline, part two: conflicts that remember themselves, build files
+ * both ways, and `watch` -- echo suppression and notices on the next reply.
+ *
+ * Build files go through the real create-spec typing, which reads the API
+ * dump, so the dump is a small fixture in a sandboxed temp dir and the network
+ * is refused: the run is the same on every machine.
+ *
+ * Usage: node scripts/test-sync-more.mjs   (after `npm run build`)
+ */
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const sandbox = mkdtempSync(path.join(tmpdir(), "rbx-sync-more-"));
+for (const name of ["TMPDIR", "TEMP", "TMP"]) process.env[name] = sandbox;
+globalThis.fetch = async () => {
+  throw new Error("offline");
+};
+const property = (name, type) => ({ MemberType: "Property", Name: name, ValueType: { Name: type, Category: "Primitive" } });
+mkdirSync(path.join(sandbox, "roblox-studio-mcp"), { recursive: true });
+writeFileSync(
+  path.join(sandbox, "roblox-studio-mcp", "api-dump.json"),
+  JSON.stringify({
+    fetchedAt: Date.now(),
+    dump: {
+      Classes: [
+        { Name: "Instance", Superclass: "", Members: [property("Name", "string")] },
+        { Name: "ScreenGui", Superclass: "Instance", Members: [property("ResetOnSpawn", "bool")] },
+        { Name: "Frame", Superclass: "Instance", Members: [property("BackgroundTransparency", "float")] },
+        { Name: "TextLabel", Superclass: "Instance", Members: [property("Text", "string")] },
+      ],
+      Enums: [],
+    },
+  }),
+);
+
+const { runBuild, runExport, runSync, startWatch, stopAllWatches, stopWatch, watchState } = await import("../dist/lib/sync.js");
+const { takeNotices } = await import("../dist/lib/notices.js");
+const { fakeStudio } = await import("./sync-fake.mjs");
+
+const dir = path.join(sandbox, "work");
+const file = (relative) => path.join(dir, ...relative.split("/"));
+const read = (relative) => readFileSync(file(relative), "utf8");
+const until = async (probe, ms = 5_000) => {
+  const deadline = Date.now() + ms;
+  while (!(await probe())) {
+    if (Date.now() > deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return true;
+};
+
+try {
+  // Conflicts remember themselves -----------------------------------------
+  {
+    const studio = fakeStudio();
+    studio.scripts.set("ServerScriptService.Mod", { className: "ModuleScript", source: "return 1\n" });
+    const sync = (extra = {}) => runSync(studio, { dir, direction: "both", ...extra });
+    await sync();
+
+    writeFileSync(file("ServerScriptService/Mod.luau"), "return 'disk'\n");
+    studio.scripts.get("ServerScriptService.Mod").source = "return 'studio'\n";
+    let report = await sync();
+    assert.equal(report.conflicts.length, 1);
+    assert.equal(read(".rbx-sync/conflicts/ServerScriptService/Mod.luau"), "return 'studio'\n", "Studio's side is kept to merge from");
+    report = await sync();
+    assert.equal(report.conflicts.length, 1, "still a conflict while neither side moves");
+    assert.deepEqual(report.newConflicts, [], "but it is not new");
+
+    // Resolve on disk: the merged file wins, conditionally on Studio not having moved.
+    writeFileSync(file("ServerScriptService/Mod.luau"), "return 'merged'\n");
+    report = await sync();
+    assert.equal(report.conflicts.length, 0);
+    assert.equal(studio.scripts.get("ServerScriptService.Mod").source, "return 'merged'\n");
+    assert.ok(!existsSync(file(".rbx-sync/conflicts/ServerScriptService/Mod.luau")), "the sidecar goes when settled");
+
+    // Resolve in Studio instead.
+    writeFileSync(file("ServerScriptService/Mod.luau"), "return 'disk 2'\n");
+    studio.scripts.get("ServerScriptService.Mod").source = "return 'studio 2'\n";
+    assert.equal((await sync()).conflicts.length, 1);
+    studio.scripts.get("ServerScriptService.Mod").source = "return 'fixed in studio'\n";
+    report = await sync();
+    assert.equal(report.conflicts.length, 0);
+    assert.equal(read("ServerScriptService/Mod.luau"), "return 'fixed in studio'\n");
+    // A file outside the roots is not created (and so not re-created every run).
+    mkdirSync(file("Workspace"), { recursive: true });
+    writeFileSync(file("Workspace/Stray.luau"), "return 'stray'\n");
+    report = await sync();
+    assert.ok(![...studio.scripts.keys()].some((key) => key.startsWith("Workspace")), "outside the roots: left alone");
+    assert.equal(report.failures.length, 0);
+    rmSync(dir, { recursive: true, force: true });
+    console.log("sync conflicts: Studio's side kept beside, reported once, settled by whichever side moves");
+  }
+
+  // Build files, both ways --------------------------------------------------
+  {
+    const studio = fakeStudio();
+    studio.trees.set("StarterGui.Shop", {
+      className: "ScreenGui",
+      name: "Shop",
+      properties: { ResetOnSpawn: false },
+      children: [
+        { className: "Frame", name: "Panel", properties: { BackgroundTransparency: 0.5 }, children: [{ className: "TextLabel", name: "Title", properties: { Text: "Hello" } }] },
+      ],
+    });
+    const title = () => studio.trees.get("StarterGui.Shop").children[0].children[0].properties.Text;
+    const setFileTitle = (text) => {
+      const spec = JSON.parse(read("StarterGui/Shop.build.json"));
+      spec.children[0].children[0].properties.Text = text;
+      writeFileSync(file("StarterGui/Shop.build.json"), `${JSON.stringify(spec, null, 2)}\n`);
+    };
+    const setStudioTitle = (text) => {
+      studio.trees.get("StarterGui.Shop").children[0].children[0].properties.Text = text;
+    };
+    const sync = (extra = {}) => runSync(studio, { dir, direction: "both", ...extra });
+
+    const [exported] = await runExport(studio, { dir, direction: "both", paths: ["StarterGui.Shop"] });
+    assert.equal(exported.file, "StarterGui/Shop.build.json");
+    const first = read("StarterGui/Shop.build.json");
+    assert.ok(first.indexOf('"className"') < first.indexOf('"name"') && first.includes('"Text": "Hello"'), "canonical key order");
+    assert.equal((await sync()).lines.length, 0, "in step right after export");
+
+    setFileTitle("From file");
+    let report = await sync();
+    assert.deepEqual(report.builds, ["StarterGui/Shop.build.json"]);
+    assert.equal(title(), "From file", "file edit rebuilds the tree");
+    assert.equal((await sync()).lines.length, 0, "and settles");
+
+    setStudioTitle("From Studio");
+    report = await sync();
+    assert.equal(report.counts.export, 1);
+    assert.ok(read("StarterGui/Shop.build.json").includes('"Text": "From Studio"'), "Studio edit is written back to the file");
+
+    setFileTitle("Disk side");
+    setStudioTitle("Studio side");
+    report = await sync();
+    assert.equal(report.conflicts.length, 1, "both sides edited: a conflict");
+    assert.equal(title(), "Studio side", "the tree is not rebuilt over");
+    assert.ok(read(".rbx-sync/conflicts/StarterGui/Shop.build.json").includes("Studio side"));
+    // An explicit build refuses too, unless told the file wins.
+    report = await runBuild(studio, { dir, direction: "push" , files: ["StarterGui/Shop.build.json"] });
+    assert.equal(report.conflicts.length, 1);
+    assert.equal(title(), "Studio side");
+
+    setFileTitle("Merged");
+    report = await sync();
+    assert.equal(report.conflicts.length, 0);
+    assert.equal(title(), "Merged", "the file that moved after the conflict wins");
+    assert.ok(!existsSync(file(".rbx-sync/conflicts/StarterGui/Shop.build.json")));
+
+    setStudioTitle("Studio again");
+    report = await runBuild(studio, { dir, direction: "push", files: ["StarterGui/Shop.build.json"], prefer: "disk" });
+    assert.equal(title(), "Merged", "prefer disk rebuilds over Studio's edit");
+
+    // Renamed in the file: the old tree is replaced, not duplicated.
+    const renamed = JSON.parse(read("StarterGui/Shop.build.json"));
+    renamed.name = "Store";
+    writeFileSync(file("StarterGui/Shop.build.json"), `${JSON.stringify(renamed, null, 2)}\n`);
+    await sync({ prefer: "disk" });
+    assert.ok(studio.trees.has("StarterGui.Store") && !studio.trees.has("StarterGui.Shop"), [...studio.trees.keys()].join(","));
+    await sync();
+    renamed.name = "Shop";
+    writeFileSync(file("StarterGui/Shop.build.json"), `${JSON.stringify(renamed, null, 2)}\n`);
+    await sync({ prefer: "disk" });
+    assert.ok(studio.trees.has("StarterGui.Shop") && !studio.trees.has("StarterGui.Store"));
+    await sync();
+
+    // A tree deleted in Studio sends its unchanged file to the trash.
+    studio.trees.delete("StarterGui.Shop");
+    report = await sync();
+    assert.ok(!existsSync(file("StarterGui/Shop.build.json")));
+    const trash = readdirSync(file(".rbx-sync/trash"));
+    assert.ok(existsSync(path.join(file(".rbx-sync/trash"), trash[0], "StarterGui", "Shop.build.json")));
+    rmSync(dir, { recursive: true, force: true });
+    console.log("sync builds: export, file -> tree, tree -> file, conflict with sidecar, settle, explicit build guard, delete");
+  }
+
+  // Watch ---------------------------------------------------------------------
+  {
+    const studio = fakeStudio();
+    studio.scripts.set("ServerScriptService.Live", { className: "ModuleScript", source: "return 0\n" });
+    const { state } = await startWatch(studio, { dir, direction: "both" });
+    const scansAfterStart = studio.calls.filter((op) => op === "sync.scan").length;
+
+    writeFileSync(file("ServerScriptService/Live.luau"), "return 1\n");
+    assert.ok(await until(() => studio.scripts.get("ServerScriptService.Live").source === "return 1\n"), "file edit reaches Studio");
+    // Sync's own write comes back as a Studio edit event: it must be recognised
+    // as an echo, not answered with a second full sync.
+    assert.ok(await until(() => state.echoes >= 1), "the echo is skipped");
+    const cyclesAfterPush = state.cycles;
+
+    studio.edit("ServerScriptService.Live", "return 2\n");
+    assert.ok(await until(() => read("ServerScriptService/Live.luau") === "return 2\n"), "Studio edit reaches the file");
+    await new Promise((resolve) => setTimeout(resolve, 1_500));
+    assert.ok(state.cycles <= cyclesAfterPush + 2, `settles after a change (${state.cycles - cyclesAfterPush} syncs)`);
+    const scans = studio.calls.filter((op) => op === "sync.scan").length - scansAfterStart;
+    assert.ok(scans <= state.cycles, "Studio is scanned only when a sync runs");
+
+    // Idle: no syncs at all.
+    const idle = state.cycles;
+    await new Promise((resolve) => setTimeout(resolve, 2_500));
+    assert.equal(state.cycles, idle, "nothing changed, nothing ran");
+
+    // Studio restarts on the same place: the watch follows it.
+    studio.restart();
+    writeFileSync(file("ServerScriptService/Live.luau"), "return 'after restart'\n");
+    assert.ok(await until(() => studio.scripts.get("ServerScriptService.Live").source === "return 'after restart'\n"), "watch reattached");
+    assert.ok(takeNotices()?.includes("reconnected"), "and said so");
+
+    // A conflict while watching reaches the agent on its next reply.
+    takeNotices();
+    writeFileSync(file("ServerScriptService/Live.luau"), "return 'disk'\n");
+    studio.edit("ServerScriptService.Live", "return 'studio'\n");
+    assert.ok(await until(() => state.conflicts.length === 1), "conflict found");
+    const notice = takeNotices();
+    assert.ok(notice?.includes("conflict in ServerScriptService/Live.luau"), notice);
+    assert.equal(takeNotices(), undefined, "said once");
+    assert.ok(watchState(dir));
+    stopWatch(dir);
+    assert.equal(watchState(dir), null);
+    console.log(`sync watch: both directions, echoes skipped (${state.echoes}), idle is silent, conflicts become notices`);
+  }
+} finally {
+  stopAllWatches();
+  rmSync(sandbox, { recursive: true, force: true });
+}