dominus-cli 2.3.0 → 2.4.0

package/dist/mcp.js

@@ -117,6 +117,11 @@ var CliMsg = {
   V2_CREATE_WELDS: "studio:v2:create_welds",
   V2_QUERY_PARTS: "studio:v2:query_parts",
   V2_SET_SELECTION: "studio:v2:set_selection",
+  V2_GET_METADATA: "studio:v2:get_metadata",
+  V2_SET_ATTRIBUTES: "studio:v2:set_attributes",
+  V2_UPDATE_TAGS: "studio:v2:update_tags",
+  V2_LIST_CALLABLE_METHODS: "studio:v2:list_callable_methods",
+  V2_INVOKE_METHODS: "studio:v2:invoke_methods",
   V2_DELETE: "studio:v2:delete",
   V2_BUILD_UI: "studio:v2:build_ui",
   V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
@@ -572,6 +577,8 @@ For broad tasks with independent Studio branches, prefer run_parallel_task when
 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_get_metadata, studio_set_attributes, and studio_update_tags for saved Instance metadata. Do not create runtime bootstrap scripts or attribute mirrors when direct tags or attributes satisfy the task.
+- Use studio_list_callable_methods before studio_invoke_methods when a task needs an Instance method not covered by a dedicated tool. Dedicated tools remain preferred for common writes.
 - 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.
@@ -580,7 +587,7 @@ 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 and supports setProperties, create, clone, and move operations. Keep related edits together, but stay within its documented limits.
+- studio_apply is transactional and supports setProperties, setAttributes, updateTags, 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.`;
 
@@ -1447,6 +1454,260 @@ function registerDocsTools(server) {
     }
   );
 }
+var finiteNumber2 = z.number().finite();
+var vector2Value = z.object({ x: finiteNumber2, y: finiteNumber2 }).strict();
+var vector3Value = z.object({ x: finiteNumber2, y: finiteNumber2, z: finiteNumber2 }).strict();
+var color3Object = z.object({ r: finiteNumber2, g: finiteNumber2, b: finiteNumber2 }).strict();
+var color3Value = z.union([
+  z.string().min(1).max(100),
+  color3Object,
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var cframeValue = z.array(finiteNumber2).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var numberSequenceKeypoint = z.union([
+  z.tuple([finiteNumber2, finiteNumber2]),
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var colorSequenceKeypoint = z.tuple([finiteNumber2, color3Value]);
+var typedString = z.object({ type: z.literal("string"), value: z.string() }).strict();
+var typedBoolean = z.object({ type: z.literal("boolean"), value: z.boolean() }).strict();
+var typedNumber = z.object({ type: z.literal("number"), value: finiteNumber2 }).strict();
+var typedUDim = z.object({
+  type: z.literal("UDim"),
+  value: z.union([
+    z.object({ scale: finiteNumber2, offset: finiteNumber2 }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedUDim2 = z.object({
+  type: z.literal("UDim2"),
+  value: z.union([
+    z.object({
+      xScale: finiteNumber2,
+      xOffset: finiteNumber2,
+      yScale: finiteNumber2,
+      yOffset: finiteNumber2
+    }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedBrickColor = z.object({ type: z.literal("BrickColor"), value: z.string().min(1).max(100) }).strict();
+var typedColor3 = z.object({ type: z.literal("Color3"), value: color3Value }).strict();
+var typedVector2 = z.object({
+  type: z.literal("Vector2"),
+  value: z.union([vector2Value, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedVector3 = z.object({
+  type: z.literal("Vector3"),
+  value: z.union([vector3Value, z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])])
+}).strict();
+var typedCFrame = z.object({ type: z.literal("CFrame"), value: cframeValue }).strict();
+var typedNumberSequence = z.object({
+  type: z.literal("NumberSequence"),
+  value: z.union([finiteNumber2, z.array(numberSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedColorSequence = z.object({
+  type: z.literal("ColorSequence"),
+  value: z.union([color3Value, z.array(colorSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedNumberRange = z.object({
+  type: z.literal("NumberRange"),
+  value: z.union([finiteNumber2, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedRect = z.object({
+  type: z.literal("Rect"),
+  value: z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+}).strict();
+var typedFont = z.object({
+  type: z.literal("Font"),
+  value: z.union([
+    z.object({
+      family: z.string().min(1).max(500),
+      weight: z.string().min(1).max(100).optional(),
+      style: z.string().min(1).max(100).optional()
+    }).strict(),
+    z.object({
+      Family: z.string().min(1).max(500),
+      Weight: z.string().min(1).max(100).optional(),
+      Style: z.string().min(1).max(100).optional()
+    }).strict()
+  ])
+}).strict();
+var attributeValueSchema = z.discriminatedUnion("type", [
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont
+]);
+var methodArgumentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("nil") }).strict(),
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont,
+  z.object({ type: z.literal("Instance"), value: instanceRefSchema }).strict()
+]);
+var callableMethodSchema = z.enum([
+  "GetAttribute",
+  "GetAttributes",
+  "GetTags",
+  "HasTag",
+  "GetFullName",
+  "IsA",
+  "IsAncestorOf",
+  "IsDescendantOf",
+  "FindFirstChild",
+  "FindFirstChildOfClass",
+  "FindFirstChildWhichIsA",
+  "FindFirstAncestor",
+  "FindFirstAncestorOfClass",
+  "FindFirstAncestorWhichIsA",
+  "GetChildren",
+  "GetDescendants",
+  "GetPivot",
+  "GetScale",
+  "GetBoundingBox",
+  "AddTag",
+  "RemoveTag",
+  "SetAttribute",
+  "PivotTo",
+  "ScaleTo"
+]);
+var attributeUpdateSchema = z.object({
+  target: instanceRefSchema,
+  set: z.array(
+    z.object({
+      name: z.string().min(1).max(100),
+      value: attributeValueSchema
+    })
+  ).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+var tagUpdateSchema = z.object({
+  target: instanceRefSchema,
+  add: z.array(z.string().min(1).max(100)).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+function registerMetadataTools(server, bridge) {
+  server.registerTool(
+    "studio_get_metadata",
+    {
+      title: "Get Roblox Tags and Attributes",
+      description: "Read persistent Instance tags and typed attributes for up to 100 instances. Use this instead of runtime bootstrap scripts or attribute mirrors when inspecting saved Studio metadata.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_GET_METADATA, { targets })
+  );
+  server.registerTool(
+    "studio_set_attributes",
+    {
+      title: "Set Roblox Attributes",
+      description: "Set or remove persistent typed Instance attributes in one undoable batch. Values are explicitly typed and saved with the place; no Play-mode bootstrap is required.",
+      inputSchema: {
+        operations: z.array(attributeUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_SET_ATTRIBUTES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_update_tags",
+    {
+      title: "Update Roblox Tags",
+      description: "Add or remove persistent Instance tags in one undoable batch using Instance:AddTag and RemoveTag. Tags are saved directly in Studio and replicate normally.",
+      inputSchema: {
+        operations: z.array(tagUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_UPDATE_TAGS, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_list_callable_methods",
+    {
+      title: "List Safe Instance Methods",
+      description: "List the guarded Instance methods Dominus can invoke on a specific target, including required classes, argument types, and whether each method reads or writes Studio state.",
+      inputSchema: {
+        target: instanceRefSchema
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ target }) => callStudio(bridge, CliMsg.V2_LIST_CALLABLE_METHODS, { target })
+  );
+  server.registerTool(
+    "studio_invoke_methods",
+    {
+      title: "Invoke Safe Instance Methods",
+      description: "Invoke a bounded allowlist of typed Instance methods. Supports hierarchy queries, metadata methods, GetPivot/GetBoundingBox/GetScale, and undoable AddTag/RemoveTag/SetAttribute/PivotTo/ScaleTo writes. Arbitrary, destructive, yielding, network, and signal methods are blocked in the Studio plugin.",
+      inputSchema: {
+        calls: z.array(
+          z.object({
+            target: instanceRefSchema,
+            method: callableMethodSchema,
+            arguments: z.array(methodArgumentSchema).max(10).optional().default([])
+          })
+        ).min(1).max(50)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ calls }) => callStudio(bridge, CliMsg.V2_INVOKE_METHODS, { calls }, 6e4)
+  );
+}
 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"
@@ -1476,7 +1737,9 @@ var mutationOperationSchema = z.discriminatedUnion("op", [
     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()
-  })
+  }),
+  attributeUpdateSchema.extend({ op: z.literal("setAttributes") }),
+  tagUpdateSchema.extend({ op: z.literal("updateTags") })
 ]);
 var workerProposalSchema = z.object({
   workerId: z.string().min(1).max(64),
@@ -1704,7 +1967,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, clone, or move operations using exact instance refs copied from evidence.",
+          "Only propose setProperties, setAttributes, updateTags, 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: [
@@ -1742,6 +2005,18 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
                         parent: { instanceId: "uuid", pathSegments: ["..."] },
                         name: "CloneName",
                         offset: { x: 0, y: 0, z: 0 }
+                      },
+                      {
+                        op: "setAttributes",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        set: [{ name: "PlotId", value: { type: "number", value: 1 } }],
+                        remove: []
+                      },
+                      {
+                        op: "updateTags",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        add: ["Plot"],
+                        remove: []
                       }
                     ],
                     risks: ["string"],
@@ -1978,11 +2253,12 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
   });
   const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
   const inspectOperations = operations.filter(
-    (operation) => operation.op !== "create" && operation.op !== "clone"
+    (operation) => operation.op === "setProperties" || operation.op === "move"
   );
   const inspectFailures = [];
   const propertyMismatches = [];
   const moveMismatches = [];
+  const metadataMismatches = [];
   for (let offset = 0; offset < inspectOperations.length; offset += 20) {
     const batch = inspectOperations.slice(offset, offset + 20);
     const targets = batch.map((operation) => operation.target);
@@ -2027,8 +2303,77 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
       }
     });
   }
+  const metadataOperations = operations.filter(
+    (operation) => operation.op === "setAttributes" || operation.op === "updateTags"
+  );
+  for (let offset = 0; offset < metadataOperations.length; offset += 100) {
+    const batch = metadataOperations.slice(offset, offset + 100);
+    const metadata = await requestStudio(bridge, CliMsg.V2_GET_METADATA, {
+      targets: batch.map((operation) => operation.target)
+    });
+    const results = Array.isArray(metadata.results) ? metadata.results : [];
+    batch.forEach((operation, index) => {
+      const result = results[index];
+      const targetLabel = refLabel(operation.target);
+      if (!result) {
+        inspectFailures.push(`${targetLabel}: missing metadata inspection result`);
+        return;
+      }
+      if (operation.op === "setAttributes") {
+        const attributes = Array.isArray(result.attributes) ? result.attributes : [];
+        const actual = new Map(attributes.map((entry) => [String(entry.name), entry.value]));
+        for (const item of operation.set) {
+          const actualValue = actual.get(item.name);
+          if (!actual.has(item.name) || !valuesEquivalent(item.value, actualValue)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name: item.name,
+              expected: item.value,
+              actual: actualValue
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (actual.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name,
+              expected: "absent",
+              actual: actual.get(name)
+            });
+          }
+        }
+      } else {
+        const tags = new Set(Array.isArray(result.tags) ? result.tags.map(String) : []);
+        for (const name of operation.add) {
+          if (!tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: true,
+              actual: false
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: false,
+              actual: true
+            });
+          }
+        }
+      }
+    });
+  }
   return {
-    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && inspectFailures.length === 0,
+    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && metadataMismatches.length === 0 && inspectFailures.length === 0,
     treeNodeCount: tree.nodeCount,
     treeTruncated: tree.truncated,
     expectedCreates: expectedCreates.length,
@@ -2036,6 +2381,7 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
     missingCreates,
     propertyMismatches,
     moveMismatches,
+    metadataMismatches,
     inspectFailures
   };
 }
@@ -2044,6 +2390,7 @@ function findRepairOperations(operations, verification, originalRoot) {
   const missingCreates = new Set(verification.missingCreates);
   const mismatchedTargets = new Set(verification.propertyMismatches.map((item) => item.target));
   const mismatchedMoves = new Set(verification.moveMismatches.map((item) => item.target));
+  const mismatchedMetadata = new Set(verification.metadataMismatches.map((item) => item.target));
   return operations.filter((operation) => {
     if (operation.op === "create") {
       const parentPath = resolveRefPath(operation.parent, knownPaths);
@@ -2051,6 +2398,9 @@ function findRepairOperations(operations, verification, originalRoot) {
     }
     if (operation.op === "clone") return false;
     if (operation.op === "setProperties") return mismatchedTargets.has(refLabel(operation.target));
+    if (operation.op === "setAttributes" || operation.op === "updateTags") {
+      return mismatchedMetadata.has(refLabel(operation.target));
+    }
     return mismatchedMoves.has(refLabel(operation.target));
   });
 }
@@ -2253,11 +2603,15 @@ var cloneOperation = z.object({
   offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
   properties: propertiesSchema3.optional()
 });
+var setAttributesOperation = attributeUpdateSchema.extend({ op: z.literal("setAttributes") });
+var updateTagsOperation = tagUpdateSchema.extend({ op: z.literal("updateTags") });
 var mutationOperation = z.discriminatedUnion("op", [
   setPropertiesOperation,
   createOperation,
   cloneOperation,
-  moveOperation
+  moveOperation,
+  setAttributesOperation,
+  updateTagsOperation
 ]);
 var uiNodeSchema = z.lazy(
   () => z.object({
@@ -2367,7 +2721,7 @@ function registerStudioTools(server, bridge) {
     "studio_apply",
     {
       title: "Apply Atomic Studio Mutations",
-      description: "Atomically set properties, create instances, deep-clone instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+      description: "Atomically set properties or typed attributes, update tags, 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: {
@@ -2493,7 +2847,7 @@ function registerStudioTools(server, bridge) {
     "studio_get_reflection",
     {
       title: "Read Live Roblox Reflection",
-      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata.",
+      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata. Reflection discovers APIs but does not grant call permission; use studio_list_callable_methods for that.",
       inputSchema: { className: z.string().min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2508,7 +2862,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.3.0";
+var VERSION = "2.4.0";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2522,6 +2876,7 @@ function createDominusMcpServer(bridge) {
   registerConnectionTools(server, bridge);
   registerStudioTools(server, bridge);
   registerBuildingTools(server, bridge);
+  registerMetadataTools(server, bridge);
   registerParallelTaskTool(server, bridge);
   registerDocsTools(server);
   registerDominusResources(server, bridge);