dominus-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# 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