dominus-cli 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+## 2.1.1 (2026-07-13)
+
+### Studio connection reliability
+
+- Made pending WebStream connection attempts cancellable so overlapping retries
+  cannot strand a waiting coroutine or deadlock future reconnects.
+- Serialized reconnect attempts and reset failed open transports explicitly.
+- Changed the Dominus 2 toolbar button to always force an immediate reconnect
+  instead of toggling automatic reconnection off.
+
+### Typed mutations and packaging
+
+- Fixed valid Enum values such as `Slate`, `Wood`, `Glass`, and `Ball` being
+  rejected by resolving names against the live Enum type's items.
+- Removed the stale binary `.rbxm` build artifact. The package and installer now
+  use the single canonical `.rbxmx` plugin build.
+- Corrected documentation to describe the 16-tool MCP catalog and optional Studio
+  restart behavior.
+
+## 2.1.0 (2026-07-12)
+
+Dominus has been rewritten as an MCP-first Roblox Studio engineering server.
+
+### MCP-native agent harness
+
+- Removed the Ink/TUI command from the published binaries. Dominus now relies on
+  the MCP host's model, context, consent UI, and agent runtime.
+- Replaced the monolithic legacy catalog with 16 focused tools for connection
+  management, inspection, transactional changes, UI, scripts, tests, and docs.
+- Added strict input schemas, output schemas, `structuredContent`, text fallbacks,
+  `isError`, and accurate read-only/destructive/idempotent/open-world annotations.
+- Added the `dominus-workflow` MCP prompt and `dominus://status` resource.
+- Added explicit inspect, plan, apply, read-back, and test instructions, including
+  UI fidelity checks for fonts, UDim2 values, colors, strokes, and hierarchy.
+- Updated the official MCP TypeScript SDK from 1.27.0 to 1.29.0.
+
+### Secure Studio bridge
+
+- Bound the WebSocket bridge to `127.0.0.1` instead of every network interface.
+- Added a persistent 256-bit bridge token that is provisioned directly into the
+  local plugin by `dominus-install-plugin`; users do not complete a pairing flow.
+- Authenticated relay/controller processes as well as Studio plugin connections.
+- Added one MiB payload limits, socket rate limits, handshake timeouts, bounded
+  request timeouts, and strict message-envelope validation.
+- Removed arbitrary `run_code` from the MCP surface and removed the plugin's
+  `loadstring` executor from the packaged model.
+- Isolated in-flight requests to the exact Studio WebSocket that owns them;
+  wrong-session responses are ignored and one disconnect cannot cancel another
+  session's work.
+
+### Multi-Studio correctness
+
+- Replaced place-ID targeting with unique connection IDs. Multiple windows on the
+  same place ID are now safe and independently selectable.
+- Relay clients carry their selected connection on each request, so separate MCP
+  processes cannot overwrite each other's active target.
+- Added `dominus_status` and `dominus_select_studio`.
+
+### Studio plugin harness
+
+- Replaced the broken ten-port scanner with one configurable loopback endpoint and
+  exponential reconnect backoff.
+- `WsClient` now waits for the real `WebStreamClient.Opened` event and handles
+  `Error`, `Closed`, timeouts, stale attempts, and signal cleanup correctly.
+- Added a strict command allowlist and bounded command router.
+- Added session-scoped instance references with path-segment fallback. Dots and
+  duplicate sibling names are no longer silently misresolved.
+- Updated ReflectionService integration to current `Type`, `Display`, and `Permits`
+  fields.
+- Added typed Roblox value encoding/decoding with surfaced property failures.
+- Added atomic mutation batches backed by ChangeHistoryService recordings. Failed
+  batches cancel and automatically undo in-progress work.
+- UI trees are fully built and validated off-tree before an existing UI is
+  replaced. Ambiguous replacements and silent property failures are rejected.
+- Script reads return a revision hash; writes require it and reject stale edits.
+- Studio tests now use bounded Run, Play, or Multiplayer StudioTestService flows,
+  reject overlapping runs, and leave timed-out sessions.
+- Output forwarding excludes all Dominus-prefixed messages, closing the previous
+  WebSocket warning feedback loop.
+
+### Packaging and tests
+
+- Added the `dominus-install-plugin` executable and fixed the previously missing
+  installer implementation.
+- The published runtime dependency set is MCP-only; old CLI dependencies are
+  development-only and excluded from the MCP bundle.
+- Added transport tests for auth, credential rejection, relays, duplicate places, wrong-target
+  responses, and disconnect isolation.
+- Added in-memory MCP conformance tests for the tool catalog, structured outputs,
+  resources, prompts, routing, and error results.
+- Added static plugin hardening tests and Rojo package verification.
+
+### Breaking changes
+
+- The `dominus` TUI command is removed. Configure `dominus-mcp` in an MCP host.
+- Legacy tool names such as `run_code`, `set_properties`, and `create_ui` are
+  replaced by the v2 tool catalog.
+- Dot-separated instance paths are replaced by instance refs containing
+  `instanceId` and/or `pathSegments`.
+- Script updates require `expectedRevision` from `studio_read_script`.
+- Existing UI is not replaced unless `replaceExisting: true` is supplied.
+
+## 0.5.5 (2026-04-23)
+
+### New MCP Tools (30 total, up from 24)
+
+- **`move_instance`** — Reparent an instance preserving all descendants. Sets ChangeHistoryService waypoint.
+- **`bulk_set_properties`** — Set properties on multiple instances in one call. Explicit paths or className filter mode.
+- **`find_replace_scripts`** — Find and replace across all scripts with optional Lua pattern matching and dry run preview.
+- **`undo`** — Undo last action (ChangeHistoryService). Like Ctrl+Z.
+- **`redo`** — Redo last undone action. Like Ctrl+Y.
+
+### Improvements
+
+- **`get_properties` now supports compact mode** — Same filtering as `get_descendants_properties`. Strips read-only, nil, deprecated, and default-valued properties by default. The previous version returned all ~50 properties per instance even though most were noise.
+- **Fixed code injection in `clone_instance`, `group_instances`, `build_multiple`** — Instance names and paths with special characters (quotes, backslashes) no longer break generated Luau code.
+- **`build_multiple` now supports `rgb()` colors and `canCollide`** — Previously only handled `#hex` and BrickColor names; `rgb(255,0,0)` would silently fail.
+- **Better tool descriptions** — More specific descriptions help AI models pick the right tool. `get_properties` disambiguates vs `serialize_ui` and `get_descendants_properties`.
+- **Shared `luaStr()` and `resolvePath()` helpers** — Centralized safe string generation for all code-gen tools.
+
+## 0.5.4 (2026-04-23)
+
+### Fixes
+
+- **Rebuilt plugin** — 0.5.3 shipped a stale `Dominus.rbxm` missing the compact property filtering and protocol changes. This release includes the correctly built plugin.
+
+## 0.5.3 (2026-04-23)
+
+### Improvements
+
+- **Compact `get_descendants_properties`** — Now strips read-only, nil, deprecated, and default-valued properties by default, reducing response size by ~80%. Pass `compact: false` for the full dump.
+- **`serialize_ui` exposed as MCP tool** — Was previously only in the internal tool registry. Now available to all MCP clients (Copilot, Cursor, Claude, etc.) for converting existing Roblox UI into clean JSON trees.
+- **UI → Roact/React conversion guidance** — System prompt and internal memory now teach the agent the full workflow: `serialize_ui` → JSON tree → Roact/React component with correct type mappings (UDim2, Color3, Vector2, enums, FontFace).
+- **Smarter tool selection** — Agent now prefers `serialize_ui` over `get_descendants_properties` for UI conversion tasks, avoiding context bloat.
+
+## 0.2.1 (2026-02-24)
+
+### New
+
+- **Auto-update checker** — On startup, Dominus checks npm for newer versions
+  and prints an upgrade notice. Cached for 4 hours, non-blocking, never throws.
+
+### Bug Fixes
+
+- **MCP server crashes on EADDRINUSE** — `dominus mcp` would crash if port 18088
+  was already held by a running `dominus start` (or another MCP instance). The MCP
+  server now checks for an existing listener and connects as a relay client instead
+  of trying to bind the same port.
+
+### New MCP Tools (22 total, up from 14)
+
+- **`get_class_info`** — Look up the full schema of any Roblox class via
+  ReflectionService (properties, methods, events with types).
+- **`create_ui`** — Create an entire UI tree in one call with a declarative JSON
+  spec. Auto-coerces UDim2, Color3, Font, and enums. ~10x faster than `run_code`.
+- **`create_part`** — One-call Part creation with position, size, color, material,
+  shape, transparency, anchored, and collision settings.
+- **`clone_instance`** — Clone an instance with optional rename, reparent, and
+  position offset.
+- **`group_instances`** — Group multiple instances into a Model or Folder.
+- **`build_multiple`** — Batch-create many parts/instances in a single round-trip.
+- **`execute_run_test`** — Enter Run mode via `StudioTestService:ExecuteRunModeAsync()`
+  with pass-through args and result capture.
+- **`execute_play_test`** — Enter Play mode via `StudioTestService:ExecutePlayModeAsync()`
+  for full client-server simulation tests.
+
+### New CLI Features
+
+- **`dominus mcp-install`** — Auto-install MCP config into Cursor, VS Code,
+  Claude Desktop, Windsurf, and Claude Code with one command.
+- **`dominus mcp-setup`** — Print manual MCP configuration instructions.
+- **Relay client architecture** — `dominus start` can now connect as a relay
+  client to an existing MCP-owned WebSocket server, allowing the TUI and MCP
+  to coexist on the same port.
+
+### Plugin Improvements
+
+- Enhanced `Properties.lua` with broader property type support.
+- Improved `Reflection.lua` for richer class metadata.
+- Updated `TestRunner.lua` with Run/Play mode test support.
+- New `UIBuilder.lua` module for server-side declarative UI construction.
+
+### Other Changes
+
+- Multi-provider AI config improvements (OpenRouter, xAI, Gemini, custom).
+- TUI setup wizard for first-run API key and provider configuration.
+- Improved system prompt with builder-tool awareness.
+- WebSocket server now supports controller relay connections.
+
+## 0.1.0 (2026-02-23)
+
+- Initial release — 14 MCP tools, TUI agent, persistent memory, Roblox Studio
+  WebSocket bridge.

package/README.md

@@ -1,248 +1,162 @@
-# Dominus
-
-**AI-powered autonomous agent for Roblox Studio development.**
-
-Dominus connects to Roblox Studio over WebSocket, giving you a terminal-based AI assistant that can read scripts, edit code, run Luau, browse the explorer tree, manage instances, upload assets, and run tests -- all in real-time.
-
-```
-      ◆           ◆           ◆
-     ╔█╗         ╔█╗         ╔█╗
-    ╔╝ █ ╚╗     ╔╝ █ ╚╗     ╔╝ █ ╚╗
-    ╚████████████████████████████████╝
-         D  O  M  I  N  U  S
-```
-
-## Features
-
-- **Autonomous AI Agent** -- Plans, executes, and verifies multi-step tasks using tool calls (not just chat)
-- **Real-time Studio Bridge** -- Bidirectional WebSocket connection to Roblox Studio via plugin
-- **Persistent Memory** -- SQLite-backed memory that learns your project across sessions
-- **15 Built-in Tools** -- Read/edit scripts, run code, browse explorer, manage instances, search, upload assets, run tests
-- **Beautiful TUI** -- Ink-powered terminal interface with explorer tree, chat, output log, and live tool indicators
-- **Multi-Model Support** -- Use any AI model via OpenRouter (Claude, GPT-4o, Gemini, Llama, DeepSeek, etc.)
-- **Open Cloud Integration** -- Upload images, models, and audio directly to Roblox
-- **Configurable Rules** -- Tell Dominus what to do and what not to do with persistent rules
-- **StudioTestService** -- Run tests directly from the terminal
-- **Plugin Auto-Install** -- One command to install the Studio plugin
-
-## Quick Start
-
-### 1. Install Dominus
-
-```bash
-# With pnpm (recommended)
-pnpm add -g dominus-cli
-
-# Or with npm
-npm install -g dominus-cli
-```
-
-### 2. Set Your API Key
-
-Get an API key from [OpenRouter](https://openrouter.ai/settings/keys) (free tier available):
-
-```bash
-dominus config set apiKey sk-or-v1-your-key-here
-```
-
-Or use an environment variable:
-
-```bash
-export OPENROUTER_API_KEY=sk-or-v1-your-key-here
-```
-
-### 3. Install the Studio Plugin
-
-```bash
-dominus install-plugin
-```
-
-This copies the Dominus plugin to your Roblox Studio plugins folder. Restart Studio to load it.
-
-### 4. Launch Dominus
-
-```bash
-dominus
-```
-
-The TUI will start, open a WebSocket server on port 18088, and wait for Studio to connect. In Studio, click the **Dominus > Connect** button in the toolbar.
-
-## Configuration
-
-All config is stored at `~/.dominus/config.json`.
-
-```bash
-# Set your API key
-dominus config set apiKey <key>
-
-# Change the AI model
-dominus config set model openai/gpt-4o
-
-# Change the WebSocket port
-dominus config set port 9090
-
-# Set your display name
-dominus config set userName Eli
-
-# Set up Open Cloud for asset uploads
-dominus config set openCloudApiKey <your-open-cloud-key>
-
-# View all settings
-dominus config list
-```
-
-### Available Models
-
-Any model on [OpenRouter](https://openrouter.ai/models) works. Popular choices:
-
-| Model | ID |
-|---|---|
-| Claude Sonnet 4 | `anthropic/claude-sonnet-4` |
-| GPT-4o | `openai/gpt-4o` |
-| GPT-4o Mini | `openai/gpt-4o-mini` |
-| Gemini 2.0 Flash | `google/gemini-2.0-flash-001` |
-| DeepSeek V3 | `deepseek/deepseek-chat` |
-| Llama 3.3 70B | `meta-llama/llama-3.3-70b-instruct` |
-
-## Agent Rules
-
-Tell Dominus what to do (and what NOT to do):
-
-```bash
-# Add rules
-dominus rules add-do "Always use strict Luau type annotations"
-dominus rules add-do "Follow Knit framework patterns"
-dominus rules add-dont "Never use deprecated APIs like wait()"
-dominus rules add-dont "Don't modify the DataStore schema without asking"
-
-# View rules
-dominus rules list
-```
-
-Rules persist across sessions at `~/.dominus/rules.json`.
-
-## TUI Commands
-
-Inside the Dominus terminal:
-
-| Command | Description |
-|---|---|
-| (just type) | Chat with the AI agent |
-| `/help` | Show all commands |
-| `/run <code>` | Execute Luau in Studio |
-| `/model <id>` | Switch AI model |
-| `/clear` | Clear chat history |
-| `/status` | Show connection info |
-| `/index` | Re-index project scripts |
-| `/memory` | Show recalled facts |
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│  Terminal                                            │
-│  ┌─────────────────────────────────────────────────┐ │
-│  │  Dominus TUI (Ink/React)                        │ │
-│  │  ┌──────────┐ ┌───────────────────────────────┐ │ │
-│  │  │ Explorer  │ │ AI Chat + Tool Indicators     │ │ │
-│  │  │          │ │                               │ │ │
-│  │  └──────────┘ └───────────────────────────────┘ │ │
-│  │  ┌─────────────────────────────────────────────┐ │ │
-│  │  │ Output Log                                  │ │ │
-│  │  └─────────────────────────────────────────────┘ │ │
-│  │  ┌─────────────────────────────────────────────┐ │ │
-│  │  │ > Input                                     │ │ │
-│  │  └─────────────────────────────────────────────┘ │ │
-│  └─────────────────────────────────────────────────┘ │
-│                         │                            │
-│              ┌──────────┴──────────┐                 │
-│              │  Agent Loop         │                 │
-│              │  (Plan→Execute→     │                 │
-│              │   Verify→Learn)     │                 │
-│              └──────────┬──────────┘                 │
-│                         │                            │
-│     ┌───────────────────┼───────────────────┐        │
-│     │                   │                   │        │
-│  ┌──┴──┐          ┌─────┴─────┐       ┌────┴────┐   │
-│  │Tools│          │  Memory   │       │   AI    │   │
-│  │(15) │          │ (SQLite)  │       │Provider │   │
-│  └──┬──┘          └───────────┘       └─────────┘   │
-│     │                                                │
-└─────┼────────────────────────────────────────────────┘
-      │ WebSocket
-      │
-┌─────┴────────────────────────────────────────────────┐
-│  Roblox Studio                                        │
-│  ┌─────────────────────────────────────────────────┐  │
-│  │  Dominus Plugin                                 │  │
-│  │  (WS Client → Explorer, Executor, Watcher,     │  │
-│  │   Properties, Reflection, TestRunner)           │  │
-│  └─────────────────────────────────────────────────┘  │
-└───────────────────────────────────────────────────────┘
-```
-
-## Studio Plugin
-
-The plugin uses the **WebSocket API** introduced in Roblox Studio (October 2025):
-
-```lua
-HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = "ws://localhost:18088" })
-```
-
-### Building with Rojo
-
-If you have [Rojo](https://rojo.space/) installed:
-
-```bash
-pnpm build:plugin
-```
-
-This creates `plugin/Dominus.rbxm` that you can drag into Studio.
-
-### Manual Install
-
-```bash
-dominus install-plugin
-```
-
-Copies the plugin Lua files directly to your Studio plugins folder.
-
-## Development
-
-```bash
-# Clone and install
-git clone https://github.com/eli/dominus.git
-cd dominus
-pnpm install
-
-# Run in dev mode
-pnpm dev
-
-# Run tests
-pnpm test
-
-# Type check
-pnpm typecheck
-
-# Build
-pnpm build
-
-# Format
-pnpm format
-```
-
-## Tech Stack
-
-- **TypeScript** + **Node.js 20+** -- Runtime
-- **Ink 5** (React for CLI) -- Terminal UI framework
-- **ws** -- WebSocket server
-- **OpenAI SDK** -- AI provider (OpenRouter-compatible)
-- **sql.js** -- SQLite in WASM (persistent memory)
-- **Commander** -- CLI argument parsing
-- **Vitest** -- Test runner
-- **tsup** -- Bundler
-- **Rojo** -- Roblox plugin builder
-
-## License
-
-MIT
+# Dominus 2
+
+Dominus 2 is a secure, MCP-native engineering bridge for Roblox Studio. It gives
+an MCP host direct, typed access to Studio instances, scripts, UI, reflection,
+output, and tests without embedding a second chat model or exposing arbitrary
+Luau execution.
+
+## What changed
+
+- MCP-only product: the old Ink chat CLI is no longer published.
+- 16 focused tools with input/output schemas, structured results, and risk hints.
+- Stable instance refs survive dots in names, renames, reparenting, and duplicate
+  sibling names for the life of the Studio session.
+- Script writes require a revision from `studio_read_script`.
+- Mutation batches and UI replacement are undoable and roll back on failure.
+- The installer provisions a private bridge token into the local Studio plugin.
+- Multiple Studio windows are selected by unique connection ID, not place ID.
+- Roblox Creator Docs API lookup is built in.
+
+## Requirements
+
+- Node.js 20 or newer
+- Roblox Studio with HTTP requests enabled for Studio/plugin use
+- An MCP client such as Codex, Claude Desktop, Cursor, or VS Code
+
+Dominus does not require its own AI API key. Your MCP host supplies the model.
+
+## Install
+
+Install the npm package globally:
+
+```powershell
+npm install -g dominus-cli@latest
+```
+
+Install or update the Studio plugin:
+
+```powershell
+dominus-install-plugin
+```
+
+Roblox Studio normally reloads the local plugin automatically. Restart Studio
+only if the Dominus 2 toolbar button does not appear or reconnect.
+
+## MCP configuration
+
+Add Dominus to your MCP client's server configuration:
+
+```json
+{
+  "mcpServers": {
+    "dominus": {
+      "command": "dominus-mcp"
+    }
+  }
+}
+```
+
+For a version-pinned configuration that does not require a global install:
+
+```json
+{
+  "mcpServers": {
+    "dominus": {
+      "command": "npx",
+      "args": ["-y", "-p", "dominus-cli@2.1.1", "dominus-mcp"]
+    }
+  }
+}
+```
+
+Restart the MCP client after changing its configuration.
+
+## First connection
+
+1. Run `dominus-install-plugin`; restart Roblox Studio only if it does not reload.
+2. Start the MCP client so `dominus-mcp` is running.
+3. Open Roblox Studio. The plugin connects and authenticates automatically.
+
+If several Studio windows are open, call `dominus_select_studio` with the exact
+connection ID before editing. Two windows on the same place ID remain distinct.
+
+## Agent workflow
+
+Dominus instructs MCP hosts to use this loop:
+
+1. Inspect the target tree, selection, instances, scripts, and API references.
+2. Plan the smallest coherent change and define acceptance checks.
+3. Apply a transactional mutation or revision-checked script update.
+4. Read the changed state back.
+5. Run a Studio test when behavior changed.
+
+For UI fidelity work, use `studio_snapshot_ui` after `studio_build_ui` and compare
+fonts, UDim2 values, colors, strokes, and hierarchy rather than relying on a
+successful write response alone.
+
+## Tool catalog
+
+Connection tools:
+
+- `dominus_status`
+- `dominus_select_studio`
+
+Studio inspection:
+
+- `studio_get_tree`
+- `studio_inspect`
+- `studio_get_selection`
+- `studio_read_script`
+- `studio_snapshot_ui`
+- `studio_get_output`
+- `studio_get_reflection`
+
+Studio changes and verification:
+
+- `studio_update_script`
+- `studio_apply`
+- `studio_delete_instances`
+- `studio_build_ui`
+- `studio_run_test`
+
+Roblox documentation:
+
+- `roblox_search_api`
+- `roblox_get_api`
+
+## Security model
+
+The MCP transport is stdio. The separate Studio WebSocket bridge binds only to
+`127.0.0.1`, limits messages to one MiB, rate-limits sockets, times out incomplete
+handshakes, and authenticates both Studio plugins and relay controllers. The local
+installer injects a user-specific token into the plugin, so no manual pairing flow
+is needed. The plugin only accepts an explicit command allowlist and contains no
+`loadstring` executor.
+
+The bridge token protects against accidental or opportunistic access by unrelated
+local processes. Like other user-level credentials, it cannot protect against a
+process that already has permission to read all files in the same user account.
+
+## Development
+
+```powershell
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm build:plugin
+npm pack --dry-run
+```
+
+Run the MCP server in development:
+
+```powershell
+pnpm dev:mcp
+```
+
+The design and research notes are in
+[`docs/DOMINUS_2_PLAN.md`](docs/DOMINUS_2_PLAN.md).
+
+## License
+
+MIT