dominus-cli 0.5.6 → 0.5.8

package/dist/mcp.js

@@ -34,14 +34,23 @@ var CliMsg = {
   INSERT_INSTANCE: "cli:insert",
   DELETE_INSTANCE: "cli:delete",
   GET_SELECTION: "cli:get:selection",
+  SELECT: "cli:select",
   SEARCH_SCRIPTS: "cli:search:scripts",
   GET_OUTPUT: "cli:get:output",
   RUN_TESTS: "cli:run:tests",
   EXECUTE_RUN_TEST: "cli:test:run",
   EXECUTE_PLAY_TEST: "cli:test:play",
+  END_TEST: "cli:test:end",
   BUILD_UI: "cli:build:ui",
   GET_REFLECTION: "cli:get:reflection",
-  SERIALIZE_UI: "cli:serialize:ui"};
+  UPLOAD_ASSET: "cli:upload:asset",
+  SERIALIZE_UI: "cli:serialize:ui",
+  MOVE_INSTANCE: "cli:move:instance",
+  UNDO: "cli:undo",
+  REDO: "cli:redo",
+  BULK_SET_PROPERTIES: "cli:bulk:set:properties",
+  FIND_REPLACE_SCRIPTS: "cli:find:replace:scripts"
+};
 function createMessage(type, payload) {
   return { id: nanoid(), type, payload, ts: Date.now() };
 }
@@ -661,8 +670,27 @@ These are built-in lessons that ship with Dominus. Follow them exactly.
 - Full UI tree \u2192 \`create_ui\` (one call, never loop \`insert_instance\` for UI)
 - **Convert/export existing UI \u2192 \`serialize_ui\`** (NOT get_descendants_properties)
 - Adjusting an existing instance \u2192 \`set_properties\` (not \`run_code\`)
+- **Inspecting user's selection \u2192 \`get_selection\`, then \`get_properties\` or \`serialize_ui\`**
+- **Reading properties \u2192 \`get_properties\` (NEVER \`run_code\` with dump scripts)**
+- **Browsing the tree \u2192 \`get_explorer\`**
 - Anything exotic or procedural \u2192 \`run_code\` as last resort
 
+### NEVER use run_code for:
+- Getting properties of an instance \u2192 use \`get_properties\` or \`serialize_ui\`
+- Dumping selection info \u2192 use \`inspect_selection\` (ONE call does it all)
+- Inspecting an instance + its children \u2192 use \`inspect_instance\`
+- Converting UI to Roact/React \u2192 use \`convert_ui_to_code\`
+- Creating instances \u2192 use \`create_part\`, \`create_ui\`, \`insert_instance\`, \`build_multiple\`
+- Modifying properties \u2192 use \`set_properties\` or \`bulk_set_properties\`
+- Reading scripts \u2192 use \`read_script\`
+- Browsing the explorer \u2192 use \`get_explorer\`
+\`run_code\` is ONLY for procedural logic, terrain generation, raycasts, physics queries, or custom algorithms with no tool equivalent.
+
+### Composite skill tools (prefer these over chaining)
+- \`inspect_selection\` \u2014 Returns paths + compact properties for all selected instances in ONE call. Use when user says "my selection" or "what I selected".
+- \`inspect_instance\` \u2014 Returns compact properties + children tree for a single instance in ONE call. Combines get_properties + get_explorer.
+- \`convert_ui_to_code\` \u2014 Serializes a UI tree and generates a Roact/React component. Use when user says "turn this into a component" or "convert to React".
+
 ### Verification habits
 - After a build, call \`get_explorer\` or \`get_selection\` to confirm the tree looks right.
 - After editing a script, read it back.
@@ -703,7 +731,7 @@ async function startMcpServer() {
   }
   const mcp = new McpServer({
     name: "dominus",
-    version: "0.5.5"
+    version: "0.5.8"
   }, {
     instructions: INTERNAL_MEMORY
   });
@@ -716,6 +744,96 @@ async function startMcpServer() {
     for (const p of parts) r += `[${luaStr(p)}]`;
     return r;
   }
+  function generateComponentCode(tree, componentName, framework) {
+    const isReact = framework === "react";
+    const lib = isReact ? "React" : "Roact";
+    const lines = [];
+    lines.push(`local ${lib} = require(game.ReplicatedStorage.Packages.${isReact ? "React" : "Roact"})`);
+    if (isReact) {
+      lines.push(`local e = React.createElement`);
+    } else {
+      lines.push(`local e = Roact.createElement`);
+    }
+    lines.push("");
+    lines.push(`local function ${componentName}()`);
+    lines.push(`	return ${renderNode(tree, 1)}`);
+    lines.push("end");
+    lines.push("");
+    lines.push(`return ${componentName}`);
+    return lines.join("\n");
+  }
+  function renderNode(node, depth) {
+    const indent = "	".repeat(depth);
+    const indent2 = "	".repeat(depth + 1);
+    const className = node.ClassName || "Frame";
+    const children = node.Children || [];
+    node.Name;
+    const props = [];
+    const skipKeys = /* @__PURE__ */ new Set(["ClassName", "Name", "Children", "className", "name", "children"]);
+    for (const [key, val] of Object.entries(node)) {
+      if (skipKeys.has(key)) continue;
+      props.push(`${indent2}${key} = ${luaValue(val, depth + 1)},`);
+    }
+    const childEntries = [];
+    for (const child of children) {
+      const childName = child.Name || child.ClassName || "Child";
+      childEntries.push(`${indent2}${childName} = ${renderNode(child, depth + 1)},`);
+    }
+    const hasProps = props.length > 0;
+    const hasChildren = childEntries.length > 0;
+    if (!hasProps && !hasChildren) {
+      return `e("${className}", {})`;
+    }
+    const parts = [];
+    parts.push(`e("${className}", {`);
+    if (hasProps) {
+      parts.push(...props);
+    }
+    if (hasChildren) {
+      parts.push(`${indent2}}, {`);
+      parts.push(...childEntries);
+      parts.push(`${indent}})`);
+    } else {
+      parts.push(`${indent}})`);
+    }
+    return parts.join("\n");
+  }
+  function luaValue(val, _depth) {
+    if (val === null || val === void 0) return "nil";
+    if (typeof val === "boolean") return String(val);
+    if (typeof val === "number") return String(val);
+    if (typeof val === "string") {
+      if (val.startsWith("#") && val.length === 7) {
+        return `Color3.fromHex("${val}")`;
+      }
+      if (/^[A-Z][a-zA-Z]+$/.test(val)) {
+        return `"${val}"`;
+      }
+      return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+    }
+    if (Array.isArray(val)) {
+      if (val.length === 4 && val.every((v) => typeof v === "number")) {
+        return `UDim2.new(${val.join(", ")})`;
+      }
+      if (val.length === 2 && val.every((v) => typeof v === "number")) {
+        return `Vector2.new(${val.join(", ")})`;
+      }
+      if (val.length === 3 && val.every((v) => typeof v === "number")) {
+        const allSmall = val.every((v) => v <= 1);
+        if (allSmall) return `Color3.new(${val.join(", ")})`;
+        return `Color3.fromRGB(${val.join(", ")})`;
+      }
+      return `{${val.map((v) => luaValue(v, _depth)).join(", ")}}`;
+    }
+    if (typeof val === "object") {
+      const entries = Object.entries(val);
+      if (entries.length === 0) return "{}";
+      return `{
+${entries.map(([k, v]) => `${"	".repeat(_depth + 1)}${k} = ${luaValue(v, _depth + 1)}`).join(",\n")}
+${"	".repeat(_depth)}}`;
+    }
+    return String(val);
+  }
   mcp.tool(
     "read_script",
     "Read the source code of a script in Roblox Studio",
@@ -741,7 +859,7 @@ async function startMcpServer() {
   );
   mcp.tool(
     "run_code",
-    "Execute Luau code in Roblox Studio and return output",
+    "Execute arbitrary Luau code in Roblox Studio. LAST RESORT \u2014 only use when no dedicated tool exists. Do NOT use for: reading properties (use get_properties/inspect_selection/serialize_ui), creating instances (use create_part/create_ui/insert_instance/build_multiple), modifying properties (use set_properties/bulk_set_properties), or inspecting the tree (use get_explorer). Valid uses: complex procedural generation, terrain algorithms, raycasting, physics queries, custom logic with no tool equivalent.",
     { code: z.string().describe("Luau code to execute") },
     async ({ code }) => {
       assertConnected();
@@ -837,7 +955,7 @@ async function startMcpServer() {
   );
   mcp.tool(
     "get_selection",
-    "Get the currently selected instances in Roblox Studio",
+    'Get the currently selected instances in Roblox Studio. Returns paths and class names of all selected objects. Use this FIRST when the user says "my selection" or "what I have selected". Then use get_properties or serialize_ui on the returned paths to inspect details.',
     {},
     async () => {
       assertConnected();
@@ -1112,6 +1230,90 @@ async function startMcpServer() {
       return { content: [{ type: "text", text: JSON.stringify(res.payload.tree, null, 2) }] };
     }
   );
+  mcp.tool(
+    "inspect_selection",
+    `Inspect the user's current selection in Roblox Studio. Returns the selected instance paths AND their properties (compact) in a single call. Use this FIRST when the user says "my selection", "what I selected", or "the selected thing". Much better than calling get_selection + get_properties separately.`,
+    {},
+    async () => {
+      assertConnected();
+      const selRes = await bridge.sendRequest(CliMsg.GET_SELECTION, {});
+      const paths = selRes.payload?.paths ?? [];
+      if (paths.length === 0) {
+        return { content: [{ type: "text", text: "No instances selected in Studio." }] };
+      }
+      const results = {};
+      for (const p of paths.slice(0, 10)) {
+        try {
+          const propRes = await bridge.sendRequest(
+            CliMsg.GET_PROPERTIES,
+            { path: p, compact: true }
+          );
+          results[p] = propRes.payload.properties ?? propRes.payload;
+        } catch {
+          results[p] = { error: "Failed to read properties" };
+        }
+      }
+      if (paths.length > 10) {
+        results["_truncated"] = `${paths.length - 10} more instances not shown`;
+      }
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "inspect_instance",
+    "Inspect a single instance: returns its compact properties AND its children tree in one call. Combines get_properties + get_explorer into a single round-trip. Use when you need to understand an instance and its subtree.",
+    {
+      path: z.string().describe('Full instance path (e.g. "Workspace.MyModel")'),
+      childDepth: z.number().optional().default(2).describe("How deep to show the children tree (default 2)")
+    },
+    async ({ path: path2, childDepth }) => {
+      assertConnected();
+      const [propRes, treeRes] = await Promise.all([
+        bridge.sendRequest(
+          CliMsg.GET_PROPERTIES,
+          { path: path2, compact: true }
+        ),
+        bridge.sendRequest(
+          CliMsg.GET_EXPLORER,
+          { rootPath: path2, maxDepth: childDepth ?? 2 }
+        )
+      ]);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            properties: propRes.payload.properties ?? propRes.payload,
+            children: treeRes.payload.tree ?? treeRes.payload
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  mcp.tool(
+    "convert_ui_to_code",
+    'Convert an existing Roblox UI tree into Roact/React-lua component code. Serializes the UI at the given path, then generates a ready-to-use Luau component. Use when the user asks to "turn this into a component", "convert to React", or "make a Roact version".',
+    {
+      path: z.string().describe('Path to the UI instance to convert (e.g. "StarterGui.MyScreenGui.MainFrame")'),
+      framework: z.enum(["roact", "react"]).optional().default("react").describe('Target framework: "roact" (legacy) or "react" (react-lua, default)'),
+      componentName: z.string().optional().describe("Name for the generated component (defaults to instance Name)")
+    },
+    async ({ path: path2, framework, componentName }) => {
+      assertConnected();
+      const res = await bridge.sendRequest(
+        CliMsg.SERIALIZE_UI,
+        { path: path2, maxDepth: 50 },
+        1e3 * 60 * 2
+      );
+      if (!res.payload.success || !res.payload.tree) {
+        return { content: [{ type: "text", text: `Error serializing UI: ${res.payload.error ?? "Unknown error"}` }] };
+      }
+      const tree = res.payload.tree;
+      const name = componentName || tree.Name || "GeneratedComponent";
+      const fw = framework || "react";
+      const code = generateComponentCode(tree, name, fw);
+      return { content: [{ type: "text", text: code }] };
+    }
+  );
   mcp.tool(
     "recall_memory",
     "Search persistent memory for facts about the current Roblox project",