dominus-cli 0.5.5 → 0.5.7

package/dist/index.js

@@ -680,8 +680,20 @@ 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 \`get_selection\` + \`get_properties\`
+- 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.
+
 ### Verification habits
 - After a build, call \`get_explorer\` or \`get_selection\` to confirm the tree looks right.
 - After editing a script, read it back.
@@ -2624,7 +2636,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/get_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, custom logic with no tool equivalent.",
     { code: z.string().describe("Luau code to execute") },
     async ({ code }) => {
       assertConnected();
@@ -2720,7 +2732,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,184 +3007,6 @@ async function startMcpServer() {
       return { content: [{ type: "text", text: JSON.stringify(res.payload.tree, null, 2) }] };
     }
   );
-  mcp.tool(
-    "move_instance",
-    "Move (reparent) an instance to a new parent in Roblox Studio. Preserves the instance and all descendants \u2014 much better than delete + recreate. Sets a ChangeHistoryService waypoint so the move can be undone.",
-    {
-      path: z.string().describe('Full path of the instance to move (e.g. "Workspace.OldFolder.MyPart")'),
-      newParent: z.string().describe('Full path of the new parent (e.g. "Workspace.NewFolder")')
-    },
-    async ({ path: path5, newParent }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.MOVE_INSTANCE,
-        { path: path5, newParent }
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "bulk_set_properties",
-    "Set properties on multiple instances at once in a single call. Much faster than calling set_properties repeatedly. Two modes:\n1. Explicit: provide targets array of {path, properties} objects\n2. Filter: provide root + className + properties to apply to all matches",
-    {
-      targets: z.array(z.object({
-        path: z.string(),
-        properties: z.record(z.unknown())
-      })).optional().describe("Array of {path, properties} for explicit mode"),
-      root: z.string().optional().describe("Root path to search under (filter mode)"),
-      className: z.string().optional().describe("Only apply to instances of this ClassName (filter mode)"),
-      properties: z.record(z.unknown()).optional().describe("Properties to set on all matches (filter mode)")
-    },
-    async (params) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.BULK_SET_PROPERTIES,
-        {
-          targets: params.targets,
-          root: params.root,
-          className: params.className,
-          properties: params.properties
-        },
-        1e3 * 60
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "find_replace_scripts",
-    "Find and replace text across all scripts in the game (or under a root path). Supports plain text and Lua patterns. Use dryRun=true to preview changes without applying.",
-    {
-      find: z.string().describe("Text or Lua pattern to search for"),
-      replace: z.string().describe("Replacement text (supports Lua pattern captures like %1, %2)"),
-      root: z.string().optional().describe("Root path to limit search scope (optional)"),
-      usePattern: z.boolean().optional().default(false).describe("Treat find/replace as Lua patterns"),
-      dryRun: z.boolean().optional().default(false).describe("Preview matches without modifying scripts")
-    },
-    async (params) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.FIND_REPLACE_SCRIPTS,
-        {
-          find: params.find,
-          replace: params.replace,
-          root: params.root,
-          usePattern: params.usePattern,
-          dryRun: params.dryRun
-        },
-        1e3 * 60 * 5
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "undo",
-    "Undo the last action in Roblox Studio (ChangeHistoryService). Works like Ctrl+Z. Use to roll back mistakes.",
-    {},
-    async () => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.UNDO, {});
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
-    }
-  );
-  mcp.tool(
-    "redo",
-    "Redo the last undone action in Roblox Studio (ChangeHistoryService). Works like Ctrl+Y.",
-    {},
-    async () => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.REDO, {});
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
-    }
-  );
-  mcp.tool(
-    "move_instance",
-    "Move (reparent) an instance to a new parent in Roblox Studio. Preserves the instance and all descendants \u2014 much better than delete + recreate. Sets a ChangeHistoryService waypoint so the move can be undone.",
-    {
-      path: z.string().describe('Full path of the instance to move (e.g. "Workspace.OldFolder.MyPart")'),
-      newParent: z.string().describe('Full path of the new parent (e.g. "Workspace.NewFolder")')
-    },
-    async ({ path: path5, newParent }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.MOVE_INSTANCE,
-        { path: path5, newParent }
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "bulk_set_properties",
-    "Set properties on multiple instances at once in a single call. Much faster than calling set_properties repeatedly. Two modes:\n1. Explicit: provide targets array of {path, properties} objects\n2. Filter: provide root + className + properties to apply to all matches",
-    {
-      targets: z.array(z.object({
-        path: z.string(),
-        properties: z.record(z.unknown())
-      })).optional().describe("Array of {path, properties} for explicit mode"),
-      root: z.string().optional().describe("Root path to search under (filter mode)"),
-      className: z.string().optional().describe("Only apply to instances of this ClassName (filter mode)"),
-      properties: z.record(z.unknown()).optional().describe("Properties to set on all matches (filter mode)")
-    },
-    async (params) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.BULK_SET_PROPERTIES,
-        {
-          targets: params.targets,
-          root: params.root,
-          className: params.className,
-          properties: params.properties
-        },
-        1e3 * 60
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "find_replace_scripts",
-    "Find and replace text across all scripts in the game (or under a root path). Supports plain text and Lua patterns. Use dryRun=true to preview changes without applying.",
-    {
-      find: z.string().describe("Text or Lua pattern to search for"),
-      replace: z.string().describe("Replacement text (supports Lua pattern captures like %1, %2)"),
-      root: z.string().optional().describe("Root path to limit search scope (optional)"),
-      usePattern: z.boolean().optional().default(false).describe("Treat find/replace as Lua patterns"),
-      dryRun: z.boolean().optional().default(false).describe("Preview matches without modifying scripts")
-    },
-    async (params) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.FIND_REPLACE_SCRIPTS,
-        {
-          find: params.find,
-          replace: params.replace,
-          root: params.root,
-          usePattern: params.usePattern,
-          dryRun: params.dryRun
-        },
-        1e3 * 60 * 5
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "undo",
-    "Undo the last action in Roblox Studio (ChangeHistoryService). Works like Ctrl+Z. Use to roll back mistakes.",
-    {},
-    async () => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.UNDO, {});
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
-    }
-  );
-  mcp.tool(
-    "redo",
-    "Redo the last undone action in Roblox Studio (ChangeHistoryService). Works like Ctrl+Y.",
-    {},
-    async () => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.REDO, {});
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
-    }
-  );
   mcp.tool(
     "recall_memory",
     "Search persistent memory for facts about the current Roblox project",
@@ -4437,10 +4271,22 @@ 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_selection, get_descendants_properties
+- Inspecting selection \u2192 get_selection (returns paths), then get_properties or serialize_ui
+- 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
+- Converting 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) {