dominus-cli 2.0.0 → 2.1.0

package/docs/DOMINUS_2_PLAN.md

@@ -0,0 +1,75 @@
+# Dominus 2 Rewrite Plan
+
+## Product direction
+
+Dominus 2 is a Roblox Studio MCP server, not a standalone AI chat CLI. The MCP
+host supplies the model and consent UI. Dominus supplies a small, strongly typed
+set of Studio inspection, mutation, documentation, and verification tools.
+
+## July 2026 compatibility target
+
+- Target the stable MCP 2025-11-25 protocol through the official TypeScript SDK.
+- Use `registerTool`, strict input schemas, output schemas, `structuredContent`,
+  text fallbacks, `isError`, and accurate tool risk annotations.
+- Keep stdio as the MCP transport. It limits the MCP server itself to the process
+  that launched it and avoids exposing another localhost HTTP endpoint.
+- Do not depend on legacy sampling, roots, or MCP logging. They are deprecated in
+  the 2026-07-28 release candidate.
+- Do not adopt the legacy experimental Tasks API. Long Studio calls remain normal
+  cancellable tool calls until the July Tasks extension is final and broadly
+  supported by clients and the TypeScript SDK.
+
+Official references:
+
+- https://modelcontextprotocol.io/specification/2025-11-25/server/tools
+- https://ts.sdk.modelcontextprotocol.io/server
+- https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices
+- https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/
+
+## Architecture
+
+1. MCP host starts `dominus-mcp` over stdio.
+2. Dominus owns or securely relays to one loopback WebSocket bridge on port 18088.
+3. The Studio plugin authenticates with a persistent random bridge token. First
+   use requires a six-digit pairing code displayed inside Studio.
+4. Every Studio window receives a unique connection ID. MCP callers select that
+   ID, so two windows editing the same place cannot overwrite each other's target.
+5. Studio instances are returned as session-scoped instance references with path
+   segments for display and fallback. Dot-separated names are not identifiers.
+6. Mutations run through a command allowlist and ChangeHistoryService recordings.
+   Failed batches are cancelled and automatically undone.
+7. Script writes require the revision hash returned by the read operation.
+8. There is no arbitrary Luau execution tool.
+
+## MCP tool surface
+
+- `dominus_status`, `dominus_pair_studio`, `dominus_select_studio`
+- `studio_get_tree`, `studio_inspect`, `studio_get_selection`
+- `studio_read_script`, `studio_update_script`
+- `studio_apply`, `studio_delete_instances`
+- `studio_build_ui`, `studio_snapshot_ui`
+- `studio_run_test`, `studio_get_output`
+- `roblox_search_api`, `roblox_get_api`
+
+The intended agent loop is inspect, plan, apply, read back, test. Tool descriptions
+and the server prompt make that workflow explicit without embedding another LLM
+inside the MCP server.
+
+## Safety limits
+
+- Loopback-only listener and authenticated controller/plugin handshakes.
+- One MiB WebSocket payload limit, handshake timeout, request timeout, and bounded
+  tool arrays/depth/source lengths.
+- Dedicated mutation tools only; no `loadstring` or generic `run_code` path.
+- Explicit destructive tool for deletion.
+- Atomic UI replacement: build and validate off-tree before replacing the live UI.
+- Output watcher filters every Dominus-prefixed message to prevent feedback loops.
+
+## Verification
+
+- Transport tests cover authentication, pairing, wrong-target responses,
+  disconnect isolation, duplicate place sessions, and payload rejection.
+- Protocol and MCP tests cover schema validation and structured result shapes.
+- Static plugin checks plus `rojo build` verify the packaged plugin model.
+- Final gates: TypeScript typecheck, targeted Vitest, full Vitest, build, and
+  `npm pack --dry-run`.

package/package.json

@@ -1,40 +1,31 @@
 {
   "name": "dominus-cli",
-  "version": "2.0.0",
-  "description": "AI-powered autonomous agent for Roblox Studio development. Real-time WebSocket bridge, persistent memory, and intelligent tool use.",
+  "version": "2.1.0",
+  "description": "Dominus 2: a secure, MCP-native Roblox Studio engineering agent bridge.",
   "type": "module",
   "bin": {
-    "dominus": "./dist/index.js",
-    "dominus-mcp": "./dist/mcp.js"
+    "dominus-mcp": "./dist/mcp.js",
+    "dominus-install-plugin": "./dist/install-plugin.js"
   },
-  "main": "./dist/index.js",
+  "main": "./dist/mcp.js",
   "scripts": {
-    "dev": "tsx src/index.tsx",
-    "dev:mcp": "nodemon --watch src -e ts,tsx --exec \"pnpm run build && node dist/mcp.js\"",
+    "dev": "tsx src/mcp/index.ts",
+    "dev:mcp": "tsx src/mcp/index.ts",
     "build": "tsup",
     "build:plugin": "rojo build plugin/default.project.json -o plugin/Dominus.rbxm",
-    "start": "node dist/index.js",
+    "start": "node dist/mcp.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "prettier --check .",
     "format": "prettier --write .",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build",
-    "install-plugin": "tsx src/install-plugin.ts"
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build && pnpm build:plugin",
+    "install-plugin": "node dist/install-plugin.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.0",
-    "chalk": "^5.4.1",
-    "commander": "^13.1.0",
-    "figures": "^6.1.0",
-    "ink": "^5.1.0",
-    "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "nanoid": "^5.1.0",
-    "openai": "^4.77.0",
-    "react": "^18.3.1",
-    "sql.js": "^1.14.0",
     "ws": "^8.18.0",
     "zod": "^3.24.0"
   },
@@ -43,8 +34,17 @@
     "@types/react": "^18.3.0",
     "@types/ws": "^8.5.0",
     "@vitest/coverage-v8": "^2.1.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "figures": "^6.1.0",
+    "ink": "^5.1.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
     "nodemon": "^3.1.14",
+    "openai": "^4.77.0",
     "prettier": "^3.4.0",
+    "react": "^18.3.1",
+    "sql.js": "^1.14.0",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
@@ -55,19 +55,18 @@
   },
   "files": [
     "dist",
-    "plugin"
+    "plugin",
+    "CHANGELOG.md",
+    "docs/DOMINUS_2_PLAN.md"
   ],
   "keywords": [
     "roblox",
     "roblox-studio",
-    "cli",
-    "tui",
-    "ai",
+    "mcp-server",
     "agent",
     "luau",
     "dominus",
     "websocket",
-    "openrouter",
     "mcp",
     "model-context-protocol"
   ],

package/plugin/src/CommandRouter.lua

@@ -0,0 +1,94 @@
+local Explorer = require(script.Parent.Explorer)
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local Mutation = require(script.Parent.Mutation)
+local Properties = require(script.Parent.Properties)
+local Reflection = require(script.Parent.Reflection)
+local TestRunner = require(script.Parent.TestRunner)
+local UIBuilder = require(script.Parent.UIBuilder)
+local Watcher = require(script.Parent.Watcher)
+
+local CommandRouter = {}
+
+local handlers = {
+	["studio:v2:get_tree"] = function(payload)
+		return Explorer.getTreeV2(payload)
+	end,
+	["studio:v2:inspect"] = function(payload)
+		return Properties.inspectV2(payload)
+	end,
+	["studio:v2:get_selection"] = function()
+		local Selection = game:GetService("Selection")
+		local selected = {}
+		for _, instance in Selection:Get() do
+			table.insert(selected, {
+				name = instance.Name,
+				className = instance.ClassName,
+				ref = InstanceRegistry.toRef(instance),
+			})
+		end
+		return { success = true, selection = selected }
+	end,
+	["studio:v2:read_script"] = function(payload)
+		return Explorer.readScriptV2(payload)
+	end,
+	["studio:v2:update_script"] = function(payload)
+		return Explorer.updateScriptV2(payload)
+	end,
+	["studio:v2:apply"] = function(payload)
+		return Mutation.apply(payload)
+	end,
+	["studio:v2:delete"] = function(payload)
+		return Mutation.delete(payload)
+	end,
+	["studio:v2:build_ui"] = function(payload)
+		return UIBuilder.buildV2(payload)
+	end,
+	["studio:v2:snapshot_ui"] = function(payload)
+		return UIBuilder.snapshotV2(payload)
+	end,
+	["studio:v2:run_test"] = function(payload)
+		return TestRunner.executeV2(payload)
+	end,
+	["studio:v2:get_output"] = function(payload)
+		local result = Watcher.getRecentOutput(math.clamp(payload.limit or 100, 1, 500), payload.level)
+		result.success = true
+		return result
+	end,
+	["studio:v2:get_reflection"] = function(payload)
+		if type(payload.className) ~= "string" then
+			return { success = false, error = "className must be a string" }
+		end
+		return Reflection.getClassInfo(payload.className)
+	end,
+}
+
+function CommandRouter.handle(message, sendResponse)
+	if type(message) ~= "table" or type(message.id) ~= "string" or #message.id > 128 then
+		return false, "Invalid Dominus request envelope"
+	end
+	if type(message.type) ~= "string" or type(message.payload) ~= "table" then
+		return false, "Invalid Dominus request type or payload"
+	end
+
+	local handler = handlers[message.type]
+	if not handler then
+		sendResponse(message.id, {
+			success = false,
+			error = "Command is not allowed by the Dominus 2 plugin: " .. message.type,
+		})
+		return true
+	end
+
+	task.spawn(function()
+		local ok, result = pcall(handler, message.payload)
+		if not ok then
+			result = { success = false, error = "Command failed: " .. tostring(result) }
+		elseif type(result) ~= "table" then
+			result = { success = false, error = "Command returned an invalid result" }
+		end
+		sendResponse(message.id, result)
+	end)
+	return true
+end
+
+return CommandRouter