dominus-cli 0.5.6 → 0.5.8

package/dist/index.js

@@ -680,8 +680,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.
@@ -2586,7 +2605,7 @@ async function startMcpServer() {
   }
   const mcp = new McpServer({
     name: "dominus",
-    version: "0.5.5"
+    version: "0.5.8"
   }, {
     instructions: INTERNAL_MEMORY
   });
@@ -2599,6 +2618,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",
@@ -2624,7 +2733,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();
@@ -2720,7 +2829,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();
@@ -2995,6 +3104,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: path5, childDepth }) => {
+      assertConnected();
+      const [propRes, treeRes] = await Promise.all([
+        bridge.sendRequest(
+          CliMsg.GET_PROPERTIES,
+          { path: path5, compact: true }
+        ),
+        bridge.sendRequest(
+          CliMsg.GET_EXPLORER,
+          { rootPath: path5, 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: path5, framework, componentName }) => {
+      assertConnected();
+      const res = await bridge.sendRequest(
+        CliMsg.SERIALIZE_UI,
+        { path: path5, 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",
@@ -4259,10 +4452,24 @@ You are deeply knowledgeable about:
 
 You have direct access to Roblox Studio through tools. You can read/edit scripts, run code, browse the explorer tree, manage instances, and run tests -- all in real-time via WebSocket.
 
+## CRITICAL: NEVER use run_code for tasks that have a dedicated tool
+run_code is a LAST RESORT. You have 30+ specialized tools \u2014 use them.
+- Reading properties \u2192 get_properties, get_descendants_properties
+- Inspecting selection \u2192 inspect_selection (ONE call returns paths + properties)
+- Inspecting an instance \u2192 inspect_instance (ONE call returns properties + children)
+- Converting UI to code \u2192 convert_ui_to_code (ONE call serializes + generates component)
+- Creating parts \u2192 create_part, build_multiple
+- Creating UI \u2192 create_ui
+- Modifying properties \u2192 set_properties, bulk_set_properties
+- Browsing the tree \u2192 get_explorer
+- Reading/editing scripts \u2192 read_script, edit_script
+- Serializing UI \u2192 serialize_ui
+Only use run_code for: procedural generation, terrain algorithms, raycasting, physics queries, or other logic that no tool covers.
+
 When the user asks you to do something, you should:
 1. Use your tools to gather context (read scripts, check explorer, recall memory)
 2. Plan your approach for complex tasks
-3. Execute changes using your tools (edit scripts, run code, insert instances)
+3. Execute changes using the appropriate dedicated tools (NOT run_code unless truly necessary)
 4. Verify your changes worked (read back, check output for errors)
 5. Remember important facts for future sessions`);
   if (opts.connected) {