@el4cteo/rbx-studio-mcp 0.8.4 → 0.8.6

package/plugin/src/init.server.luau

@@ -44,6 +44,7 @@ local Device = require(script.handlers.Device)
 local Data = require(script.handlers.Data)
 local Api = require(script.handlers.Api)
 local Scripts = require(script.handlers.Scripts)
+local Sync = require(script.handlers.Sync)
 local Session = require(script.handlers.Session)
 
 local SETTING_PORT = "port"
@@ -196,6 +197,7 @@ Audio.register()
 Exec.register()
 Viewport.register()
 Scripts.register()
+Sync.register()
 Input.register()
 Device.register()
 Data.register()
@@ -580,6 +582,12 @@ Commands.setup({
 
 Console.setPromptChat(chat)
 
+-- Sync reports what it changed in the log; handed a function rather than the
+-- console itself, for the same reason `Commands` is.
+Sync.setup(function(level, message, detail)
+	Console.log(level :: any, message, detail)
+end)
+
 -- The saved preset, now that there is something to paint. Done immediately
 -- after mounting and before the first line is logged, so nothing is ever drawn
 -- in the wrong palette.
@@ -755,7 +763,30 @@ end
 	and any `*Async` call does -- and serialising them would let one slow edit
 	stall every other request on the stream.
 ]]
-local function onCommand(id: string, op: string, params: { [string]: any }?)
+--[[
+	Commands that run without a line in the log.
+
+	`sync watch` asks what changed twice a second for as long as it runs, and
+	`sync.log` exists to print a line of its own. Logging either call would bury
+	everything else the panel shows under a heartbeat nobody needs to see.
+]]
+local QUIET: { [string]: boolean } = {
+	["sync.changes"] = true,
+	["sync.log"] = true,
+	["sync.shape"] = true,
+	["sync.revisions"] = true,
+}
+
+local function onCommand(id: string, op: string, params: { [string]: any }?, deadlineMs: number?)
+	-- A sync op can also ask to be quiet: `watch` runs the same scans a manual
+	-- sync does, and logging each would print a heartbeat. What a watch
+	-- actually changes is still logged, by `sync.apply` and `sync.log`.
+	if QUIET[op] or (string.sub(op, 1, 5) == "sync." and params ~= nil and params.quiet == true) then
+		task.spawn(function()
+			Transport.sendResult(Dispatch.invoke(id, op, params, deadlineMs))
+		end)
+		return
+	end
 	task.spawn(function()
 		local startedAt = os.clock()
 		--[[
@@ -778,7 +809,7 @@ local function onCommand(id: string, op: string, params: { [string]: any }?)
 		]]
 		Console.beginCall(title, Phrase.kindOf(op))
 
-		local result = Dispatch.invoke(id, op, params)
+		local result = Dispatch.invoke(id, op, params, deadlineMs)
 		local milliseconds = (os.clock() - startedAt) * 1000
 
 		--[[

package/scripts/build.mjs

@@ -0,0 +1,14 @@
+/** Build from a clean output directory so removed tools cannot enter npm packs. */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
+const output = join(root, "dist");
+if (existsSync(output)) {
+  // Refuse junctions/symlinks outside the exact generated-output directory.
+  if (realpathSync(output) !== output) throw new Error("dist resolves outside the expected build directory");
+  rmSync(output, { recursive: true, force: true });
+}
+execFileSync(process.execPath, [join(root, "node_modules", "typescript", "bin", "tsc")], { cwd: root, stdio: "inherit" });

package/scripts/sync-fake.mjs

@@ -0,0 +1,191 @@
+/**
+ * An in-memory Studio answering the plugin's `sync.*` ops, for the offline
+ * sync tests. It keeps the plugin's contracts -- revisions, writes and moves
+ * conditional on them, per-item results, change tracking that also reports
+ * the echo of sync's own writes -- without any of its Roblox.
+ */
+import { createHash } from "node:crypto";
+import { ToolError } from "../dist/lib/errors.js";
+
+export const fingerprint = (source) => createHash("sha1").update(source).digest("hex").slice(0, 12);
+
+/** A scan from a flat map of script paths, the way the plugin reports one. */
+export function scanOf(scripts, folders = {}) {
+  const nodes = [];
+  const index = new Map();
+  const nodeOf = (segments, className) => {
+    const key = segments.join(".");
+    if (index.has(key)) return index.get(key);
+    const parent = segments.length > 1 ? nodeOf(segments.slice(0, -1), folders[segments.slice(0, -1).join(".")] ?? "Folder") : 0;
+    nodes.push({ path: key, name: segments.at(-1), className, parent });
+    index.set(key, nodes.length);
+    return nodes.length;
+  };
+  const items = [];
+  for (const [scriptPath, info] of Object.entries(scripts)) {
+    const node = nodeOf(scriptPath.split("."), info.className);
+    nodes[node - 1].className = info.className;
+    items.push({ node, revision: info.revision, fileSynced: info.fileSynced });
+  }
+  return { nodes, items, roots: [...new Set(Object.keys(scripts).map((key) => key.split(".")[0]))] };
+}
+
+/** `{value, type}` property specs back to plain values, as Studio would store them. */
+function untype(spec) {
+  const out = { className: spec.className, name: spec.name };
+  if (spec.properties) {
+    out.properties = Object.fromEntries(
+      Object.entries(spec.properties).map(([key, value]) => [key, value && typeof value === "object" && "value" in value ? value.value : value]),
+    );
+  }
+  if (spec.attributes) out.attributes = spec.attributes;
+  if (spec.tags) out.tags = spec.tags;
+  if (spec.children) out.children = spec.children.map(untype);
+  for (const key of Object.keys(out)) if (out[key] === undefined) delete out[key];
+  return out;
+}
+
+const classesIn = (spec, into = new Set()) => {
+  into.add(spec.className);
+  for (const child of spec.children ?? []) classesIn(child, into);
+  return into;
+};
+
+export function fakeStudio(placeId = 1) {
+  const scripts = new Map(); // path -> { className, source }
+  const trees = new Map(); // path -> build spec (plain values)
+  const dirty = new Set();
+  const logged = [];
+  const session = { studioId: "edit", placeId, placeName: "Test", context: "edit" };
+  const chain = (item) => [item.parentPath, ...(item.parents ?? []).map((link) => link.name)].filter(Boolean).join(".");
+  const calls = [];
+
+  const bridge = {
+    scripts,
+    trees,
+    logged,
+    calls,
+    /** Studio restarted: same place, new session id. */
+    restart() {
+      session.studioId = `${session.studioId}+`;
+    },
+    /** An edit made in Studio: tracked, as the plugin's events would. */
+    edit(path, source) {
+      scripts.get(path).source = source;
+      dirty.add(path);
+    },
+    async sessions() {
+      return { list: [session], activeId: null, activeIsChosen: false };
+    },
+    async call(op, params = {}, options = {}) {
+      calls.push(op);
+      if (options.studioId !== undefined && options.studioId !== session.studioId) {
+        throw new ToolError("UNKNOWN_STUDIO", `No connected Studio has id "${options.studioId}".`);
+      }
+      switch (op) {
+        case "sync.scan": {
+          const byPath = {};
+          for (const [key, value] of scripts) {
+            byPath[key] = { className: value.className, revision: params.revisions === false ? undefined : fingerprint(value.source) };
+          }
+          const scan = scanOf(byPath);
+          scan.roots = ["ServerScriptService", "ReplicatedStorage", "StarterGui"];
+          return scan;
+        }
+        case "sync.shape":
+          return { shape: [...scripts.keys()].sort().join("\n") };
+        case "sync.read":
+          return {
+            items: params.paths.map((key) =>
+              scripts.has(key)
+                ? { path: key, source: scripts.get(key).source, revision: fingerprint(scripts.get(key).source), className: scripts.get(key).className }
+                : { path: key, code: "NOT_FOUND", message: "gone" },
+            ),
+          };
+        case "sync.revisions":
+          return {
+            items: params.paths.map((key) =>
+              scripts.has(key) ? { path: key, revision: fingerprint(scripts.get(key).source) } : { path: key, missing: true },
+            ),
+          };
+        case "sync.changes": {
+          const out = { token: "tracking", reset: params.token !== "tracking", dirty: [...dirty], structural: false };
+          dirty.clear();
+          return out;
+        }
+        case "sync.apply": {
+          const out = { writes: [], creates: [], deletes: [], moves: [], undoStep: "MCP sync" };
+          for (const item of params.creates ?? []) {
+            const target = `${chain(item)}.${item.name}`;
+            if (scripts.has(target)) out.creates.push({ ok: false, code: "EXISTS", message: "exists" });
+            else {
+              scripts.set(target, { className: item.className, source: item.source });
+              out.creates.push({ ok: true, path: target, revision: fingerprint(item.source) });
+            }
+          }
+          for (const item of params.deletes ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.deletes.push({ ok: false, path: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              scripts.delete(item.path);
+              out.deletes.push({ ok: true, path: item.path });
+            }
+          }
+          for (const item of params.moves ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.moves.push({ ok: false, from: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              const target = `${chain(item)}.${item.name}`;
+              scripts.delete(item.path);
+              scripts.set(target, current);
+              out.moves.push({ ok: true, from: item.path, path: target });
+            }
+          }
+          for (const item of params.writes ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.writes.push({ ok: false, path: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              current.source = item.source;
+              // The plugin's editor event fires for sync's own write too.
+              dirty.add(item.path);
+              out.writes.push({ ok: true, path: item.path, revision: fingerprint(item.source) });
+            }
+          }
+          return out;
+        }
+        case "sync.classes": {
+          const spec = trees.get(params.path);
+          if (!spec) throw new ToolError("NOT_FOUND", `nothing at ${params.path}`);
+          const segments = params.path.split(".");
+          return {
+            path: params.path,
+            classes: [...classesIn(spec)].sort(),
+            chain: segments.map((name, index) => ({
+              name,
+              className: index === segments.length - 1 ? spec.className : index === 0 ? name : "Folder",
+              path: segments.slice(0, index + 1).join("."),
+            })),
+          };
+        }
+        case "sync.export": {
+          const spec = trees.get(params.path);
+          return { path: params.path, spec: structuredClone(spec), instances: classesIn(spec).size, scripts: 0, skipped: [] };
+        }
+        case "sync.build": {
+          const target = `${params.parent}.${params.spec.name ?? params.spec.className}`;
+          if (params.replaces && params.replaces !== target) trees.delete(params.replaces);
+          trees.set(target, untype(params.spec));
+          return { path: target, carried: [] };
+        }
+        case "sync.log":
+          logged.push(...params.lines);
+          return { logged: true };
+        case "sync.stop":
+          return { stopped: true };
+        default:
+          throw new Error(`fake Studio has no ${op}`);
+      }
+    },
+  };
+  return bridge;
+}

package/scripts/test-live-sync-scale.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * `sync` at scale, against a real Studio: thousands of scripts, same-named
+ * siblings, a source past the `.Source` limit -- timed, so a slowdown shows up
+ * as a number rather than as a watch that "feels laggy".
+ *
+ * Builds ServerStorage.__mcp_sync_scale and a temp folder, and removes both.
+ *
+ * Usage: node scripts/test-live-sync-scale.mjs [--scripts 2000] [--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, rmSync, 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, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? fallback : args[at + 1];
+};
+const COUNT = Number(flag("scripts", "2000"));
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const FIXTURE = "ServerStorage.__mcp_sync_scale";
+const dir = mkdtempSync(join(tmpdir(), "rbx-sync-scale-"));
+const file = (relative) => join(dir, "ServerStorage", "__mcp_sync_scale", ...relative.split("/"));
+const studioId = flag("studio-id");
+
+const client = new Client({ name: "test-live-sync-scale", 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 timings = [];
+async function call(name, params = {}) {
+  const started = performance.now();
+  const result = await client.callTool({ name, arguments: { ...(studioId ? { studioId } : {}), ...params } }, undefined, { timeout: 600_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) };
+}
+function report(label, good, detail = "") {
+  if (!good) failures += 1;
+  process.stdout.write(`${good ? "ok  " : "FAIL"}  ${label.padEnd(48)} ${detail.replace(/\s+/g, " ").slice(0, good ? 100 : 400)}\n`);
+}
+async function timed(label, name, params, expect = /./) {
+  const reply = await call(name, params);
+  timings.push([label, reply.ms]);
+  report(label, !reply.isError && expect.test(reply.text), `${reply.ms}ms  ${reply.text}`);
+  return reply;
+}
+const luau = async (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 });
+const until = async (probe, seconds = 10) => {
+  const started = Date.now();
+  for (;;) {
+    if (await probe()) return Date.now() - started;
+    if (Date.now() - started > seconds * 1000) return -1;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+};
+
+try {
+  // A place-shaped tree: 40 folders of modules with realistic bodies, two
+  // same-named siblings, and one script too long for `.Source`.
+  await luau(`
+    local old = game.ServerStorage:FindFirstChild("__mcp_sync_scale")
+    if old then old:Destroy() end
+    local fixture = Instance.new("Folder"); fixture.Name = "__mcp_sync_scale"
+    local body = string.rep("local value = math.random() * 100 -- padding to look like real code\\n", 30)
+    for f = 1, 40 do
+      local folder = Instance.new("Folder"); folder.Name = "Feature" .. f; folder.Parent = fixture
+      for s = 1, math.floor(${COUNT} / 40) do
+        local module = Instance.new("ModuleScript"); module.Name = "Module" .. s
+        module.Source = "-- " .. f .. "/" .. s .. "\\n" .. body .. "return {}\\n"
+        module.Parent = folder
+      end
+    end
+    local a = Instance.new("ModuleScript"); a.Name = "Dup"; a.Source = "return 'first'\\n"; a:SetAttribute("Which", "first"); a.Parent = fixture
+    local b = Instance.new("ModuleScript"); b.Name = "Dup"; b.Source = "return 'second'\\n"; b:SetAttribute("Which", "second"); b.Parent = fixture
+    fixture.Parent = game.ServerStorage
+    local big = Instance.new("ModuleScript"); big.Name = "Big"; big.Parent = fixture
+    game:GetService("ScriptEditorService"):UpdateSourceAsync(big, function() return string.rep("-- a long generated table row\\n", 12000) .. "return {}\\n" end)
+    return "ok"`);
+
+  await timed(`pull ${COUNT + 3} scripts`, "sync", sync("pull"), new RegExp(`${COUNT + 3} created on disk`));
+  await timed("no-op sync (nothing changed)", "sync", sync("sync"), /nothing to do/);
+  await timed("no-op sync again (revision cache warm)", "sync", sync("sync"), /nothing to do/);
+
+  writeFileSync(file("Feature7/Module3.luau"), "return 'edited'\n");
+  await timed("one file edited", "sync", sync("sync"), /1 written to Studio/);
+  const edited = await luau(`return game.ServerStorage.__mcp_sync_scale.Feature7.Module3.Source`);
+  report("the right script took it", edited.includes("edited"), edited);
+
+  // Same-named siblings: two files, each bound to its own script.
+  report("duplicate names get two files", existsSync(file("Dup.luau")) && existsSync(file("Dup~2.luau")));
+  const second = readFileSync(file("Dup~2.luau"), "utf8").includes("second") ? "Dup~2.luau" : "Dup.luau";
+  writeFileSync(file(second), "return 'second, edited'\n");
+  await timed("edit one of two same-named scripts", "sync", sync("sync"), /1 written to Studio/);
+  const which = await luau(`
+    for _, s in game.ServerStorage.__mcp_sync_scale:GetChildren() do
+      if s.Name == "Dup" and string.find(s.Source, "edited") then return s:GetAttribute("Which") end
+    end
+    return "none"`);
+  report("edit landed on the matching duplicate", which.includes("second"), which);
+
+  // Past the .Source limit: round trip through the editor path.
+  const big = readFileSync(file("Big.luau"), "utf8");
+  report("large script pulled whole", big.length > 300_000, `${big.length} chars`);
+  writeFileSync(file("Big.luau"), `${big}-- appended\n`);
+  await timed("push a 360KB script", "sync", sync("sync"), /1 written to Studio/);
+  const tail = await luau(`local s = game.ServerStorage.__mcp_sync_scale.Big.Source return string.sub(s, -12)`);
+  report("large script edit landed", tail.includes("appended"), tail);
+
+  // Watch latency at this size.
+  await timed("watch start", "sync", sync("watch"), /Watching|Already/);
+  writeFileSync(file("Feature20/Module5.luau"), "return 'watched'\n");
+  const toStudio = await until(async () => (await luau(`return game.ServerStorage.__mcp_sync_scale.Feature20.Module5.Source`)).includes("watched"));
+  timings.push(["watch: file -> Studio", toStudio]);
+  report("watch: file edit reached Studio", toStudio >= 0, `${toStudio}ms`);
+  await luau(`game:GetService("ScriptEditorService"):UpdateSourceAsync(game.ServerStorage.__mcp_sync_scale.Feature21.Module6, function() return "return 'from studio'\\n" end) return 1`);
+  const toDisk = await until(() => readFileSync(file("Feature21/Module6.luau"), "utf8").includes("from studio"));
+  timings.push(["watch: Studio -> file", toDisk]);
+  report("watch: Studio edit reached the file", toDisk >= 0, `${toDisk}ms`);
+  await new Promise((resolve) => setTimeout(resolve, 3_000));
+  const status = await call("sync", sync("status"));
+  report("watch settles: echoes skipped, not re-synced", /echo/.test(status.text), status.text.split("\n").slice(-1)[0]);
+  await call("sync", sync("stop"));
+} 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_sync_scale") if f then f:Destroy() end return 1`).catch(() => undefined);
+  rmSync(dir, { recursive: true, force: true });
+  await client.close();
+}
+
+process.stdout.write("\ntimings\n");
+for (const [label, ms] of timings) process.stdout.write(`  ${label.padEnd(44)} ${ms}ms\n`);
+process.stdout.write(failures === 0 ? "\nlive sync scale: ok\n" : `\nlive sync scale: ${failures} failure(s)\n`);
+process.exit(failures === 0 ? 0 : 1);

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