dominus-cli 2.2.1 → 2.3.0

package/dist/mcp.js

@@ -109,6 +109,14 @@ var CliMsg = {
   V2_READ_SCRIPT: "studio:v2:read_script",
   V2_UPDATE_SCRIPT: "studio:v2:update_script",
   V2_APPLY: "studio:v2:apply",
+  V2_CREATE_PARTS: "studio:v2:create_parts",
+  V2_CLONE_INSTANCES: "studio:v2:clone_instances",
+  V2_GROUP_INSTANCES: "studio:v2:group_instances",
+  V2_UNGROUP_INSTANCES: "studio:v2:ungroup_instances",
+  V2_TRANSFORM_INSTANCES: "studio:v2:transform_instances",
+  V2_CREATE_WELDS: "studio:v2:create_welds",
+  V2_QUERY_PARTS: "studio:v2:query_parts",
+  V2_SET_SELECTION: "studio:v2:set_selection",
   V2_DELETE: "studio:v2:delete",
   V2_BUILD_UI: "studio:v2:build_ui",
   V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
@@ -561,11 +569,18 @@ Required workflow for Studio changes:
 
 For broad tasks with independent Studio branches, prefer run_parallel_task when the MCP client supports Sampling. Dominus partitions immediate child scopes, runs proposal-only workers concurrently, rejects unknown refs and overlapping writes, applies only the coordinator-approved atomic plan, and reads the result back. Use the normal workflow when Sampling is unavailable or the task is a simple edit.
 
+Building workflow:
+- Use studio_create_parts for multi-part structures instead of many generic create operations.
+- Use studio_clone_instances when an existing instance or model is the intended template. Clone rather than manually recreating descendants and properties.
+- Use studio_transform_instances for Models and BaseParts so model layouts move through PVInstance pivots.
+- Use studio_group_instances and studio_ungroup_instances to organize hierarchy, studio_create_welds for rigid assemblies, and studio_query_parts to inspect crowded 3D regions before editing.
+- Use studio_set_selection when surfacing completed objects to the Studio user.
+
 Safety rules:
 - Never invent instance IDs or Roblox API members.
 - Do not retry a failed write unchanged. Inspect the error and current state first.
 - Deletion is a separate destructive tool and requires explicit user intent.
-- studio_apply is transactional. Keep related edits together, but stay within its documented limits.
+- studio_apply is transactional and supports setProperties, create, clone, and move operations. Keep related edits together, but stay within its documented limits.
 - UI fidelity work must snapshot and inspect the result after building; verify fonts, UDim2 values, colors, strokes, and hierarchy.
 - Dominus intentionally has no arbitrary Luau execution tool.`;
 
@@ -632,6 +647,8 @@ function failure(error, data) {
     data
   });
 }
+
+// src/mcp/tools/shared.ts
 var instanceRefSchema = z.object({
   instanceId: z.string().uuid().optional(),
   pathSegments: z.array(z.string().min(1).max(256)).min(1).max(100).optional()
@@ -664,7 +681,245 @@ function ref(value) {
   return value;
 }
 
-// src/mcp/tools/connections.ts
+// src/mcp/tools/building.ts
+var finiteNumber = z.number().finite();
+var vector3Schema = z.object({ x: finiteNumber, y: finiteNumber, z: finiteNumber }).strict();
+var propertiesSchema = z.record(z.unknown()).refine(
+  (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
+  "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
+);
+var partSchema = z.object({
+  name: z.string().min(1).max(100),
+  className: z.enum([
+    "Part",
+    "WedgePart",
+    "CornerWedgePart",
+    "TrussPart",
+    "MeshPart",
+    "SpawnLocation",
+    "Seat",
+    "VehicleSeat"
+  ]).optional().default("Part"),
+  shape: z.enum(["Block", "Ball", "Cylinder", "Wedge", "CornerWedge"]).optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  size: vector3Schema.optional(),
+  color: z.string().min(1).max(100).optional(),
+  material: z.string().min(1).max(100).optional(),
+  transparency: z.number().min(0).max(1).optional(),
+  anchored: z.boolean().optional().default(true),
+  canCollide: z.boolean().optional(),
+  properties: propertiesSchema.optional()
+});
+var cloneRequestSchema = z.object({
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  count: z.number().int().min(1).max(50).optional().default(1),
+  offset: vector3Schema.optional(),
+  stepOffset: vector3Schema.optional(),
+  properties: propertiesSchema.optional()
+});
+var cframeSchema = z.array(finiteNumber).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var transformOperationSchema = z.object({
+  target: instanceRefSchema,
+  mode: z.enum(["absolute", "relative"]).optional().default("absolute"),
+  cframe: cframeSchema.optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  offset: vector3Schema.optional(),
+  rotationOffset: vector3Schema.optional(),
+  space: z.enum(["world", "local"]).optional().default("world")
+}).refine(
+  (value) => value.mode === "relative" ? Boolean(value.offset || value.rotationOffset) : Boolean(value.cframe || value.position || value.orientation),
+  "Absolute transforms require cframe, position, or orientation; relative transforms require offset or rotationOffset"
+);
+function registerBuildingTools(server, bridge) {
+  server.registerTool(
+    "studio_create_parts",
+    {
+      title: "Build Roblox Parts",
+      description: "Create up to 200 typed BaseParts in one undoable batch, optionally grouped under a new Model or Folder. Supports positions, orientations, sizes, colors, materials, shapes, and additional writable properties.",
+      inputSchema: {
+        parent: instanceRefSchema.optional(),
+        groupName: z.string().min(1).max(100).optional(),
+        groupClass: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parts: z.array(partSchema).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ parent, groupName, groupClass, parts }) => callStudio(bridge, CliMsg.V2_CREATE_PARTS, { parent, groupName, groupClass, parts }, 12e4)
+  );
+  server.registerTool(
+    "studio_clone_instances",
+    {
+      title: "Clone Roblox Instances",
+      description: "Deep-clone instances and descendants with Instance:Clone(), optionally rename, reparent, override root properties, and create repeated spatial copies using offsets. The entire request is undoable and rolls back on failure.",
+      inputSchema: { requests: z.array(cloneRequestSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ requests }) => callStudio(bridge, CliMsg.V2_CLONE_INSTANCES, { requests }, 12e4)
+  );
+  server.registerTool(
+    "studio_group_instances",
+    {
+      title: "Group Roblox Instances",
+      description: "Create a Model or Folder and move up to 100 independent instances into it in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100),
+        name: z.string().min(1).max(100),
+        className: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parent: instanceRefSchema.optional()
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, name, className, parent }) => callStudio(bridge, CliMsg.V2_GROUP_INSTANCES, { targets, name, className, parent }, 6e4)
+  );
+  server.registerTool(
+    "studio_ungroup_instances",
+    {
+      title: "Ungroup Roblox Instances",
+      description: "Move every child out of up to 20 Models or Folders, then remove the empty containers in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(20),
+        parent: instanceRefSchema.optional(),
+        confirm: z.literal(true)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, parent, confirm }) => callStudio(bridge, CliMsg.V2_UNGROUP_INSTANCES, { targets, parent, confirm }, 6e4)
+  );
+  server.registerTool(
+    "studio_transform_instances",
+    {
+      title: "Transform Roblox Models and Parts",
+      description: "Move or rotate up to 100 Models and BaseParts through PVInstance:PivotTo. Supports exact absolute CFrames and world/local relative offsets without breaking model layouts.",
+      inputSchema: { operations: z.array(transformOperationSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_TRANSFORM_INSTANCES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_create_welds",
+    {
+      title: "Create Roblox Welds",
+      description: "Create up to 200 WeldConstraints between explicit BasePart refs in one undoable operation.",
+      inputSchema: {
+        welds: z.array(
+          z.object({
+            part0: instanceRefSchema,
+            part1: instanceRefSchema,
+            name: z.string().min(1).max(100).optional(),
+            parent: instanceRefSchema.optional()
+          })
+        ).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ welds }) => callStudio(bridge, CliMsg.V2_CREATE_WELDS, { welds }, 6e4)
+  );
+  server.registerTool(
+    "studio_query_parts",
+    {
+      title: "Query Parts in 3D Space",
+      description: "Find BaseParts intersecting an oriented box or radius using WorldRoot spatial queries. Returns stable refs, positions, and sizes for inspection or later mutations.",
+      inputSchema: {
+        root: instanceRefSchema.optional(),
+        mode: z.enum(["box", "radius"]).optional().default("box"),
+        position: vector3Schema,
+        orientation: vector3Schema.optional(),
+        size: vector3Schema.optional(),
+        radius: z.number().finite().positive().optional(),
+        maxParts: z.number().int().min(1).max(500).optional().default(200),
+        filter: z.array(instanceRefSchema).max(100).optional(),
+        filterType: z.enum(["Include", "Exclude"]).optional().default("Exclude"),
+        respectCanCollide: z.boolean().optional().default(false)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    }) => callStudio(bridge, CliMsg.V2_QUERY_PARTS, {
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    })
+  );
+  server.registerTool(
+    "studio_set_selection",
+    {
+      title: "Set Roblox Studio Selection",
+      description: "Replace the current Studio selection with up to 200 stable instance refs. Pass an empty array to clear selection.",
+      inputSchema: { targets: z.array(instanceRefSchema).max(200) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_SET_SELECTION, { targets })
+  );
+}
 function registerConnectionTools(server, bridge) {
   server.registerTool(
     "dominus_status",
@@ -1192,7 +1447,7 @@ function registerDocsTools(server) {
     }
   );
 }
-var propertiesSchema = z.record(z.unknown()).refine(
+var propertiesSchema2 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
@@ -1200,19 +1455,27 @@ var mutationOperationSchema = z.discriminatedUnion("op", [
   z.object({
     op: z.literal("setProperties"),
     target: instanceRefSchema,
-    properties: propertiesSchema
+    properties: propertiesSchema2
   }),
   z.object({
     op: z.literal("create"),
     parent: instanceRefSchema,
     className: z.string().min(1).max(100),
     name: z.string().min(1).max(256),
-    properties: propertiesSchema.optional()
+    properties: propertiesSchema2.optional()
   }),
   z.object({
     op: z.literal("move"),
     target: instanceRefSchema,
     parent: instanceRefSchema
+  }),
+  z.object({
+    op: z.literal("clone"),
+    target: instanceRefSchema,
+    parent: instanceRefSchema,
+    name: z.string().min(1).max(100),
+    offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+    properties: propertiesSchema2.optional()
   })
 ]);
 var workerProposalSchema = z.object({
@@ -1441,7 +1704,7 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
         systemPrompt: [
           "You are a read-only Dominus worker. Inspect only the Studio evidence in the request.",
           "You cannot write to Studio. Return one strict JSON WorkerProposal and no Markdown.",
-          "Only propose setProperties, create, or move operations using exact instance refs copied from evidence.",
+          "Only propose setProperties, create, clone, or move operations using exact instance refs copied from evidence.",
           "Never invent instanceId values. Never propose delete, script edits, or arbitrary execution."
         ].join(" "),
         messages: [
@@ -1472,6 +1735,13 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
                         op: "move",
                         target: { instanceId: "uuid", pathSegments: ["..."] },
                         parent: { instanceId: "uuid", pathSegments: ["..."] }
+                      },
+                      {
+                        op: "clone",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        parent: { instanceId: "uuid", pathSegments: ["..."] },
+                        name: "CloneName",
+                        offset: { x: 0, y: 0, z: 0 }
                       }
                     ],
                     risks: ["string"],
@@ -1556,7 +1826,7 @@ function validateWorkerResults(results) {
 function validateOperations(assignment, operations) {
   const errors = [];
   for (const [index, operation] of operations.entries()) {
-    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" ? [operation.target, operation.parent] : [operation.target];
+    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" || operation.op === "clone" ? [operation.target, operation.parent] : [operation.target];
     for (const ref2 of refs) {
       if (!isKnownParallelRef(ref2, assignment.knownRefKeys)) {
         errors.push(`Operation ${index} references an instance absent from worker evidence`);
@@ -1702,12 +1972,14 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
   );
   const knownPaths = collectInstancePaths(originalRoot);
   const expectedCreates = operations.flatMap((operation) => {
-    if (operation.op !== "create") return [];
+    if (operation.op !== "create" && operation.op !== "clone") return [];
     const parentPath = resolveRefPath(operation.parent, knownPaths);
     return parentPath ? [pathKey([...parentPath, operation.name])] : [];
   });
   const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
-  const inspectOperations = operations.filter((operation) => operation.op !== "create");
+  const inspectOperations = operations.filter(
+    (operation) => operation.op !== "create" && operation.op !== "clone"
+  );
   const inspectFailures = [];
   const propertyMismatches = [];
   const moveMismatches = [];
@@ -1777,6 +2049,7 @@ function findRepairOperations(operations, verification, originalRoot) {
       const parentPath = resolveRefPath(operation.parent, knownPaths);
       return Boolean(parentPath && missingCreates.has(pathKey([...parentPath, operation.name])));
     }
+    if (operation.op === "clone") return false;
     if (operation.op === "setProperties") return mismatchedTargets.has(refLabel(operation.target));
     return mismatchedMoves.has(refLabel(operation.target));
   });
@@ -1846,7 +2119,7 @@ function isParallelRefWithinScopes(ref2, scopes) {
   return scopes.some((scope) => Boolean(ref2.instanceId && scope.instanceId === ref2.instanceId));
 }
 function operationTarget(operation) {
-  if (operation.op === "create") {
+  if (operation.op === "create" || operation.op === "clone") {
     const parentPath = operation.parent.pathSegments;
     return {
       key: `${refKey(operation.parent)}/create:${operation.name}`,
@@ -1951,37 +2224,46 @@ function emit(server, type, data) {
 function toErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-var propertiesSchema2 = z.record(z.unknown()).refine(
+var propertiesSchema3 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
 var setPropertiesOperation = z.object({
   op: z.literal("setProperties"),
   target: instanceRefSchema,
-  properties: propertiesSchema2
+  properties: propertiesSchema3
 });
 var createOperation = z.object({
   op: z.literal("create"),
   parent: instanceRefSchema,
   className: z.string().min(1).max(100),
   name: z.string().min(1).max(256),
-  properties: propertiesSchema2.optional()
+  properties: propertiesSchema3.optional()
 });
 var moveOperation = z.object({
   op: z.literal("move"),
   target: instanceRefSchema,
   parent: instanceRefSchema
 });
+var cloneOperation = z.object({
+  op: z.literal("clone"),
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+  properties: propertiesSchema3.optional()
+});
 var mutationOperation = z.discriminatedUnion("op", [
   setPropertiesOperation,
   createOperation,
+  cloneOperation,
   moveOperation
 ]);
 var uiNodeSchema = z.lazy(
   () => z.object({
     ClassName: z.string().min(1).max(100),
     Name: z.string().min(1).max(256).optional(),
-    properties: propertiesSchema2.optional(),
+    properties: propertiesSchema3.optional(),
     Children: z.array(uiNodeSchema).max(1e3).optional()
   })
 );
@@ -2085,7 +2367,7 @@ function registerStudioTools(server, bridge) {
     "studio_apply",
     {
       title: "Apply Atomic Studio Mutations",
-      description: "Atomically set properties, create instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+      description: "Atomically set properties, create instances, deep-clone instances, and move instances. Any failed operation cancels and undoes the entire batch.",
       inputSchema: { operations: z.array(mutationOperation).min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2226,7 +2508,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.2.1";
+var VERSION = "2.3.0";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2239,6 +2521,7 @@ function createDominusMcpServer(bridge) {
   );
   registerConnectionTools(server, bridge);
   registerStudioTools(server, bridge);
+  registerBuildingTools(server, bridge);
   registerParallelTaskTool(server, bridge);
   registerDocsTools(server);
   registerDominusResources(server, bridge);