@el4cteo/rbx-studio-mcp 0.1.0

package/dist/lib/apidump.js

@@ -0,0 +1,269 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Live Roblox API reflection, sourced from the official API dump.
+ *
+ * Every other Studio MCP server hardcodes a property list per class, which goes
+ * stale the moment Roblox ships an engine update — the agent then gets told a
+ * real property "does not exist". Here the dump is downloaded once a day and
+ * cached, so property enumeration, validation and "did you mean" suggestions
+ * track whatever engine version the user is actually running.
+ *
+ * Doing this on the Node side rather than in the plugin keeps it off Studio's
+ * HTTP permission prompt and lets the cache survive Studio restarts.
+ */
+/** Mirror of the dump Roblox publishes for each Studio build, updated per release. */
+const DUMP_URL = "https://raw.githubusercontent.com/MaximumADHD/Roblox-Client-Tracker/roblox/API-Dump.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+let loaded = null;
+const propertyCache = new Map();
+function cachePath() {
+    return join(tmpdir(), "roblox-studio-mcp", "api-dump.json");
+}
+async function readCache() {
+    try {
+        const raw = await readFile(cachePath(), "utf8");
+        const cached = JSON.parse(raw);
+        if (Date.now() - cached.fetchedAt > CACHE_TTL_MS)
+            return null;
+        return cached.dump;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(dump) {
+    try {
+        const path = cachePath();
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, JSON.stringify({ fetchedAt: Date.now(), dump }), "utf8");
+    }
+    catch {
+        // A read-only or full temp directory only costs us the cache, not the feature.
+    }
+}
+/**
+ * Returns the API dump, or null if it cannot be obtained.
+ *
+ * Null is a supported state, not a failure: the server must keep working
+ * offline, so callers fall back to whatever the plugin reports about an
+ * instance rather than refusing to answer.
+ */
+export function loadApiDump() {
+    loaded ??= (async () => {
+        const cached = await readCache();
+        if (cached)
+            return cached;
+        try {
+            const response = await fetch(DUMP_URL, {
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok)
+                return null;
+            const dump = (await response.json());
+            await writeCache(dump);
+            return dump;
+        }
+        catch {
+            // Stale beats absent: fall back to an expired cache when the network is
+            // unavailable, since engine APIs change slowly.
+            try {
+                const raw = await readFile(cachePath(), "utf8");
+                return JSON.parse(raw).dump;
+            }
+            catch {
+                return null;
+            }
+        }
+    })();
+    return loaded;
+}
+function isReadable(member) {
+    if (member.MemberType !== "Property")
+        return false;
+    const security = member.Security;
+    const read = typeof security === "string" ? security : security?.Read;
+    // PluginSecurity is fine — the plugin runs with it. Anything higher is not
+    // reachable from a plugin and would just produce errors if we offered it.
+    if (read && read !== "None" && read !== "PluginSecurity")
+        return false;
+    // Only `NotScriptable` actually blocks Luau access. `Hidden` means "not
+    // serialized / not shown in the Properties widget", which is true of
+    // BasePart.Position and .Orientation — both derived from CFrame, both
+    // perfectly scriptable, and both among the properties agents reach for most.
+    // Filtering on `Hidden` would silently hide them.
+    return !(member.Tags ?? []).includes("NotScriptable");
+}
+/**
+ * Every readable property of a class, walking the inheritance chain. Ordered
+ * most-derived first so callers can take a prefix and get the properties that
+ * actually characterise the instance.
+ */
+export async function propertiesOf(className) {
+    const cached = propertyCache.get(className);
+    if (cached)
+        return cached;
+    const dump = await loadApiDump();
+    if (!dump)
+        return [];
+    const byName = new Map(dump.Classes.map((entry) => [entry.Name, entry]));
+    const properties = [];
+    const seen = new Set();
+    let current = byName.get(className);
+    while (current) {
+        for (const member of current.Members) {
+            if (!isReadable(member) || seen.has(member.Name))
+                continue;
+            seen.add(member.Name);
+            const tags = member.Tags ?? [];
+            properties.push({
+                name: member.Name,
+                valueType: member.ValueType?.Name ?? "unknown",
+                category: member.ValueType?.Category ?? "unknown",
+                declaredBy: current.Name,
+                readOnly: tags.includes("ReadOnly"),
+                deprecated: tags.includes("Deprecated"),
+            });
+        }
+        current = current.Superclass ? byName.get(current.Superclass) : undefined;
+    }
+    propertyCache.set(className, properties);
+    return properties;
+}
+/** Bases that describe every instance and so distinguish none of them. */
+const GENERIC_BASES = new Set(["Instance", "PVInstance"]);
+/** Ceiling for `standard`, so wide classes like Humanoid stay affordable. */
+const STANDARD_LIMIT = 25;
+/**
+ * Properties that lead, when the class has them.
+ *
+ * The dump lists members alphabetically, so a plain prefix of `BasePart` would
+ * cut off at `Reflectance` and lose Size, Position and Transparency — the three
+ * an agent reaches for most. This is the one place a curated list is worth its
+ * maintenance cost; everything after it still comes straight from the dump, so
+ * new engine properties appear without a code change.
+ */
+const PRIORITY_PROPERTIES = [
+    "Size",
+    "Position",
+    "CFrame",
+    "Orientation",
+    "Rotation",
+    "Anchored",
+    "CanCollide",
+    "Transparency",
+    "Color",
+    "BrickColor",
+    "Material",
+    "Shape",
+    "Visible",
+    "Enabled",
+    "Disabled",
+    "Text",
+    "Value",
+    "Source",
+    "Image",
+    "MeshId",
+    "SoundId",
+    "Health",
+    "MaxHealth",
+    "WalkSpeed",
+    "PrimaryPart",
+    "RunContext",
+];
+/** Sorts priority names first (in listed order), leaving the rest untouched. */
+function rankProperties(names) {
+    const rank = new Map(PRIORITY_PROPERTIES.map((name, index) => [name, index]));
+    return [...names].sort((a, b) => {
+        const left = rank.get(a) ?? Number.MAX_SAFE_INTEGER;
+        const right = rank.get(b) ?? Number.MAX_SAFE_INTEGER;
+        if (left !== right)
+            return left - right;
+        return 0; // ties keep dump order, which is most-derived class first
+    });
+}
+/**
+ * The properties worth showing at `detail: "standard"`.
+ *
+ * Heuristic: everything the class and its non-generic bases declare — for a
+ * Part that is `Shape` plus all of `BasePart` (Size, Anchored, CFrame,
+ * Material...), which is exactly what an agent needs to reason about it.
+ * `Instance` itself is skipped because `Archivable` and `Parent` say nothing
+ * about a specific instance, and the path already encodes the parent.
+ *
+ * Deprecated and read-only entries are dropped: an agent cannot act on them,
+ * and `detail: "full"` is there when the whole surface is genuinely wanted.
+ */
+export async function standardProperties(className) {
+    const all = await propertiesOf(className);
+    if (all.length === 0)
+        return [];
+    const useful = all.filter((property) => !GENERIC_BASES.has(property.declaredBy) && !property.deprecated && !property.readOnly);
+    // Classes that add nothing of their own (Folder, Model) fall back to the full
+    // set, minus the noise, rather than returning just the name.
+    const chosen = useful.length > 0 ? useful : all.filter((p) => !p.deprecated && !p.readOnly);
+    const ranked = rankProperties(chosen.map((property) => property.name));
+    const names = ranked.slice(0, STANDARD_LIMIT);
+    return ["Name", ...names.filter((name) => name !== "Name")];
+}
+/** True when the dump knows this class. False also covers "dump unavailable". */
+export async function isKnownClass(className) {
+    const dump = await loadApiDump();
+    return dump?.Classes.some((entry) => entry.Name === className) ?? false;
+}
+/**
+ * Suggests real property names close to a mistyped one. Turns a dead-end
+ * "property does not exist" into a correction the agent can apply immediately.
+ */
+export async function suggestProperty(className, attempted) {
+    const all = await propertiesOf(className);
+    const target = attempted.toLowerCase();
+    return all
+        .map((property) => ({
+        name: property.name,
+        distance: editDistance(target, property.name.toLowerCase()),
+    }))
+        .filter((entry) => entry.distance <= Math.max(2, Math.floor(target.length / 3)))
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, 5)
+        .map((entry) => entry.name);
+}
+/** Suggests real class names close to a mistyped one, for `create`. */
+export async function suggestClass(attempted) {
+    const dump = await loadApiDump();
+    if (!dump)
+        return [];
+    const target = attempted.toLowerCase();
+    return dump.Classes.map((entry) => ({
+        name: entry.Name,
+        distance: editDistance(target, entry.Name.toLowerCase()),
+    }))
+        .filter((entry) => entry.distance <= Math.max(2, Math.floor(target.length / 3)))
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, 5)
+        .map((entry) => entry.name);
+}
+/** Levenshtein distance, two-row variant. Inputs here are short identifiers. */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let current = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        current[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            const deletion = previous[j] + 1;
+            const insertion = current[j - 1] + 1;
+            current[j] = Math.min(substitution, deletion, insertion);
+        }
+        [previous, current] = [current, previous];
+    }
+    return previous[b.length];
+}
+//# sourceMappingURL=apidump.js.map

package/dist/lib/apidump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apidump.js","sourceRoot":"","sources":["../../src/lib/apidump.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors.js

@@ -0,0 +1,38 @@
+/**
+ * Error whose message is written for an agent, not a human log reader: it says
+ * what failed and what to try next, because that is the only feedback channel
+ * the model has for learning correct tool usage.
+ */
+export class ToolError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(hint ? `${message}\n${hint}` : message);
+        this.name = "ToolError";
+        this.code = code;
+        this.hint = hint;
+    }
+    static fromCommandError(error) {
+        return new ToolError(error.code, error.message, error.hint);
+    }
+}
+export const NO_STUDIO = () => new ToolError("NO_STUDIO", "No Roblox Studio instance is connected to this MCP server.", "Open Roblox Studio, install the companion plugin, and make sure it is enabled " +
+    "(Plugins tab -> Studio MCP -> Connect). If the plugin asks for permission to " +
+    "reach 127.0.0.1, accept it. Then retry.");
+export const AMBIGUOUS_STUDIO = (names) => new ToolError("AMBIGUOUS_STUDIO", `${names.length} Studio instances are connected and the user has not said ` +
+    "which one to work in.", "Ask the user which place they mean, then call set_active_studio with its " +
+    `studioId. Connected now: ${names.join("; ")}. To act on one place without ` +
+    "changing the default, pass `studioId` to the tool directly.");
+export const TIMEOUT = (op, ms) => new ToolError("TIMEOUT", `Studio did not answer "${op}" within ${ms}ms.`, "Studio is usually busy compiling, mid-playtest, or blocked on a modal dialog. " +
+    "Call studio_status to check, then retry. If the work is genuinely long, " +
+    "run it through execute_luau with your own coroutine instead.");
+export const DISCONNECTED = () => new ToolError("DISCONNECTED", "The Studio connection dropped while the request was in flight.", "Studio was closed, the place was switched, or the plugin was disabled. " +
+    "Call studio_status to confirm a live connection, then retry the request.");
+/** Wraps unknown throwables so every tool boundary reports the same shape. */
+export function toToolError(cause) {
+    if (cause instanceof ToolError)
+        return cause;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new ToolError("INTERNAL", message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAS;IACb,IAAI,CAAqB;IAElC,YAAY,IAAY,EAAE,OAAe,EAAE,IAAa;QACtD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,KAAmB;QACzC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,GAAc,EAAE,CACvC,IAAI,SAAS,CACX,WAAW,EACX,4DAA4D,EAC5D,gFAAgF;IAC9E,+EAA+E;IAC/E,yCAAyC,CAC5C,CAAC;AAEJ,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAe,EAAa,EAAE,CAC7D,IAAI,SAAS,CACX,kBAAkB,EAClB,GAAG,KAAK,CAAC,MAAM,4DAA4D;IACzE,uBAAuB,EACzB,2EAA2E;IACzE,4BAA4B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC;IAC5E,6DAA6D,CAChE,CAAC;AAEJ,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAE,EAAU,EAAa,EAAE,CAC3D,IAAI,SAAS,CACX,SAAS,EACT,0BAA0B,EAAE,YAAY,EAAE,KAAK,EAC/C,gFAAgF;IAC9E,0EAA0E;IAC1E,8DAA8D,CACjE,CAAC;AAEJ,MAAM,CAAC,MAAM,YAAY,GAAG,GAAc,EAAE,CAC1C,IAAI,SAAS,CACX,cAAc,EACd,gEAAgE,EAChE,yEAAyE;IACvE,0EAA0E,CAC7E,CAAC;AAEJ,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/lib/format.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+/**
+ * Hard ceiling on a single tool response, in characters (~6k tokens). Roblox
+ * data models routinely run to tens of thousands of instances, so an unbounded
+ * response can blow an agent's whole context on one call. Everything that can
+ * grow is paged instead of truncated silently.
+ */
+export const CHARACTER_LIMIT = 25_000;
+/** Default page size for list-shaped results, tuned to stay well under the cap. */
+export const DEFAULT_PAGE_SIZE = 100;
+export const MAX_PAGE_SIZE = 500;
+export const detailSchema = z
+    .enum(["concise", "standard", "full"])
+    .default("standard")
+    .describe("How much to return per item. 'concise' = name + class only, cheapest, use " +
+    "when scanning or counting. 'standard' = the properties that matter for most " +
+    "edits. 'full' = every readable property, expensive — use only after you have " +
+    "narrowed to a handful of instances.");
+export const cursorSchema = z
+    .string()
+    .optional()
+    .describe("Opaque cursor from a previous call's `nextCursor`. Omit for the first page.");
+export const limitSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_PAGE_SIZE)
+    .default(DEFAULT_PAGE_SIZE)
+    .describe(`Maximum items to return (1-${MAX_PAGE_SIZE}).`);
+/**
+ * Cursors are just offsets. They are encoded so callers treat them as opaque
+ * and pass them back verbatim instead of doing arithmetic on a number whose
+ * meaning may change.
+ */
+export const encodeCursor = (offset) => Buffer.from(String(offset)).toString("base64url");
+export function decodeCursor(cursor) {
+    if (!cursor)
+        return 0;
+    const parsed = Number.parseInt(Buffer.from(cursor, "base64url").toString("utf8"), 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+export function text(body) {
+    return { content: [{ type: "text", text: body }] };
+}
+/**
+ * An image the model can actually look at, with a line of text alongside it.
+ *
+ * The caption is not decoration: an image arrives with no path, no size and no
+ * indication of which of several Studio windows it came from, and none of that
+ * is recoverable from the pixels.
+ */
+export function image(data, caption, mimeType = "image/png") {
+    return {
+        content: [
+            { type: "image", data, mimeType },
+            { type: "text", text: caption },
+        ],
+    };
+}
+export function errorText(body) {
+    return { content: [{ type: "text", text: body }], isError: true };
+}
+/**
+ * The rendered text of a result, for composing one helper's output into another.
+ *
+ * Results can now carry an image, so reading `content[0].text` is no longer
+ * always meaningful. Callers that stitch tables together want the text and
+ * nothing else, which is exactly what this returns.
+ */
+export function textOf(result) {
+    return result.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+}
+/**
+ * Renders a page of records as JSON plus a short trailer telling the agent
+ * whether anything was left behind and how to reach it. The trailer is the
+ * point: a bare truncated array reads as a complete answer and the agent
+ * confidently reports the wrong total.
+ */
+export function page(items, meta = {}) {
+    const parts = [];
+    let body = JSON.stringify(items, null, 2);
+    if (body.length > CHARACTER_LIMIT) {
+        const kept = fitToLimit(items, CHARACTER_LIMIT - 500);
+        body = JSON.stringify(kept, null, 2);
+        parts.push(body);
+        parts.push(`\n[${items.length - kept.length} of ${items.length} items dropped: the page ` +
+            `exceeded the ${CHARACTER_LIMIT}-character response limit. Re-run with a ` +
+            `smaller \`limit\`, or with \`detail: "concise"\` to fit more per page.]`);
+    }
+    else {
+        parts.push(body);
+    }
+    if (meta.total !== undefined && meta.total > items.length) {
+        parts.push(`\n[showing ${items.length} of ${meta.total} matches]`);
+    }
+    if (meta.nextCursor) {
+        parts.push(`\n[more results available — call again with cursor: "${meta.nextCursor}"]`);
+    }
+    if (meta.more)
+        parts.push(`\n[${meta.more}]`);
+    return text(parts.join(""));
+}
+/**
+ * Renders a list of uniform records as a pipe-delimited table.
+ *
+ * A hierarchy listing pretty-printed as JSON spends five lines and a dozen
+ * punctuation tokens per instance to repeat the same three keys. One header
+ * plus one line per row carries the same information for roughly a quarter of
+ * the tokens, and reads better in a transcript. `json` is still the right
+ * choice for nested or heterogeneous data.
+ */
+export function table(columns, rows, meta = {}) {
+    if (rows.length === 0) {
+        return text(meta.more ?? "No matches.");
+    }
+    const render = (row) => columns.map((column) => formatCell(row[column])).join(" | ");
+    const lines = [columns.join(" | ")];
+    let used = lines[0].length;
+    let dropped = 0;
+    for (const row of rows) {
+        const line = render(row);
+        if (used + line.length + 1 > CHARACTER_LIMIT - 500) {
+            dropped = rows.length - (lines.length - 1);
+            break;
+        }
+        lines.push(line);
+        used += line.length + 1;
+    }
+    const trailer = [];
+    if (dropped > 0) {
+        trailer.push(`[${dropped} rows dropped to stay under the ${CHARACTER_LIMIT}-character ` +
+            `response limit — re-run with a smaller \`limit\`]`);
+    }
+    if (meta.total !== undefined && meta.total > rows.length) {
+        trailer.push(`[showing ${rows.length} of ${meta.total} matches]`);
+    }
+    if (meta.nextCursor) {
+        trailer.push(`[more results — call again with cursor: "${meta.nextCursor}"]`);
+    }
+    if (meta.more)
+        trailer.push(`[${meta.more}]`);
+    return text([...lines, ...(trailer.length > 0 ? ["", ...trailer] : [])].join("\n"));
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+/** Greedily keeps the longest prefix of `items` that serialises under `budget`. */
+function fitToLimit(items, budget) {
+    const kept = [];
+    let used = 2; // the enclosing brackets
+    for (const item of items) {
+        const cost = JSON.stringify(item, null, 2).length + 2;
+        if (used + cost > budget)
+            break;
+        used += cost;
+        kept.push(item);
+    }
+    return kept;
+}
+/**
+ * Emits a plain text body, clipping at the character limit with an explicit
+ * marker. Used for source listings, where the content is already line-oriented
+ * and reflowing it into JSON would only add escaping noise.
+ */
+export function body(content, advice) {
+    if (content.length <= CHARACTER_LIMIT)
+        return text(content);
+    return text(`${content.slice(0, CHARACTER_LIMIT)}\n\n[clipped at ${CHARACTER_LIMIT} characters — ${advice}]`);
+}
+/**
+ * Renders arbitrary structured data, clipping at the character limit with an
+ * explicit marker so the agent never mistakes a clipped blob for the whole one.
+ */
+export function json(value, note) {
+    let body = JSON.stringify(value, null, 2);
+    if (body.length > CHARACTER_LIMIT) {
+        body =
+            body.slice(0, CHARACTER_LIMIT) +
+                `\n\n[response clipped at ${CHARACTER_LIMIT} characters — narrow the request ` +
+                `(fewer paths, lower depth, or detail: "concise") to see the rest]`;
+    }
+    return text(note ? `${body}\n\n${note}` : body);
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAIjC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;KACrC,OAAO,CAAC,UAAU,CAAC;KACnB,QAAQ,CACP,4EAA4E;IAC1E,8EAA8E;IAC9E,+EAA+E;IAC/E,qCAAqC,CACxC,CAAC;AAEJ,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CACP,6EAA6E,CAC9E,CAAC;AAEJ,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,aAAa,CAAC;KAClB,OAAO,CAAC,iBAAiB,CAAC;KAC1B,QAAQ,CAAC,8BAA8B,aAAa,IAAI,CAAC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAU,EAAE,CACrD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAEpD,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IACtB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IACtF,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAWD,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAAe,EAAE,QAAQ,GAAG,WAAW;IACzE,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE;SAChC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,MAAkB;IACvC,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,IAAI,EAA0C,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;SAC9E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;SACxB,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,KAAgB,EAAE,IAAI,GAAa,EAAE;IACxD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE1C,IAAI,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,CAAC;QACtD,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,KAAK,CAAC,IAAI,CACR,MAAM,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,2BAA2B;YAC5E,gBAAgB,eAAe,2CAA2C;YAC1E,yEAAyE,CAC5E,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,MAAM,OAAO,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CACR,wDAAwD,IAAI,CAAC,UAAU,IAAI,CAC5E,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CACnB,OAAiB,EACjB,IAAoC,EACpC,IAAI,GAAa,EAAE;IAEnB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAA4B,EAAU,EAAE,CACtD,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAE/D,MAAM,KAAK,GAAa,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC;IAC5B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,eAAe,GAAG,GAAG,EAAE,CAAC;YACnD,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC3C,MAAM;QACR,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CACV,IAAI,OAAO,mCAAmC,eAAe,aAAa;YACxE,mDAAmD,CACtD,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,4CAA4C,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,mFAAmF;AACnF,SAAS,UAAU,CAAC,KAAgB,EAAE,MAAc;IAClD,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,yBAAyB;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACtD,IAAI,IAAI,GAAG,IAAI,GAAG,MAAM;YAAE,MAAM;QAChC,IAAI,IAAI,IAAI,CAAC;QACb,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,MAAc;IAClD,IAAI,OAAO,CAAC,MAAM,IAAI,eAAe;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,IAAI,CACT,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,mBAAmB,eAAe,iBAAiB,MAAM,GAAG,CACjG,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,KAAc,EAAE,IAAa;IAChD,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QAClC,IAAI;YACF,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;gBAC9B,4BAA4B,eAAe,mCAAmC;gBAC9E,mEAAmE,CAAC;IACxE,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/lib/pluginbuild.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Fingerprint of the Luau sources this server package ships.
+ *
+ * Roblox Studio only reloads a plugin when it next takes focus, so a developer
+ * who rebuilds the plugin while working in a terminal keeps talking to the
+ * previous build — and the symptom is a handler quietly behaving like an older
+ * version, which is miserable to debug. The plugin reports the fingerprint it
+ * was built from, the server compares it against this one, and any mismatch is
+ * surfaced in `studio_status` and `list_studios` with the fix.
+ *
+ * Must stay byte-identical to the hash in scripts/build-plugin.mjs.
+ */
+let cached = null;
+function pluginSourceDir() {
+    // dist/lib/pluginbuild.js -> package root -> plugin/src
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "plugin", "src");
+}
+function collect(dir, root, into) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collect(path, root, into);
+        }
+        else if (entry.name.endsWith(".luau")) {
+            into.push([
+                relative(root, path).split("\\").join("/"),
+                readFileSync(path, "utf8"),
+            ]);
+        }
+    }
+}
+/**
+ * Hashes every .luau file under plugin/src, sorted by path. Line endings are
+ * normalised because git checkouts differ between platforms and the plugin
+ * would otherwise look stale on Windows.
+ */
+export function expectedPluginBuildId() {
+    if (cached !== null)
+        return cached;
+    try {
+        const root = pluginSourceDir();
+        const files = [];
+        collect(root, root, files);
+        files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const hash = createHash("sha256");
+        for (const [path, contents] of files) {
+            hash.update(path);
+            hash.update("\n");
+            hash.update(contents.replace(/\r\n/g, "\n"));
+            hash.update("\n");
+        }
+        cached = hash.digest("hex").slice(0, 12);
+    }
+    catch {
+        // Sources missing (an unusual install layout) means we cannot compare, and
+        // an unverifiable version is better reported as "unknown" than as stale.
+        cached = "unknown";
+    }
+    return cached;
+}
+/**
+ * Human-readable warning when the connected plugin was built from different
+ * sources, or null when it matches. Returned to the agent so it knows a
+ * surprising result may just be a stale plugin.
+ */
+export function pluginStalenessWarning(reported) {
+    const expected = expectedPluginBuildId();
+    if (expected === "unknown" || !reported || reported === expected)
+        return null;
+    if (reported === "dev") {
+        return ("The connected plugin was loaded from source rather than a build, so its " +
+            "version cannot be verified against this server.");
+    }
+    return (`The connected Studio plugin was built from different sources than this ` +
+        `server (plugin ${reported}, server ${expected}). Studio only reloads a ` +
+        `plugin when its window next takes focus — click into Studio, then retry. ` +
+        `If that does not clear it, run \`npm run install:plugin\` and restart Studio.`);
+}
+//# sourceMappingURL=pluginbuild.js.map

package/dist/lib/pluginbuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginbuild.js","sourceRoot":"","sources":["../../src/lib/pluginbuild.ts"],"names":[],"mappings":"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"}