dominus-cli 0.5.1 → 0.5.3

package/dist/index.js

@@ -629,6 +629,84 @@ var init_ws_client = __esm({
   }
 });
 
+// src/agent/internal-memory.ts
+var INTERNAL_MEMORY;
+var init_internal_memory = __esm({
+  "src/agent/internal-memory.ts"() {
+    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/memory/store.ts
 var store_exports = {};
 __export(store_exports, {
@@ -1138,7 +1216,7 @@ var init_get_descendants_properties = __esm({
     init_protocol();
     tool6 = {
       name: "get_descendants_properties",
-      description: "Easily get all descendants of a UI instance (or any instance) and all of their properties.",
+      description: "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.",
       parameters: {
         type: "object",
         properties: {
@@ -1146,6 +1224,10 @@ var init_get_descendants_properties = __esm({
             type: "string",
             description: 'Full instance path (e.g., "Workspace.Part", "StarterGui.ScreenGui")'
           },
+          compact: {
+            type: "boolean",
+            description: "When true (default), strips read-only, nil, deprecated, and default-valued properties to massively reduce response size. Set to false for full property dump."
+          },
           outputFile: {
             type: "string",
             description: "Optional file path to write the JSON result to, useful for very large trees where context limits apply."
@@ -1157,9 +1239,10 @@ var init_get_descendants_properties = __esm({
         if (!ctx.isStudioConnected()) {
           return { success: false, error: "Studio is not connected" };
         }
+        const compact = params.compact !== false;
         const response = await ctx.sendToStudio(
           CliMsg.GET_DESCENDANTS_PROPERTIES,
-          { path: params.path },
+          { path: params.path, compact },
           1e3 * 60 * 5
           // 5 minute timeout since getting ALL descendants can take a very long time
         );
@@ -1518,7 +1601,7 @@ var init_create_ui = __esm({
           },
           tree: {
             type: "object",
-            description: 'The root UI node. Each node has: ClassName (string), Name (string), any properties as key-value pairs, and Children (array of child nodes). Property values are auto-coerced:\n  UDim2: [xScale, xOffset, yScale, yOffset] or {XScale, XOffset, YScale, YOffset}\n  Color3: "#hex", "rgb(r,g,b)", [r,g,b], or BrickColor name\n  UDim: [scale, offset] or number\n  Vector2: [x, y] or {x, y} (auto-disambiguated from UDim by property name)\n  NumberRange: [min, max] or number\n  Rect: [minX, minY, maxX, maxY] or {MinX, MinY, MaxX, MaxY}\n  Font: "GothamBold", "SourceSans", etc. (Enum.Font names)\n  Enums: string name like "Center", "Left", "Fit"\n  FontFace: {Family, Weight, Style}\n  2-element arrays are auto-disambiguated: AnchorPoint\u2192Vector2, CornerRadius/Padding\u2192UDim, etc.'
+            description: 'The root UI node. Each node has: ClassName (string), Name (string), Children (array of child nodes), and properties. Properties may be specified either flattened at the top level of the node, OR nested under a "properties" / "Properties" / "props" key \u2014 both work. Property values are auto-coerced:\n  UDim2: [xScale, xOffset, yScale, yOffset] or {XScale, XOffset, YScale, YOffset}\n  Color3: "#hex", "rgb(r,g,b)", [r,g,b], or BrickColor name\n  UDim: [scale, offset] or number\n  Vector2: [x, y] or {x, y} (auto-disambiguated from UDim by property name)\n  NumberRange: [min, max] or number\n  Rect: [minX, minY, maxX, maxY] or {MinX, MinY, MaxX, MaxY}\n  Font: "GothamBold", "SourceSans", etc. (Enum.Font names)\n  Enums: string name like "Center", "Left", "Fit"\n  FontFace: {Family, Weight, Style}\n  2-element arrays are auto-disambiguated: AnchorPoint\u2192Vector2, CornerRadius/Padding\u2192UDim, etc.'
           },
           animate: {
             type: "boolean",
@@ -2499,6 +2582,8 @@ async function startMcpServer() {
   const mcp = new McpServer({
     name: "dominus",
     version: "0.2.1"
+  }, {
+    instructions: INTERNAL_MEMORY
   });
   mcp.tool(
     "read_script",
@@ -2561,14 +2646,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: path5, outputFile }) => {
+    async ({ path: path5, compact, outputFile }) => {
       assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path5, outputFile }, 1e3 * 60 * 5);
+      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path5, compact, outputFile }, 1e3 * 60 * 5);
       return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
     }
   );
@@ -2885,6 +2971,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: path5, maxDepth }) => {
+      assertConnected();
+      const res = await bridge.sendRequest(
+        CliMsg.SERIALIZE_UI,
+        { path: path5, 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",
@@ -2951,6 +3057,7 @@ var init_server = __esm({
     init_protocol();
     init_store();
     init_config();
+    init_internal_memory();
   }
 });
 var CROWN_ART = `    \u25C6       \u25C6       \u25C6
@@ -4132,6 +4239,7 @@ function toolToOpenAI(tool29) {
 }
 
 // src/agent/system-prompt.ts
+init_internal_memory();
 function buildSystemPrompt(opts) {
   const parts = [];
   parts.push(`You are Dominus, an expert AI agent for Roblox Studio development.
@@ -4283,6 +4391,66 @@ GUI classes use DIFFERENT property types than 3D parts:
 - All enum properties from string names
 - Color3 from hex "#RRGGBB", "rgb(r,g,b)", or BrickColor name strings
 
+## Serializing & Converting Existing UI
+When the user asks to convert, export, recreate, or turn an existing UI into a React/Roact component:
+
+**Use \`serialize_ui\` \u2014 NOT \`get_descendants_properties\`.**
+\`serialize_ui\` returns a clean, minimal JSON tree with only non-default properties, values already in JSON-friendly formats (hex colors, UDim2 arrays, enum names), and a proper parent-child hierarchy. It's purpose-built for this exact workflow.
+
+\`get_descendants_properties\` returns a flat list with ALL properties (including read-only, defaults, deprecated) \u2014 it's much larger and harder to convert.
+
+### Roblox UI \u2192 Roact/React Conversion Workflow
+1. Call \`serialize_ui\` with the path (e.g. \`StarterGui.MyScreenGui.MyFrame\`)
+2. The result is a tree like:
+\`\`\`json
+{
+  "ClassName": "Frame", "Name": "MyFrame",
+  "Size": [0.5, 0, 0.3, 0], "BackgroundColor3": "#1a1a2e",
+  "Children": [
+    { "ClassName": "UICorner", "CornerRadius": [0, 8] },
+    { "ClassName": "TextLabel", "Name": "Title", "Text": "Hello",
+      "Size": [1, 0, 0.2, 0], "TextColor3": "#ffffff", "BackgroundTransparency": 1 }
+  ]
+}
+\`\`\`
+3. Convert to Roact/React-lua using these mappings:
+   - Each JSON node \u2192 \`Roact.createElement(ClassName, props, children)\` or \`React.createElement\`
+   - \`UDim2\` arrays \`[xS, xO, yS, yO]\` \u2192 \`UDim2.new(xS, xO, yS, yO)\`
+   - \`Color3\` hex \`"#RRGGBB"\` \u2192 \`Color3.fromHex("#RRGGBB")\`
+   - \`Vector2\` arrays \`[x, y]\` \u2192 \`Vector2.new(x, y)\`
+   - \`UDim\` arrays \`[s, o]\` \u2192 \`UDim.new(s, o)\`
+   - Enum strings \`"Center"\` \u2192 \`Enum.TextXAlignment.Center\` (resolve the full enum path)
+   - \`Children\` array \u2192 child elements table
+   - UI modifiers (UICorner, UIStroke, UIGradient, UIListLayout, UIPadding, UIScale) \u2192 children of the parent element
+
+### Example Roact output:
+\`\`\`lua
+local function MyFrame()
+    return Roact.createElement("Frame", {
+        Size = UDim2.new(0.5, 0, 0.3, 0),
+        BackgroundColor3 = Color3.fromHex("#1a1a2e"),
+    }, {
+        Corner = Roact.createElement("UICorner", {
+            CornerRadius = UDim.new(0, 8),
+        }),
+        Title = Roact.createElement("TextLabel", {
+            Size = UDim2.new(1, 0, 0.2, 0),
+            Text = "Hello",
+            TextColor3 = Color3.fromHex("#ffffff"),
+            BackgroundTransparency = 1,
+        }),
+    })
+end
+\`\`\`
+
+### Key rules for conversion:
+- Use the instance \`Name\` as the dictionary key in the children table
+- UI modifiers (UICorner, UIStroke, etc.) are CHILDREN, not props
+- Keep the exact property values from serialize_ui \u2014 don't guess or approximate
+- For Fusion: \`New "Frame" { Size = UDim2.new(...), [Children] = { ... } }\`
+- Preserve ZIndex ordering when relevant
+- FontFace objects \u2192 \`Font.new("rbxasset://fonts/families/...", Enum.FontWeight.Bold)\`
+
 ## ReflectionService
 The \`get_class_info\` tool queries Roblox's ReflectionService to return the complete API surface for any class:
 - All properties with their exact ValueType
@@ -4290,7 +4458,9 @@ The \`get_class_info\` tool queries Roblox's ReflectionService to return the com
 - All events with parameter types
 - Superclass, creatability, serialization info
 
-Use it whenever you're unsure about property names or types. It's fast and cached.`);
+Use it whenever you're unsure about property names or types. It's fast and cached.
+
+${INTERNAL_MEMORY}`);
   return parts.join("\n");
 }