@el4cteo/rbx-studio-mcp 0.8.4 → 0.8.6

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,6 +28,15 @@ 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" },
@@ -46,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
@@ -64,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 });
+}

package/scripts/test-sync.mjs

@@ -0,0 +1,245 @@
+/**
+ * `sync`, offline: the planner on its own, then the whole engine against a
+ * real temp folder and an in-memory Studio that behaves like the plugin's
+ * sync handler (revisions, conditional writes, creates, moves, deletes).
+ *
+ * Usage: node scripts/test-sync.mjs   (after `npm run build`)
+ */
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  classFromFile,
+  decodeName,
+  emptyManifest,
+  encodeName,
+  layout,
+  placementOf,
+  plan,
+} from "../dist/lib/syncplan.js";
+import { hashOf, runSync, stopAllWatches } from "../dist/lib/sync.js";
+import { fakeStudio, scanOf } from "./sync-fake.mjs";
+
+// Names -----------------------------------------------------------------------
+
+for (const name of ["Main", "Dr. Who", "a/b\\c", "what?", "100%", "CON", "trailing.", "trailing ", "..", "", "init", "Config.server", "日本"]) {
+  for (const kind of ["dir", "script"]) {
+    const encoded = encodeName(name, kind);
+    assert.ok(!/[<>:"/\\|?*]/.test(encoded), `${JSON.stringify(name)} -> ${encoded} is file-safe`);
+    assert.ok(!/[. ]$/.test(encoded) && !/^(con|prn|aux|nul)$/i.test(encoded), `${encoded} is Windows-safe`);
+    assert.equal(decodeName(encoded), name, `${JSON.stringify(name)} round-trips as ${kind}`);
+  }
+}
+assert.equal(classFromFile(`${encodeName("Config.server", "script")}.luau`).className, "ModuleScript", "a dotted name keeps its class");
+assert.equal(classFromFile(`${encodeName("init", "script")}.luau`).init, false, "a script named init is not an init file");
+assert.deepEqual(classFromFile("Main.server.luau"), { stem: "Main", className: "Script", init: false });
+assert.deepEqual(classFromFile("init.client.lua"), { stem: "init", className: "LocalScript", init: true });
+assert.equal(classFromFile("notes.txt"), null);
+console.log("sync names: encode/decode round trips, reserved and ambiguous names");
+
+// Layout ----------------------------------------------------------------------
+
+{
+  const shape = layout(
+    scanOf({
+      "ServerScriptService.Main": { className: "Script", revision: "r1" },
+      "ServerScriptService.Main.Helper": { className: "ModuleScript", revision: "r2" },
+      "ReplicatedStorage.Shared.Util": { className: "ModuleScript", revision: "r3" },
+      "ReplicatedStorage.Shared.util": { className: "LocalScript", revision: "r4" },
+      "ReplicatedStorage.Shared.UTIL": { className: "ModuleScript", revision: "r5" },
+      "StarterGui.Bound": { className: "LocalScript", revision: "r6", fileSynced: true },
+    }),
+  );
+  assert.equal(shape.fileOf.get("ServerScriptService.Main"), "ServerScriptService/Main/init.server.luau");
+  assert.equal(shape.fileOf.get("ServerScriptService.Main.Helper"), "ServerScriptService/Main/Helper.luau");
+  assert.equal(shape.fileOf.get("ReplicatedStorage.Shared.UTIL"), "ReplicatedStorage/Shared/UTIL.luau");
+  assert.equal(shape.fileOf.get("ReplicatedStorage.Shared.Util"), "ReplicatedStorage/Shared/Util~2.luau", "case collision suffixed");
+  assert.equal(shape.fileOf.get("ReplicatedStorage.Shared.util"), "ReplicatedStorage/Shared/util.client.luau", "different extension, no collision");
+  assert.deepEqual(shape.fileSynced, ["StarterGui.Bound"]);
+  assert.equal(shape.pathOfDir.get("ReplicatedStorage/Shared"), "ReplicatedStorage.Shared");
+
+  const place = placementOf("ReplicatedStorage/Shared/New/Thing.luau", shape, () => undefined);
+  assert.deepEqual(place, { parentPath: "ReplicatedStorage.Shared", parents: [{ name: "New", className: "Folder" }], name: "Thing", className: "ModuleScript" });
+  const init = placementOf("ServerScriptService/Svc/init.server.luau", shape, () => "Script");
+  assert.deepEqual(init, { parentPath: "ServerScriptService", parents: [], name: "Svc", className: "Script" });
+  assert.ok("error" in placementOf("Loose.luau", shape, () => undefined), "files must sit inside a service folder");
+  console.log("sync layout: init folders, case collisions, Script Sync exclusions, placement");
+}
+
+// Plan ------------------------------------------------------------------------
+
+{
+  const scripts = { "ServerScriptService.A": { className: "Script", revision: "a1" }, "ServerScriptService.B": { className: "ModuleScript", revision: "b1" } };
+  const studio = layout(scanOf(scripts));
+  const inScope = () => true;
+  const manifest = emptyManifest();
+  const first = plan({ manifest, studio, disk: new Map(), inScope, direction: "both" });
+  assert.deepEqual(first.actions.map((action) => action.kind).sort(), ["create-disk", "create-disk"], "first sync pulls everything, deletes nothing");
+
+  manifest.files["ServerScriptService/A.server.luau"] = { path: "ServerScriptService.A", className: "Script", revision: "a1", hash: "ha" };
+  manifest.files["ServerScriptService/B.luau"] = { path: "ServerScriptService.B", className: "ModuleScript", revision: "b1", hash: "hb" };
+  const kinds = (input) => plan({ manifest, inScope, direction: "both", ...input }).actions.map((action) => `${action.kind} ${action.file}`).sort();
+
+  const same = new Map([["ServerScriptService/A.server.luau", "ha"], ["ServerScriptService/B.luau", "hb"]]);
+  assert.deepEqual(kinds({ studio, disk: same }), [], "in step: nothing to do");
+  assert.deepEqual(kinds({ studio, disk: new Map([...same, ["ServerScriptService/A.server.luau", "ha2"]]) }), ["push ServerScriptService/A.server.luau"]);
+  const edited = layout(scanOf({ ...scripts, "ServerScriptService.A": { className: "Script", revision: "a2" } }));
+  assert.deepEqual(kinds({ studio: edited, disk: same }), ["pull ServerScriptService/A.server.luau"]);
+  assert.deepEqual(kinds({ studio: edited, disk: new Map([...same, ["ServerScriptService/A.server.luau", "ha2"]]) }), ["merge ServerScriptService/A.server.luau"]);
+
+  // Renamed on disk: same hash under a new name moves the script.
+  const renamedOnDisk = new Map([["ServerScriptService/Alpha.server.luau", "ha"], ["ServerScriptService/B.luau", "hb"]]);
+  assert.deepEqual(kinds({ studio, disk: renamedOnDisk }), ["move-studio ServerScriptService/Alpha.server.luau"]);
+  // Renamed in Studio: same revision at a new path moves the file.
+  const renamedInStudio = layout(scanOf({ "ServerScriptService.Alpha": { className: "Script", revision: "a1" }, "ServerScriptService.B": scripts["ServerScriptService.B"] }));
+  assert.deepEqual(kinds({ studio: renamedInStudio, disk: same }), ["move-disk ServerScriptService/Alpha.server.luau"]);
+
+  // Deleted on one side, untouched on the other: delete on the other.
+  assert.deepEqual(kinds({ studio, disk: new Map([["ServerScriptService/B.luau", "hb"]]) }), ["delete-studio ServerScriptService/A.server.luau"]);
+  const withoutA = layout(scanOf({ "ServerScriptService.B": scripts["ServerScriptService.B"] }));
+  assert.deepEqual(kinds({ studio: withoutA, disk: same }), ["delete-disk ServerScriptService/A.server.luau"]);
+  // Deleted on one side, edited on the other: conflict, unless told who wins.
+  assert.deepEqual(kinds({ studio: withoutA, disk: new Map([...same, ["ServerScriptService/A.server.luau", "ha2"]]) }), ["conflict ServerScriptService/A.server.luau"]);
+  assert.deepEqual(
+    plan({ manifest, inScope, direction: "both", prefer: "disk", studio: withoutA, disk: new Map([...same, ["ServerScriptService/A.server.luau", "ha2"]]) }).actions.map((a) => a.kind),
+    ["create-studio"],
+  );
+  // Gone from both: forget.
+  assert.deepEqual(kinds({ studio: withoutA, disk: new Map([["ServerScriptService/B.luau", "hb"]]) }), ["forget ServerScriptService/A.server.luau"]);
+  // Direction holds the other side's changes back rather than dropping them.
+  const pushOnly = plan({ manifest, inScope, direction: "push", studio: edited, disk: same });
+  assert.equal(pushOnly.actions.length, 0);
+  assert.deepEqual(pushOnly.held.map((action) => action.kind), ["pull"]);
+  // Out of scope entries are ignored, never deleted.
+  assert.deepEqual(plan({ manifest, inScope: () => false, direction: "both", studio: layout(scanOf({})), disk: new Map() }).actions, []);
+  console.log("sync plan: first sync, push, pull, merge, renames both ways, deletes, conflicts, direction, scope");
+}
+
+// Engine ----------------------------------------------------------------------
+
+const dir = mkdtempSync(path.join(tmpdir(), "rbx-sync-test-"));
+const file = (relative) => path.join(dir, ...relative.split("/"));
+const read = (relative) => readFileSync(file(relative), "utf8");
+const studio = fakeStudio();
+studio.scripts.set("ServerScriptService.Main", { className: "Script", source: 'print("hi")\n' });
+studio.scripts.set("ServerScriptService.Main.Helper", { className: "ModuleScript", source: "return {}\n" });
+studio.scripts.set("StarterGui.Shop.Client", { className: "LocalScript", source: "-- client\n" });
+const sync = (extra = {}) => runSync(studio, { dir, direction: "both", ...extra });
+
+try {
+  // First pull writes everything, the Rojo way.
+  let report = await sync();
+  assert.equal(report.counts["create-disk"], 3);
+  assert.equal(read("ServerScriptService/Main/init.server.luau"), 'print("hi")\n');
+  assert.equal(read("ServerScriptService/Main/Helper.luau"), "return {}\n");
+  assert.equal(read("StarterGui/Shop/Client.client.luau"), "-- client\n");
+  assert.ok(existsSync(file(".rbx-sync/manifest.json")) && read(".rbx-sync/.gitignore") === "*\n");
+  assert.equal((await sync()).lines.length, 0, "a second run is a no-op");
+
+  // Edit a file (with CRLF, as some editors save): it reaches Studio as LF.
+  writeFileSync(file("ServerScriptService/Main/Helper.luau"), "return { answer = 42 }\r\n");
+  report = await sync();
+  assert.equal(report.counts.push, 1);
+  assert.equal(studio.scripts.get("ServerScriptService.Main.Helper").source, "return { answer = 42 }\n");
+
+  // Edit in Studio: it reaches the file.
+  studio.scripts.get("StarterGui.Shop.Client").source = "-- client v2\n";
+  report = await sync();
+  assert.equal(report.counts.pull, 1);
+  assert.equal(read("StarterGui/Shop/Client.client.luau"), "-- client v2\n");
+
+  // New file on disk, in a new folder: created in Studio.
+  mkdirSync(file("ReplicatedStorage/Shared"), { recursive: true });
+  writeFileSync(file("ReplicatedStorage/Shared/Util.luau"), "return 1\n");
+  report = await sync();
+  assert.equal(report.counts["create-studio"], 1);
+  assert.equal(studio.scripts.get("ReplicatedStorage.Shared.Util").source, "return 1\n");
+
+  // Both sides edited: a conflict, and neither side is touched.
+  writeFileSync(file("ReplicatedStorage/Shared/Util.luau"), "return 2\n");
+  studio.scripts.get("ReplicatedStorage.Shared.Util").source = "return 3\n";
+  report = await sync();
+  assert.equal(report.conflicts.length, 1);
+  assert.equal(read("ReplicatedStorage/Shared/Util.luau"), "return 2\n");
+  assert.equal(studio.scripts.get("ReplicatedStorage.Shared.Util").source, "return 3\n");
+  // ...and the same text on both sides settles it without asking.
+  writeFileSync(file("ReplicatedStorage/Shared/Util.luau"), "return 3\n");
+  report = await sync();
+  assert.equal(report.conflicts.length, 0);
+  assert.equal((await sync()).lines.length, 0);
+  // prefer settles a real conflict in one direction.
+  writeFileSync(file("ReplicatedStorage/Shared/Util.luau"), "return 4\n");
+  studio.scripts.get("ReplicatedStorage.Shared.Util").source = "return 5\n";
+  report = await sync({ prefer: "disk" });
+  assert.equal(studio.scripts.get("ReplicatedStorage.Shared.Util").source, "return 4\n");
+
+  // Rename on disk: the script moves, it is not recreated.
+  const moved = studio.scripts.get("ReplicatedStorage.Shared.Util");
+  renameSync(file("ReplicatedStorage/Shared/Util.luau"), file("ReplicatedStorage/Shared/Tools.luau"));
+  report = await sync();
+  assert.equal(report.counts["move-studio"], 1);
+  assert.equal(studio.scripts.get("ReplicatedStorage.Shared.Tools"), moved, "same instance, new name");
+  assert.ok(!studio.scripts.has("ReplicatedStorage.Shared.Util"));
+
+  // Rename in Studio: the file moves.
+  studio.scripts.set("StarterGui.Shop.ShopClient", studio.scripts.get("StarterGui.Shop.Client"));
+  studio.scripts.delete("StarterGui.Shop.Client");
+  report = await sync();
+  assert.equal(report.counts["move-disk"], 1);
+  assert.ok(existsSync(file("StarterGui/Shop/ShopClient.client.luau")) && !existsSync(file("StarterGui/Shop/Client.client.luau")));
+
+  // Deleted in Studio: the file goes to the trash, not away.
+  studio.scripts.delete("StarterGui.Shop.ShopClient");
+  report = await sync();
+  assert.equal(report.counts["delete-disk"], 1);
+  assert.ok(!existsSync(file("StarterGui/Shop/ShopClient.client.luau")));
+  assert.ok(!existsSync(file("StarterGui/Shop")), "emptied folders are pruned");
+  const trashRuns = readdirSync(file(".rbx-sync/trash"));
+  assert.equal(read(`.rbx-sync/trash/${trashRuns[0]}/StarterGui/Shop/ShopClient.client.luau`), "-- client v2\n");
+
+  // Deleted on disk: the script is deleted in Studio.
+  unlinkSync(file("ReplicatedStorage/Shared/Tools.luau"));
+  report = await sync();
+  assert.equal(report.counts["delete-studio"], 1);
+  assert.ok(!studio.scripts.has("ReplicatedStorage.Shared.Tools"));
+
+  // Push holds Studio's changes back and says so.
+  studio.scripts.get("ServerScriptService.Main").source = 'print("studio")\n';
+  report = await sync({ direction: "push" });
+  assert.equal(report.held.length, 1);
+  assert.equal(read("ServerScriptService/Main/init.server.luau"), 'print("hi")\n');
+  await sync();
+  assert.equal(read("ServerScriptService/Main/init.server.luau"), 'print("studio")\n');
+
+  // Dry run changes nothing.
+  writeFileSync(file("ServerScriptService/Main/Helper.luau"), "return 'dry'\n");
+  report = await sync({ dryRun: true });
+  assert.equal(report.counts.push, 1);
+  assert.notEqual(studio.scripts.get("ServerScriptService.Main.Helper").source, "return 'dry'\n");
+  await sync();
+
+  // Another place is refused outright.
+  const other = fakeStudio(2);
+  await assert.rejects(runSync(other, { dir, direction: "both" }), /PLACE_MISMATCH|synced with place/);
+
+  // Deleting most of what is tracked stops and asks.
+  const big = mkdtempSync(path.join(tmpdir(), "rbx-sync-big-"));
+  const bigStudio = fakeStudio(3);
+  for (let index = 0; index < 20; index += 1) bigStudio.scripts.set(`ServerScriptService.S${index}`, { className: "ModuleScript", source: `return ${index}\n` });
+  await runSync(bigStudio, { dir: big, direction: "both" });
+  rmSync(path.join(big, "ServerScriptService"), { recursive: true });
+  await assert.rejects(runSync(bigStudio, { dir: big, direction: "both" }), /would delete 20/);
+  assert.equal(bigStudio.scripts.size, 20, "nothing was deleted");
+  const confirmed = await runSync(bigStudio, { dir: big, direction: "both", confirmDeletes: true });
+  assert.equal(confirmed.counts["delete-studio"], 20);
+  rmSync(big, { recursive: true, force: true });
+
+  assert.ok(studio.logged.some((line) => line.message.startsWith("sync to files")), "disk-side work is reported in the panel");
+  console.log("sync engine: pull, push (CRLF), create, conflicts, prefer, renames, trash, prune, direction, dry run, place and mass-delete guards");
+} finally {
+  stopAllWatches();
+  rmSync(dir, { recursive: true, force: true });
+}
+
+assert.equal(hashOf("a\r\nb"), hashOf("a\nb"));