roblox-opencode 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Roblox-OpenCode-blue?style=for-the-badge&logo=roblox&logoColor=white" alt="roblox-opencode" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/roblox-opencode?style=flat-square&color=blue" alt="npm version" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license" />
+  <img src="https://img.shields.io/badge/Luau-100%25-purple?style=flat-square" alt="Luau" />
+  <img src="https://img.shields.io/badge/Fusion-0.3-orange?style=flat-square" alt="Fusion 0.3" />
+</p>
+
+<p align="center">
+  An OpenCode plugin that gives AI assistants deep knowledge of Roblox development.<br/>
+  17 skills, production-ready vendor libraries, and complete UI references. The AI writes code that actually works in Studio.
+</p>
+
+<br/>
+
+## Install
+
+```bash
+npm install roblox-opencode@git+https://github.com/TabooHarmony/roblox-opencode.git --prefix ~/.config/opencode
+```
+
+Then add to your `opencode.json` (global or project):
+
+```json
+{
+  "plugin": ["~/.config/opencode/node_modules/roblox-opencode"]
+}
+```
+
+Restart OpenCode, then run `/setup-game` in your project.
+
+> npm publish is coming soon. Once live, install with `opencode plugin roblox-opencode`.
+
+## What it does
+
+Without this plugin, AI assistants treat Roblox like a generic Lua environment. They miss session locking, write exploitable remotes, ignore mobile players, and produce UI that breaks on phones.
+
+With it, the AI knows:
+
+- How to structure a game (services, lifecycle, module patterns)
+- How to persist data safely (ProfileStore, session locking, migrations)
+- How to build reactive UI (Fusion 0.3, with complete shop/inventory/settings references)
+- How to secure remotes (validation, rate limiting, type checking)
+- How to ship (analytics, monetization, TOS compliance, publish checklist)
+- What NOT to do (13 documented production footguns ranked by severity)
+
+## Skills
+
+Loaded on-demand based on what you're working on. The AI picks the right ones automatically.
+
+| Domain | Skill | Covers |
+|--------|-------|--------|
+| Language | `roblox-luau-mastery` | Syntax, idioms, type system, strict mode |
+| UI | `roblox-gui` | Layout fundamentals, mobile-first, responsive patterns |
+| UI | `roblox-gui-fusion` | Fusion 0.3 reactive UI with full screen references |
+| VFX | `roblox-animation-vfx` | Tweens, particles, trails, highlights, camera shake |
+| Networking | `roblox-networking` | Security hardening, validation, rate limiting |
+| Data | `roblox-data` | ProfileStore, schema design, migrations, BindToClose |
+| Testing | `roblox-testing` | TestEZ, BDD patterns, test strategy |
+| Tooling | `roblox-tooling` | Studio MCP, luau-lsp, diagnostics |
+| Architecture | `roblox-architecture` | Service hierarchy, 7 foundational patterns |
+| Runtime | `roblox-runtime` | RunService, StreamingEnabled, memory |
+| Gotchas | `roblox-sharp-edges` | 13 production footguns by severity |
+| Money | `roblox-monetization` | GamePasses, DevProducts, subscriptions, TOS |
+| Sync | `roblox-sync` | Script Sync setup and troubleshooting |
+| Analytics | `roblox-analytics` | Events, economy tracking, funnels |
+| Review | `roblox-code-review` | Security, performance, networking, data lenses |
+| Debug | `roblox-debug` | Iterative debug loop for Luau issues |
+| Ship | `roblox-publish-checklist` | Pre-ship verification gauntlet |
+
+## Vendor libraries
+
+Copied to your project on setup. No Wally required.
+
+| Library | Purpose |
+|---------|---------|
+| **Fusion** | Reactive UI framework (dphfox, 0.3) |
+| **ProfileStore** | Data persistence with session locking |
+| **Promise** | Async flow control (evaera) |
+| **Signal** | Typed custom signals (Sleitnick) |
+| **Trove** | Cleanup/lifecycle management |
+| **Comm** | Typed client-server remotes |
+| **Component** | CollectionService tag binding |
+| **t** | Runtime type checking |
+| **TestEZ** | BDD testing framework |
+| + RbxUtil | 25 additional utility packages available on demand |
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/setup-game` | One-time project config: skills, vendor, LSP, AGENTS.md |
+| `/sync-check` | Verify Script Sync is working correctly |
+
+## How it works
+
+1. Plugin installs via npm on OpenCode startup
+2. You run `/setup-game` once per project
+3. Setup copies skills + vendor libs to `.opencode/`, writes LSP config, generates `.luaurc` aliases, injects a core block into `AGENTS.md`
+4. After that, the plugin is dormant. The skills do all the work.
+
+The AI loads relevant skills on-demand based on your prompt. Ask it to build a shop and it pulls in `roblox-gui-fusion`. Ask it to review security and it loads `roblox-code-review` with the networking lens.
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai)
+- [Roblox Studio](https://www.roblox.com/create) with Script Sync and MCP server enabled
+
+## Update
+
+Update the version in `opencode.json`, restart OpenCode, and run `/setup-game` again to refresh skills and vendor libs. Content outside managed markers in `AGENTS.md` is preserved.
+
+## Contributors
+
+- [MrFearTick](https://github.com/MrFearTick): Highlight reference, parent destruction patterns, networking lens, monetization expansion
+
+## License
+
+MIT

package/commands/setup-game.md

@@ -0,0 +1,108 @@
+---
+description: "First-time Roblox project setup: skills, vendor libs, LSP, sync"
+agent: build
+---
+
+# /setup-game
+
+One-time project configuration for roblox-opencode. Run this when you first open a Roblox project.
+
+Commands (`/setup-game`, `/sync-check`) are already available globally. Skills (`roblox-code-review`, `roblox-debug`, `roblox-publish-checklist`) are loaded on demand. This command sets up the *project*.
+
+---
+
+## Step 1: Run the setup tool
+
+Call the `roblox_setup` tool. It handles:
+- Copying 17 skills to `.opencode/skills/`
+- Copying vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to `.opencode/vendor/`
+- Writing luau-lsp config to `opencode.json`
+- Writing the core Roblox agent instructions to `AGENTS.md`
+
+Report the results to the user. If any step failed, explain what went wrong and how to fix it.
+
+## Step 2: Check prerequisites
+
+Run these checks (cross-platform):
+
+```bash
+command -v luau-lsp   # needed for Luau diagnostics
+```
+
+If luau-lsp is missing: point user to https://github.com/JohnnyMorganz/luau-lsp/releases and guide install. If declined, note: "Reduced safety net. Install luau-lsp later and re-run /setup-game."
+
+## Step 3: Download globalTypes.d.luau
+
+If luau-lsp is installed, download the Roblox type definitions:
+
+```bash
+curl -fsSL https://luau-lsp.pages.dev/type-definitions/globalTypes.RobloxScriptSecurity.d.luau -o globalTypes.d.luau
+```
+
+This file provides Roblox API types to luau-lsp. The `--definitions` flag in the LSP config (from Step 1) points to it.
+
+## Step 4: Enable Studio MCP
+
+The Roblox Studio MCP server is built into Studio. To enable it:
+
+1. Open Roblox Studio
+2. Open Assistant (View → Assistant)
+3. Click `…` → Manage MCP Servers
+4. Turn on **Enable Studio as MCP server**
+
+For opencode to connect, add this to your project's `opencode.json`:
+
+**Windows:**
+```json
+{
+  "mcp": {
+    "studio": {
+      "type": "local",
+      "command": ["cmd.exe", "/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**macOS:**
+```json
+{
+  "mcp": {
+    "studio": {
+      "type": "local",
+      "command": ["/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"],
+      "enabled": true
+    }
+  }
+}
+```
+
+After adding the config, restart opencode to connect.
+
+## Step 5: Sync setup
+
+Hand off Script Sync setup to the user with these instructions:
+
+"Enable Script Sync in Roblox Studio:
+1. File → Beta Features → Script Sync → toggle on → restart Studio
+2. In Explorer, right-click each top-level container with scripts (ServerScriptService, ReplicatedStorage, etc.) → Start Sync → pick a folder
+
+Suggested folder layout: ~/projects/<game-name>/src/<container-name>/"
+
+"You should now see your scripts in Studio's Explorer matching the files on disk. If you do, sync is working. If the container looks empty, double-check you picked the right folder and that Studio is focused (sync pauses when minimized). Run /sync-check if you need to verify later."
+
+## Step 6: Print the command tour
+
+"roblox-opencode is ready. Here's what you can do:
+
+**Commands** (type `/` to use):
+- /setup-game - re-run this setup (after plugin updates)
+- /sync-check - check if Script Sync is working properly
+
+**Skills** (AI suggests when relevant):
+- roblox-code-review - review code with security/performance/monetization lenses
+- roblox-debug - iterative debug loop for Luau/Roblox issues
+- roblox-publish-checklist - pre-ship gauntlet before publishing
+
+The harness is loaded. Prompt normally - the AI will suggest skills when relevant."

package/commands/sync-check.md

@@ -0,0 +1,53 @@
+---
+description: "Sync sanity check - diagnose when files aren't appearing in Studio"
+agent: build
+---
+
+# /sync-check
+
+On-demand sync sanity check. Run when files aren't appearing in Studio or edits aren't landing on disk.
+
+---
+
+## Step 1: Check mode detection
+
+Try to read any `.luau` file from the project's synced folder. If files exist on disk, you're in Sync Mode. If not, you're in MCP-Only Mode.
+
+Report which mode is active.
+
+## Step 2: Sentinel round-trip (Sync Mode only)
+
+1. Write `_sync_check.luau` to the synced folder with content: `-- roblox-opencode sync verification sentinel`
+2. Ask user: "Did `_sync_check.luau` appear in Studio's Explorer?"
+3. If yes: clean up the sentinel file. Report: "Sync is healthy."
+4. If no: proceed to Step 3.
+
+## Step 3: Troubleshooting (if sentinel failed)
+
+Walk through these in order:
+
+1. "Is Script Sync still enabled? Check File → Beta Features → Script Sync."
+2. "Did you right-click the container and Start Sync to the correct folder?"
+3. "Is Studio focused? Script Sync pauses when Studio is minimized or in the background."
+4. "Try: stop sync on the container, re-start sync, pick the same folder."
+
+If none of these resolve it:
+
+- "Script Sync may have silently disconnected. Restart Studio and re-run /sync-check."
+- Do NOT suggest switching to MCP as a fix. Sync is the canonical path.
+
+## Step 4: MCP-Only Mode check
+
+If in MCP-Only Mode (no files on disk):
+
+1. Check if Studio MCP is registered in opencode.json.
+2. Try a simple MCP call (e.g., list scripts in ServerScriptService).
+3. If MCP responds: "MCP-Only mode is working, but sync is recommended for heavy sessions. Run /setup-game to enable sync."
+4. If MCP fails: "Neither sync nor MCP is working. Run /setup-game to configure the environment."
+
+## Behavior rules
+
+- One diagnostic pass. Don't loop.
+- If sync works, say so and stop. No upselling.
+- If sync is broken, help fix it. Don't suggest MCP as a replacement.
+- Clean up the sentinel file whether the check passes or fails.

package/core/roblox-core.md

@@ -0,0 +1,93 @@
+# roblox-opencode Core Block
+# Written to AGENTS.md by /setup-game between version markers.
+# Budget: ~1.2k tokens. Every line must earn its place.
+
+## 1. Sync vs MCP
+
+1. Every session: try to read project .luau files at the expected synced paths.
+   Found → Sync Mode. Not found → MCP-Only Mode.
+2. Sync Mode: read/write/edit scripts via filesystem. Use MCP only for
+   verification (run_code, execute_luau), playtest control, scene/instance ops.
+3. Sync Mode: never read a script via MCP if its file exists on disk.
+4. MCP-Only Mode: minimize file reads. Prefer run_code for inspection.
+   Batch related edits behind ChangeHistoryService Recording.
+5. MCP-Only Mode: note that MCP ops are slower and token-hungry. If a session
+   will be heavy, recommend the user enable Sync.
+6. MCP-Only Mode loses LSP diagnostics entirely (luau-check hooks filesystem
+   writes only). Surface this when relevant.
+
+## 2. Sharp Edges
+
+| Severity | Issue | Fix |
+|----------|-------|-----|
+| CRIT | DataStore data loss from no session lock | Use ProfileStore. Never raw SetAsync for player data. |
+| CRIT | Client-side currency manipulation | All currency math server-side. Client is display-only. |
+| CRIT | ProcessReceipt mishandling (duplicates/refunds) | Grant item THEN return PurchaseGranted. If grant fails, return NotProcessedYet. |
+| CRIT | Missing BindToClose | Always implement BindToClose to flush pending saves. |
+| HIGH | RemoteEvent flooding | Per-player rate limiting on all remotes. |
+| HIGH | Memory leaks from undisconnected events | Use Trove. Every :Connect() must have a corresponding :Disconnect(). |
+| HIGH | Assuming instances exist with StreamingEnabled | Check existence before access. Instances may not be loaded yet. |
+| MED | Instance.new(class, parent) race | Create first, parent second. Parenting in constructor causes replication race. |
+| LOW | :connect typo | It's :Connect() with capital C. |
+
+## 3. Capabilities Boundary
+
+roblox-opencode handles: Luau code, scripts, modules, remotes, data, UI logic, game architecture.
+roblox-opencode does NOT handle: 3D model generation, mesh creation, animation authoring, terrain sculpting, pixel-perfect UI design. These are Studio's domain - use blockout Parts with descriptive names and let the user detail visually.
+
+## 4. Skill Routing Corrections
+
+Only for ambiguous cases where two skills overlap:
+- streaming/workspace not loaded → roblox-runtime (not roblox-architecture)
+- gui/ui layout → roblox-gui (not roblox-architecture)
+- data persistence → roblox-data (not roblox-networking)
+- remote handler validation → roblox-networking (not roblox-architecture)
+- security hardening → roblox-networking (security is folded in)
+
+For everything else, load the skill whose description best matches the task.
+Load the Quick Reference section first. Only load the Full Reference if the task requires specific syntax examples or implementation details.
+
+## 5. Asset Trust
+
+- Never suggest asset IDs. Never recommend free-model code (ModuleScripts, Scripts, LocalScripts).
+- Free models OK strictly for art assets (Mesh, Texture, Sound, Animation).
+- Before any LoadAsset: walk user through audit - inspect children, check for getfenv/loadstring/HttpService/suspicious RemoteEvents.
+- Vendored libraries (ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component) are the only pre-written code the agent may place.
+
+## 6. Verification
+
+Silence means verified. Surface ⚠️ only when verification was NOT possible:
+"⚠️ not verified: [thing], [reason]"
+Do not prefix verified responses with "Verified: ..." - that noise trains users to stop reading.
+
+## 7. Luau-LSP
+
+- Diagnostics are signal, not authority. On conflict with documented Roblox behavior, prefer documented behavior.
+- Never claim "done, test it" with unresolved diagnostics. Either fix them, justify them, or surface ⚠️.
+- Diagnostics fire async after each .luau write. The agent reconciles silently.
+
+## 8. Tiered Library Policy
+
+**Vendored libraries** (auto-placed with mention): ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component.
+- Agent mentions the choice. User can revert or say "use my own."
+- Before auto-placing, query project index for existing equivalents. If found, skip auto-place and mention why.
+- Placement mechanic: copy from `.opencode/vendor/<path>` into the project's synced folder. Shared libs → ReplicatedStorage/Packages/. Server-only (ProfileStore) → ServerScriptService/Packages/. Infer sync folder from existing project structure.
+
+**Vendored tools** (recommended when relevant, not auto-placed): t (runtime type checking), TestEZ (testing).
+- Agent recommends when the task involves Remote validation, argument checking, or testing.
+- Agent does NOT auto-place - requires user buy-in.
+
+**Anything else**: full consent. Agent explains, asks via user prompts, places only on yes.
+
+## 9. Skill & Command Routing
+
+When the user's task matches a command or skill, suggest it:
+- First-time project setup → /setup-game (command)
+- Sync feels broken → /sync-check (command)
+- Code review or audit → load roblox-code-review skill
+- Debugging → load roblox-debug skill
+- Pre-publish check → load roblox-publish-checklist skill
+
+## Version
+
+roblox-opencode 1.0.0

package/dist/server.js

@@ -0,0 +1,167 @@
+// src/index.ts
+import { tool } from "@opencode-ai/plugin";
+import { fileURLToPath } from "node:url";
+var VERSION = "1.0.0";
+var MARKER_BEGIN = `<!-- roblox-opencode ${VERSION} BEGIN - managed block, edits inside will be overwritten -->`;
+var MARKER_END = "<!-- roblox-opencode END -->";
+var RobloxOpenCode = async () => {
+  try {
+    const { existsSync, mkdirSync, readdirSync, copyFileSync } = await import("fs");
+    const { join } = await import("path");
+    const os = await import("os");
+    const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
+    const srcDir = join(pkgDir, "commands");
+    const destDir = join(os.homedir(), ".config", "opencode", "commands");
+    if (existsSync(srcDir)) {
+      mkdirSync(destDir, { recursive: true });
+      const files = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
+      for (const file of files) {
+        copyFileSync(join(srcDir, file), join(destDir, file));
+      }
+    }
+  } catch {
+  }
+  return {
+    tool: {
+      roblox_setup: tool({
+        description: "One-time project setup for roblox-opencode. Copies 17 skills and vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to the project, writes luau-lsp config to opencode.json, and writes the core Roblox agent instructions to AGENTS.md. Run this when first opening a Roblox project.",
+        args: {},
+        async execute(_args, context) {
+          if (!context.directory) {
+            return [{ step: "pre-check", status: "error", error: "No project directory. Open a project folder first." }];
+          }
+          return await runSetup(context.directory);
+        }
+      })
+    }
+  };
+};
+async function runSetup(directory) {
+  const { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } = await import("fs");
+  const { join } = await import("path");
+  const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
+  const projectDir = directory;
+  const steps = [];
+  steps.push({
+    name: "Copy 17 skills to .opencode/skills/",
+    fn: () => {
+      const src = join(pkgDir, "skills");
+      const dest = join(projectDir, ".opencode", "skills");
+      if (!existsSync(src)) throw new Error(`skills/ not found in plugin at ${src}`);
+      mkdirSync(dest, { recursive: true });
+      cpSync(src, dest, { recursive: true, force: true });
+    }
+  });
+  steps.push({
+    name: "Copy vendor libraries to project",
+    fn: () => {
+      const src = join(pkgDir, "vendor");
+      const dest = join(projectDir, ".opencode", "vendor");
+      if (!existsSync(src)) throw new Error(`vendor/ not found in plugin at ${src}`);
+      mkdirSync(dest, { recursive: true });
+      cpSync(src, dest, { recursive: true, force: true });
+    }
+  });
+  steps.push({
+    name: "Write LSP config (luau-lsp)",
+    fn: () => {
+      const configPath = join(projectDir, "opencode.json");
+      let config = {};
+      if (existsSync(configPath)) {
+        try {
+          config = JSON.parse(readFileSync(configPath, "utf-8"));
+        } catch {
+        }
+      }
+      config.lsp = {
+        ...config.lsp || {},
+        luau: {
+          command: ["luau-lsp", "lsp"],
+          extensions: [".luau"]
+        }
+      };
+      writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    }
+  });
+  steps.push({
+    name: "Write .luaurc (vendor path aliases)",
+    fn: () => {
+      const luaurcPath = join(projectDir, ".luaurc");
+      let luaurc = {};
+      if (existsSync(luaurcPath)) {
+        try {
+          luaurc = JSON.parse(readFileSync(luaurcPath, "utf-8"));
+        } catch {
+        }
+      }
+      const aliases = luaurc.aliases || {};
+      aliases["Packages"] = ".opencode/vendor/rbxutil";
+      aliases["Fusion"] = ".opencode/vendor/fusion";
+      aliases["ProfileStore"] = ".opencode/vendor/profilestore";
+      aliases["Promise"] = ".opencode/vendor/promise";
+      aliases["TestEZ"] = ".opencode/vendor/testez";
+      aliases["t"] = ".opencode/vendor/t";
+      luaurc.aliases = aliases;
+      luaurc.languageMode = luaurc.languageMode || "nonstrict";
+      writeFileSync(luaurcPath, JSON.stringify(luaurc, null, 2) + "\n");
+    }
+  });
+  steps.push({
+    name: "Write core block to AGENTS.md",
+    fn: () => {
+      const agentsPath = join(projectDir, "AGENTS.md");
+      const corePath = join(pkgDir, "core", "roblox-core.md");
+      if (!existsSync(corePath)) throw new Error(`core/roblox-core.md not found in plugin at ${corePath}`);
+      const coreContent = readFileSync(corePath, "utf-8");
+      const block = `${MARKER_BEGIN}
+${coreContent}
+${MARKER_END}`;
+      let agentsContent = "";
+      if (existsSync(agentsPath)) {
+        agentsContent = readFileSync(agentsPath, "utf-8");
+      }
+      const beginPattern = /<!-- roblox-opencode[^>]*BEGIN[^>]*-->/;
+      const endPattern = /<!-- roblox-opencode END -->/;
+      const oldBeginPattern = /<!-- roblox-pi[^>]*BEGIN[^>]*-->/;
+      const oldEndPattern = /<!-- roblox-pi END -->/;
+      let newContent;
+      if (beginPattern.test(agentsContent) && endPattern.test(agentsContent)) {
+        newContent = agentsContent.replace(
+          new RegExp(`${beginPattern.source}[\\s\\S]*?${endPattern.source}`),
+          block
+        );
+      } else if (oldBeginPattern.test(agentsContent) && oldEndPattern.test(agentsContent)) {
+        newContent = agentsContent.replace(
+          new RegExp(`${oldBeginPattern.source}[\\s\\S]*?${oldEndPattern.source}`),
+          block
+        );
+      } else {
+        newContent = agentsContent ? agentsContent.trimEnd() + "\n\n" + block + "\n" : block + "\n";
+      }
+      writeFileSync(agentsPath, newContent);
+    }
+  });
+  const results = [];
+  for (const step of steps) {
+    try {
+      step.fn();
+      results.push({ step: step.name, status: "ok" });
+    } catch (err) {
+      results.push({
+        step: step.name,
+        status: "error",
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return results;
+}
+var index_default = {
+  id: "roblox-opencode",
+  server: RobloxOpenCode
+};
+export {
+  RobloxOpenCode,
+  index_default as default,
+  runSetup
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "roblox-opencode",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for Roblox/Luau development: skills, commands, module libs, and config",
+  "keywords": [
+    "opencode-plugin",
+    "roblox",
+    "luau",
+    "game-development"
+  ],
+  "license": "MIT",
+  "author": "TabooHarmony",
+  "type": "module",
+  "main": "./dist/server.js",
+  "exports": {
+    "./server": {
+      "import": "./dist/server.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TabooHarmony/roblox-opencode"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/server.js --target=esnext --format=esm --platform=node --external:@opencode-ai/plugin",
+    "prepare": "node -e \"\""
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "commands/",
+    "vendor/",
+    "core/"
+  ]
+}