@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.5

package/scripts/build-plugin.mjs

@@ -17,6 +17,19 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const sourceDir = join(root, "plugin", "src");
 const outputPath = resolve(process.argv[2] ?? join(root, "build", "StudioMCP.rbxmx"));
 
+/**
+ * The package's version, stamped into the plugin the same way the build id is.
+ *
+ * `Config.PLUGIN_VERSION` used to be a literal that someone had to remember to
+ * edit alongside package.json, and nothing checked. A release that bumped the
+ * package and not the literal shipped a plugin reporting the previous version
+ * in its own `version` and `status` output, in `list_studios`, and in the
+ * mismatch warnings the server prints when a plugin looks out of date -- which
+ * is the one place a wrong version number does real damage, because it is read
+ * as evidence about which build is running.
+ */
+const packageVersion = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+
 const NEWLINE = "\n";
 
 /**
@@ -121,6 +134,13 @@ function buildTree(dir, name) {
       // Stamped with the fingerprint of the pre-injection sources, which is
       // exactly what the server recomputes at runtime.
       source = source.replace('Config.BUILD_ID = "dev"', `Config.BUILD_ID = "${stamp}"`);
+      // The literal in the source is the fallback for anyone loading
+      // plugin/src directly through Rojo; a built plugin always carries the
+      // package's own version.
+      source = source.replace(
+        /Config\.PLUGIN_VERSION = "[^"]*"/,
+        `Config.PLUGIN_VERSION = "${packageVersion}"`,
+      );
     }
 
     if (entry.name === "init.server.luau") {

package/scripts/check-plugin.mjs

@@ -1,125 +1,172 @@
-/**
- * Compiles every plugin source file, so a broken one is caught here rather than
- * in Studio.
- *
- * This exists because the feedback loop without it is terrible. Nothing in the
- * Node build reads the Luau at all -- `build:plugin` packs the files into an
- * .rbxmx as text -- so a syntax error ships, installs, and is only discovered
- * when the user focuses Studio and the plugin fails to load. It cost two
- * sessions in one afternoon: a literal newline written into a string where an
- * escape was meant, and a closure that captured a nil global because it sat
- * above the forward declaration of the local it meant to call. The first is a
- * compile error and would have been caught instantly by this. The second is not,
- * which is why `--!strict` analysis runs too when the analyser is available:
- * an unknown global is exactly what it flags.
- *
- * Needs `luau-compile` (and ideally `luau-analyze`) on PATH, in ./tools, or
- * named by the LUAU_COMPILE / LUAU_ANALYZE environment variables. Get them from
- * https://github.com/luau-lang/luau/releases.
- *
- * Silent and exit 0 when everything compiles; prints what failed otherwise.
- *
- * Usage: node scripts/check-plugin.mjs
- */
-import { spawnSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { locateLuau, missingLuau } from "./locate-luau.mjs";
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-
-function luauFiles(directory) {
-  const found = [];
-  for (const entry of readdirSync(directory)) {
-    const path = join(directory, entry);
-    if (statSync(path).isDirectory()) found.push(...luauFiles(path));
-    else if (entry.endsWith(".luau")) found.push(path);
-  }
-  return found;
-}
-
-const compiler = locateLuau("LUAU_COMPILE", ["luau-compile.exe", "luau-compile"]);
-if (compiler === null) {
-  process.stderr.write(
-    "No luau-compile found. Put it on PATH or in ./tools, or set LUAU_COMPILE.\n" +
-      "Download: https://github.com/luau-lang/luau/releases\n",
-  );
-  process.exit(1);
-}
-
-const files = luauFiles(join(root, "plugin", "src"));
-const failures = [];
-
-for (const file of files) {
-  // --binary throws the bytecode away; only the exit status and diagnostics
-  // matter, and writing it anywhere would just be litter to clean up.
-  const result = spawnSync(compiler, ["--binary", file], { encoding: "utf8" });
-  const diagnostics = `${result.stderr ?? ""}${result.status === 0 ? "" : (result.stdout ?? "")}`.trim();
-  if (result.status !== 0 || diagnostics.length > 0) {
-    failures.push(`${file.slice(root.length + 1)}\n${diagnostics}`);
-  }
-}
-
-/*
- * One diagnostic from the analyser, deliberately.
- *
- * `LocalShadow` is reported when a name is used as a global and a local of that
- * same name is declared later in the file -- which is the shape of the bug this
- * check was written for, and is unambiguous. Running the analyser without
- * Roblox's type definitions also reports every engine global as unknown, so
- * `script`, `task`, `Color3` and friends produce hundreds of lines of noise;
- * filtering to this one diagnostic gets the signal without needing a
- * definitions file that would then have to be kept current with the engine.
- */
-/*
- * Diagnostics about a table this file declares its own type for.
- *
- * The LocalShadow filter was the only thing let through, and that let a whole
- * class of error ship: a field read or written on a `--!strict` table type that
- * does not declare it. The plugin failed to load on the first line it logged --
- * "attempt to perform arithmetic on nil" -- because a batch of edits added five
- * uses of `state.entries` and the edit declaring it never landed. The analyser
- * had said so, four times, and this script threw it away.
- *
- * These two patterns are safe to surface where the rest is not. Without Roblox
- * type definitions the analyser cannot know what `Instance` or `Color3` are, so
- * it reports engine globals in their hundreds -- but those come out as unknown
- * *globals* and unknown *types*. A key missing from a named table type can only
- * be a table this file declared itself.
- */
-const TYPE_PATTERNS = [/Key '[^']+' not found in table/, /Cannot add property '[^']+' to table/];
-
-const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
-const shadowed = [];
-const mistyped = [];
-if (analyser !== null) {
-  for (const file of files) {
-    const result = spawnSync(analyser, [file], { encoding: "utf8" });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    for (const line of output.split("\n")) {
-      if (line.includes("LocalShadow:")) shadowed.push(line.trim());
-      else if (TYPE_PATTERNS.some((pattern) => pattern.test(line))) mistyped.push(line.trim());
-    }
-  }
-}
-
-if (failures.length > 0) {
-  process.stderr.write(`${failures.join("\n\n")}\n`);
-}
-if (shadowed.length > 0) {
-  process.stderr.write(
-    "\nA local is used before it is declared, so the call reaches a nil global " +
-      "instead:\n" +
-      `${shadowed.join("\n")}\n`,
-  );
-}
-if (mistyped.length > 0) {
-  process.stderr.write(
-    "\nA field is used on a table whose type does not declare it. It is nil at " +
-      "runtime, and the plugin fails the first time that line runs:\n" +
+/**
+ * Compiles every plugin source file, so a broken one is caught here rather than
+ * in Studio.
+ *
+ * This exists because the feedback loop without it is terrible. Nothing in the
+ * Node build reads the Luau at all -- `build:plugin` packs the files into an
+ * .rbxmx as text -- so a syntax error ships, installs, and is only discovered
+ * when the user focuses Studio and the plugin fails to load. It cost two
+ * sessions in one afternoon: a literal newline written into a string where an
+ * escape was meant, and a closure that captured a nil global because it sat
+ * above the forward declaration of the local it meant to call. The first is a
+ * compile error and would have been caught instantly by this. The second is not,
+ * which is why `--!strict` analysis runs too when the analyser is available:
+ * an unknown global is exactly what it flags.
+ *
+ * Needs `luau-compile` (and ideally `luau-analyze`) on PATH, in ./tools, or
+ * named by the LUAU_COMPILE / LUAU_ANALYZE environment variables. Get them from
+ * https://github.com/luau-lang/luau/releases.
+ *
+ * Silent and exit 0 when everything compiles; prints what failed otherwise.
+ *
+ * Usage: node scripts/check-plugin.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function luauFiles(directory) {
+  const found = [];
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) found.push(...luauFiles(path));
+    else if (entry.endsWith(".luau")) found.push(path);
+  }
+  return found;
+}
+
+const compiler = locateLuau("LUAU_COMPILE", ["luau-compile.exe", "luau-compile"]);
+if (compiler === null) {
+  process.stderr.write(
+    "No luau-compile found. Put it on PATH or in ./tools, or set LUAU_COMPILE.\n" +
+      "Download: https://github.com/luau-lang/luau/releases\n",
+  );
+  process.exit(1);
+}
+
+const files = luauFiles(join(root, "plugin", "src"));
+const failures = [];
+
+for (const file of files) {
+  // --binary throws the bytecode away; only the exit status and diagnostics
+  // matter, and writing it anywhere would just be litter to clean up.
+  const result = spawnSync(compiler, ["--binary", file], { encoding: "utf8" });
+  const diagnostics = `${result.stderr ?? ""}${result.status === 0 ? "" : (result.stdout ?? "")}`.trim();
+  if (result.status !== 0 || diagnostics.length > 0) {
+    failures.push(`${file.slice(root.length + 1)}\n${diagnostics}`);
+  }
+}
+
+/*
+ * One diagnostic from the analyser, deliberately.
+ *
+ * `LocalShadow` is reported when a name is used as a global and a local of that
+ * same name is declared later in the file -- which is the shape of the bug this
+ * check was written for, and is unambiguous. Running the analyser without
+ * Roblox's type definitions also reports every engine global as unknown, so
+ * `script`, `task`, `Color3` and friends produce hundreds of lines of noise;
+ * filtering to this one diagnostic gets the signal without needing a
+ * definitions file that would then have to be kept current with the engine.
+ */
+/*
+ * Diagnostics about a table this file declares its own type for.
+ *
+ * The LocalShadow filter was the only thing let through, and that let a whole
+ * class of error ship: a field read or written on a `--!strict` table type that
+ * does not declare it. The plugin failed to load on the first line it logged --
+ * "attempt to perform arithmetic on nil" -- because a batch of edits added five
+ * uses of `state.entries` and the edit declaring it never landed. The analyser
+ * had said so, four times, and this script threw it away.
+ *
+ * These two patterns are safe to surface where the rest is not. Without Roblox
+ * type definitions the analyser cannot know what `Instance` or `Color3` are, so
+ * it reports engine globals in their hundreds -- but those come out as unknown
+ * *globals* and unknown *types*. A key missing from a named table type can only
+ * be a table this file declared itself.
+ */
+const TYPE_PATTERNS = [/Key '[^']+' not found in table/, /Cannot add property '[^']+' to table/];
+
+const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
+const shadowed = [];
+const mistyped = [];
+if (analyser !== null) {
+  for (const file of files) {
+    const result = spawnSync(analyser, [file], { encoding: "utf8" });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    for (const line of output.split("\n")) {
+      if (line.includes("LocalShadow:")) shadowed.push(line.trim());
+      else if (TYPE_PATTERNS.some((pattern) => pattern.test(line))) mistyped.push(line.trim());
+    }
+  }
+}
+
+/*
+ * Every operation the plugin answers has to have a readable name in the panel.
+ *
+ * `Phrase` falls back to tidying the wire name, so a missing entry is invisible
+ * in testing and only shows up as "Data set" where "SAVE over 4212 in PlayerData"
+ * belonged. Left unchecked it rots by default: 26 of 72 operations had drifted
+ * out of the table, which is every tool added after the table was written. A
+ * missing KIND is worse than cosmetic -- the fallback is "read", so an
+ * unregistered terrain wipe was announced with the weight of an inspect.
+ */
+const unnamed = [];
+const kindless = new Set();
+{
+  const phrase = readFileSync(join(root, "plugin", "src", "Phrase.luau"), "utf8");
+  const described = new Set([...phrase.matchAll(/\["([^"]+)"\]\s*=\s*function/g)].map((m) => m[1]));
+  const kinds = new Set([...phrase.matchAll(/^\t([a-z]+) = "/gm)].map((m) => m[1]));
+  // `script` is split by action inside Phrase.kindOf rather than by a table row.
+  kinds.add("script");
+
+  for (const file of files) {
+    const source = readFileSync(file, "utf8");
+    for (const block of source.matchAll(/Dispatch\.registerAll\("([^"]+)",\s*\{([\s\S]*?)\n\t\}\)/g)) {
+      const group = block[1];
+      if (!kinds.has(group)) kindless.add(group);
+      for (const entry of block[2].matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)) {
+        const op = `${group}.${entry[1]}`;
+        if (!described.has(op)) unnamed.push(op);
+      }
+    }
+  }
+}
+
+if (unnamed.length > 0) {
+  failures.push(
+    "These operations have no entry in Phrase.luau, so the Studio panel shows " +
+      "the wire name instead of saying what they touch:\n  " +
+      unnamed.sort().join("\n  "),
+  );
+}
+if (kindless.size > 0) {
+  failures.push(
+    "These operation groups have no entry in Phrase KINDS, so they are announced " +
+      'as "read" whatever they do:\n  ' +
+      [...kindless].sort().join("\n  "),
+  );
+}
+
+if (failures.length > 0) {
+  process.stderr.write(`${failures.join("\n\n")}\n`);
+}
+if (shadowed.length > 0) {
+  process.stderr.write(
+    "\nA local is used before it is declared, so the call reaches a nil global " +
+      "instead:\n" +
+      `${shadowed.join("\n")}\n`,
+  );
+}
+if (mistyped.length > 0) {
+  process.stderr.write(
+    "\nA field is used on a table whose type does not declare it. It is nil at " +
+      "runtime, and the plugin fails the first time that line runs:\n" +
       `${mistyped.join("\n")}
-`,
-  );
-}
-process.exit(failures.length > 0 || shadowed.length > 0 || mistyped.length > 0 ? 1 : 0);
+`,
+  );
+}
+process.exit(failures.length > 0 || shadowed.length > 0 || mistyped.length > 0 ? 1 : 0);