dominus-cli 0.5.1 → 0.5.3

package/dist/mcp.js

@@ -40,7 +40,8 @@ var CliMsg = {
   EXECUTE_RUN_TEST: "cli:test:run",
   EXECUTE_PLAY_TEST: "cli:test:play",
   BUILD_UI: "cli:build:ui",
-  GET_REFLECTION: "cli:get:reflection"};
+  GET_REFLECTION: "cli:get:reflection",
+  SERIALIZE_UI: "cli:serialize:ui"};
 function createMessage(type, payload) {
   return { id: nanoid(), type, payload, ts: Date.now() };
 }
@@ -612,6 +613,79 @@ function getScriptIndex(projectId) {
   }));
 }
 
+// src/agent/internal-memory.ts
+var INTERNAL_MEMORY = `## Internal Memory \u2014 Known Quirks & Lessons
+
+These are built-in lessons that ship with Dominus. Follow them exactly.
+
+### create_ui \u2014 property format
+- Each node accepts properties in **either** of two shapes:
+  - **Flattened (preferred)**: props as top-level keys next to \`ClassName\`, \`Name\`, \`Children\`.
+    \`\`\`json
+    { "ClassName": "TextButton", "Name": "Btn", "Text": "OK", "Size": [0, 100, 0, 40] }
+    \`\`\`
+  - **Nested bag**: props grouped under \`properties\` / \`Properties\` / \`props\` / \`Props\`.
+    \`\`\`json
+    { "ClassName": "TextButton", "Name": "Btn",
+      "properties": { "Text": "OK", "Size": [0, 100, 0, 40] } }
+    \`\`\`
+- Do NOT mix a nested \`properties\` bag with flattened props of the same name \u2014 the bag wins.
+- Reserved keys (never treated as instance properties): \`ClassName\`, \`className\`, \`Name\`, \`name\`, \`Children\`, \`children\`, \`properties\`, \`Properties\`, \`props\`, \`Props\`.
+
+### build_multiple \u2014 schema is strict
+- Top-level keys only: \`name\`, \`className\`, \`position\`, \`size\`, \`color\`, \`material\`, \`anchored\`, \`shape\`, \`transparency\`, \`parent\`, \`canCollide\`.
+- Does NOT accept a nested \`properties\` bag. For anything outside those fields use \`insert_instance\` + \`set_properties\`.
+- \`shape\` values: \`Block\`, \`Ball\`, \`Cylinder\`, \`Wedge\`.
+
+### Color formats (accepted everywhere)
+- Hex: \`"#RRGGBB"\`
+- RGB string: \`"rgb(255, 128, 0)"\`
+- BrickColor name: \`"Bright red"\`, \`"Institutional white"\`, \`"Really black"\`, etc.
+- Array: \`[r, g, b]\` (0\u20131 floats) or \`[255, 128, 0]\` (auto-detected if any value > 1)
+
+### UDim2 / UDim / Vector2 / Color3 coercion (create_ui)
+- UDim2: \`[xScale, xOffset, yScale, yOffset]\` or \`{XScale, XOffset, YScale, YOffset}\`.
+- UDim: \`[scale, offset]\` or a plain number (treated as pixels).
+- Vector2 (e.g. \`AnchorPoint\`): \`[x, y]\` or \`{x, y}\`.
+- 2-element arrays are auto-disambiguated by property name (\`AnchorPoint\` \u2192 Vector2, \`CornerRadius\` \u2192 UDim).
+
+### Common GUI property names
+- GUI uses \`Size\`/\`Position\` as **UDim2** \u2014 never Vector3.
+- \`BackgroundColor3\`, \`TextColor3\`, \`BorderColor3\`, \`ImageColor3\` \u2192 Color3.
+- \`Font\` accepts a string enum name like \`"GothamBold"\`, \`"SourceSans"\`.
+- Enum properties take the string name: \`"Center"\`, \`"Left"\`, \`"Fit"\`.
+
+### Tool selection cheat-sheet
+- Single 3D part \u2192 \`create_part\`
+- Many 3D parts (tree, building, vehicle) \u2192 \`build_multiple\` with \`groupName\`
+- 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\`)
+- Anything exotic or procedural \u2192 \`run_code\` as last resort
+
+### Verification habits
+- After a build, call \`get_explorer\` or \`get_selection\` to confirm the tree looks right.
+- After editing a script, read it back.
+- After \`run_code\`, check \`get_output\` for errors.
+
+### serialize_ui \u2014 the RIGHT tool for UI conversion
+- **Use \`serialize_ui\` when converting existing UI to Roact/React/Fusion components.** It returns a minimal JSON tree with only non-default properties, already in JSON-friendly formats.
+- **Do NOT use \`get_descendants_properties\` for UI conversion** \u2014 it returns a flat list with ~50+ properties per instance (including read-only, deprecated, nil, and default values), which bloats context and confuses conversion.
+- \`serialize_ui\` output maps 1:1 to \`create_ui\` input \u2014 you can round-trip UI through it.
+- The tree structure preserves parent-child hierarchy, so Roact/React children mapping is direct.
+
+### UI \u2192 Roact/React conversion cheat-sheet
+- \`serialize_ui\` path \u2192 JSON tree \u2192 map each node to \`Roact.createElement(ClassName, props, childrenDict)\`
+- UDim2 arrays \`[xS, xO, yS, yO]\` \u2192 \`UDim2.new(xS, xO, yS, yO)\`
+- Color3 hex strings \u2192 \`Color3.fromHex("#RRGGBB")\`
+- Vector2 arrays \u2192 \`Vector2.new(x, y)\`
+- UDim arrays \u2192 \`UDim.new(s, o)\`
+- Enum strings like \`"Center"\` \u2192 \`Enum.TextXAlignment.Center\`
+- FontFace \u2192 \`Font.new(family, weight, style)\`
+- UI modifiers (UICorner, UIStroke, UIGradient, UIListLayout, UIPadding) are CHILDREN not props
+- Use instance Name as dictionary key in children table
+`;
+
 // src/mcp/server.ts
 var bridge;
 async function startMcpServer() {
@@ -630,6 +704,8 @@ async function startMcpServer() {
   const mcp = new McpServer({
     name: "dominus",
     version: "0.2.1"
+  }, {
+    instructions: INTERNAL_MEMORY
   });
   mcp.tool(
     "read_script",
@@ -692,14 +768,15 @@ async function startMcpServer() {
   );
   mcp.tool(
     "get_descendants_properties",
-    "Easily get all descendants of a UI instance (or any instance) and all of their properties.",
+    "Easily get all descendants of a UI instance (or any instance) and all of their properties. By default uses compact mode which strips read-only, nil, deprecated, and default-valued properties to keep responses small.",
     {
       path: z.string().describe('Full instance path (e.g., "Workspace.Part", "StarterGui.ScreenGui")'),
+      compact: z.boolean().optional().default(true).describe("Strip noisy/default properties (default true). Set false for full dump."),
       outputFile: z.string().optional().describe("Optional file path to write to prevent limit errors/timeouts")
     },
-    async ({ path: path2, outputFile }) => {
+    async ({ path: path2, compact, outputFile }) => {
       assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path2, outputFile }, 1e3 * 60 * 5);
+      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path2, compact, outputFile }, 1e3 * 60 * 5);
       return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
     }
   );
@@ -1016,6 +1093,26 @@ async function startMcpServer() {
       return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
     }
   );
+  mcp.tool(
+    "serialize_ui",
+    "Serialize an existing Roblox UI tree into a compact, create_ui-compatible JSON tree. This is the reverse of create_ui \u2014 reads any GUI instance and returns a declarative JSON tree with ClassName, Name, non-default properties (Color3 as hex, UDim2 as arrays, etc.), and Children. Perfect for: converting existing UI to Roact/React components, cloning/templating, understanding UI structure, or refactoring. Use this INSTEAD of get_descendants_properties when you need to recreate or convert UI.",
+    {
+      path: z.string().describe('Instance path to serialize (e.g. "StarterGui.MyScreenGui")'),
+      maxDepth: z.number().optional().default(50).describe("Maximum tree depth (default 50)")
+    },
+    async ({ path: path2, maxDepth }) => {
+      assertConnected();
+      const res = await bridge.sendRequest(
+        CliMsg.SERIALIZE_UI,
+        { path: path2, maxDepth },
+        1e3 * 60 * 2
+      );
+      if (!res.payload.success) {
+        return { content: [{ type: "text", text: `Error: ${res.payload.error ?? "Serialization failed"}` }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.payload.tree, null, 2) }] };
+    }
+  );
   mcp.tool(
     "recall_memory",
     "Search persistent memory for facts about the current Roblox project",