regent-code 3.0.0 → 3.0.1

package/.opencode/INSTALL.md

@@ -1,11 +1,25 @@
 # Installation
 
+## One-command install
+
+If the package is published to npm, both the plugin and the MCP server install
+with a single command against any existing `opencode.json` / `opencode.jsonc`:
+
+```bash
+npx -y regent-code@3.0.1 install
+```
+
+Patches the project config (or the global `~/.config/opencode/` config) to add
+`mcp.servers.regent` and the `plugins` entry. Idempotent and non-destructive;
+`--global` forces the user config, `--file <path>` targets an exact file,
+`--help` for options. Restart the OpenCode session afterwards.
+
 ## Add to opencode.jsonc
 
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v2.7.1"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.1"],
 }
 ```
 
@@ -18,7 +32,7 @@
 }
 ```
 
-The pinned version is recommended. Use the unpinned branch only when you intentionally want the latest changes. The `v2.7.1` git tag must be pushed to GitHub before the pinned spec resolves.
+The pinned version is recommended. Use the unpinned branch only when you intentionally want the latest changes. The `v3.0.1` git tag must be pushed to GitHub before the pinned spec resolves.
 
 ## Single-source rule (duplicate plugin ID)
 

package/README.md

@@ -51,14 +51,31 @@ Add Regent to your OpenCode configuration:
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v2.7.1"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.1"],
 }
 ```
 
-This release targets the OpenCode v2 beta plugin API (`@opencode-ai/plugin@0.0.0-beta-18155`); the beta API may change. The `v2.7.1` git tag must be pushed to GitHub before this pinned spec resolves.
+This release targets the OpenCode v2 beta plugin API (`@opencode-ai/plugin@0.0.0-beta-18314`); the beta API may change. The `v3.0.1` git tag must be pushed to GitHub before this pinned spec resolves.
 
 > **Windows dev-machine warning (single-source rule):** when this repository is open as an OpenCode project, its own `.opencode/plugins/regent.js` is auto-loaded as a project plugin. Do NOT also pin regent in `opencode.jsonc` on the same machine — two active sources make host plugin reloads fail with `Duplicate plugin ID: regent`, leaving sessions with a torn tool surface and blocking live skill/plugin edits. Either develop unpinned (project plugin only) or pin the repo file directly: `"plugins": ["file:///Q:/PROJECTS/PERSONAL/regent-code/.opencode/plugins/regent.js"]`. One source of truth, always.
 
+## One-command install
+
+The fastest way to get **both** the plugin and the MCP server on any machine — no cloning, no manual config edits, no local files:
+
+```bash
+npx -y regent-code@3.0.1 install
+```
+
+The installer finds an existing `opencode.json` / `opencode.jsonc` (project config in the current directory first, then the global `~/.config/opencode/` config) and adds both entries:
+
+- **MCP server**: `mcp.servers.regent` → runs `["npx", "-y", "regent-code@3.0.1"]`
+- **Plugin**: `plugins` → `regent-code@3.0.1`
+
+It is **idempotent and non-destructive** — it only adds or updates regent entries, preserving comments, trailing commas, and every unrelated setting in the file. Re-run it to upgrade the pinned version. Flags: `--global` forces the user config, `--file <path>` targets an exact file, `--help` explains all options. Restart the OpenCode session afterwards — plugin load and MCP connection happen on config load.
+
+> On the machine that develops regent-code itself, respect the single-source rule above: do not add a second pin when the repo is open as a project.
+
 ## MCP Server
 
 Since v3.0.0, regent-code ships a second distribution alongside the plugin: a Model Context Protocol (MCP) server that exposes the same six tools (`delegate`, `delegate_many`, `research`, `explore`, `changed-files`, `verify`) plus the Regent command and skill corpus as MCP prompts. It is out-of-process and works from any MCP client (Claude Desktop, Cursor, or OpenCode).
@@ -91,7 +108,7 @@ Configure it in OpenCode by adding a local MCP server:
     "servers": {
       "regent": {
         "type": "local",
-        "command": ["npx", "-y", "regent-code@3.0.0"]
+        "command": ["npx", "-y", "regent-code@3.0.1"]
       }
     }
   }

package/mcp/cli.js

@@ -1,9 +1,83 @@
-// Launch the Regent MCP server. Used as the package `bin` entry so that
-// `npx -y regent-code` starts the server over stdio without needing a local
-// clone. Keep this file dependency-free and side-effect-only by design.
+// Regent CLI entry (package `bin`).
+//   no arguments  -> run the MCP server over stdio (that is what a local
+//                    `mcp.servers` entry in OpenCode invokes)
+//   install       -> patch an existing opencode.json / opencode.jsonc to
+//                    register the Regent MCP server AND plugin; idempotent and
+//                    non-destructive, can create the config when missing
+//   anything else -> usage error
 import { main } from './index.js';
+import { install, InstallError, PLUGIN_SPEC, SERVER_NAME } from './install.js';
 
-main().catch((err) => {
-  console.error(err);
+const USAGE = `Usage: npx -y ${PLUGIN_SPEC} install [--global] [--file <path>] [--help]
+
+Patches an existing opencode.json / opencode.jsonc (V2 OpenCode config) to
+register:
+  - MCP server "${SERVER_NAME}" running ${PLUGIN_SPEC}
+  - plugin ${PLUGIN_SPEC}
+
+Without flags: patches ./opencode.json(c) or ./.opencode/opencode.json(c) when
+present, otherwise the global ~/.config/opencode config, creating it if needed.
+
+  --global  patch (or create) the user-global config instead
+  --file P  patch the exact file path (wins over --global)
+  --help    show this help
+
+Non-destructive and idempotent: only adds or updates regent entries, leaving
+comments, formatting, and unrelated settings untouched. Restart the OpenCode
+session afterwards — plugin load and MCP connection happen on config load.`;
+
+function runInstaller(args) {
+  const options = { cwd: process.cwd() };
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--global':
+        options.global = true;
+        break;
+      case '--file':
+        if (!args[i + 1]) throw new InstallError('--file requires a path argument');
+        options.file = args[++i];
+        break;
+      case '--help':
+        console.log(USAGE);
+        process.exit(0);
+        break;
+      default:
+        throw new InstallError(`unknown argument: ${args[i]}\n\n${USAGE}`);
+    }
+  }
+
+  const report = install(options);
+  const lines = [
+    `Installed into: ${report.path} (${report.scope}${report.created ? ', created' : ''})`,
+    `  MCP server "${SERVER_NAME}": ${report.mcp}`,
+    `  Plugin ${PLUGIN_SPEC}:        ${report.plugin}`,
+    '',
+    ...report.warnings.map((warning) => `  warning: ${warning}`),
+    '',
+    'Restart your OpenCode session — the plugin registers on load and the',
+    'MCP server connects on the next config load.',
+  ];
+  console.log(lines.join('\n'));
+}
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'install') {
+  try {
+    runInstaller(args.slice(1));
+  } catch (err) {
+    if (err instanceof InstallError) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+} else if (args.length === 0) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+} else {
+  console.error(`Unknown arguments: ${args.join(' ')}\n\n${USAGE}`);
   process.exit(1);
-});
+}

package/mcp/index.js

@@ -41,7 +41,7 @@ import {
 
 import { readPackagePrompts, renderPrompt } from './prompts.js';
 
-const version = '3.0.0';
+const version = '3.0.1';
 
 // ── OpenCode client (lazy singleton) ─────────────────────────
 let clientPromise = null;

package/mcp/install.js

@@ -9,13 +9,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import {
-  parseTree,
-  findNodeAtLocation,
-  getNodeValue,
-  modify,
-  applyEdits,
-} from 'jsonc-parser';
+import { parseTree, findNodeAtLocation, getNodeValue, modify, applyEdits } from 'jsonc-parser';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -58,10 +52,20 @@ function findExisting(candidates) {
   return null;
 }
 
+/**
+ * @typedef {Object} InstallOptions
+ * @property {string} [cwd] Working directory for resolving relative paths and project configs.
+ * @property {string} [file] Explicit config path (wins over every other mode).
+ * @property {boolean} [global] Force the user-global config.
+ */
+
 // Decide which file to patch. Never writes; the installer writes after
 // resolving. Explicit --file wins, then forced global, then: an existing
 // project config in cwd, else an existing global config, else the global
 // location (created on demand).
+/**
+ * @param {InstallOptions} [options]
+ */
 export function resolveTarget({ cwd = process.cwd(), file, global = false } = {}) {
   if (file) return { path: resolve(cwd, file), scope: 'explicit' };
   if (global) {
@@ -91,7 +95,9 @@ export function patchText(
   { pluginSpec = PLUGIN_SPEC, serverName = SERVER_NAME, serverConfig = SERVER_CONFIG } = {},
 ) {
   const errors = [];
-  const root = parseTree(text, errors);
+  // JSONC by contract: comments are allowed by default, trailing commas must
+  // be opted into — both are common in real opencode.json(c) files.
+  const root = parseTree(text, errors, { allowTrailingComma: true });
   if (!root || errors.length) {
     throw new InstallError(`invalid JSONC: ${errors[0]?.error ?? 'could not parse'}`);
   }
@@ -101,8 +107,17 @@ export function patchText(
 
   const eol = detectEol(text);
   const formattingOptions = { insertSpaces: true, tabSize: 2, eol };
+  /** @type {{ mcp: string, plugin: string, warnings: string[] }} */
   const report = { mcp: 'unchanged', plugin: 'unchanged', warnings: [] };
-  let edits = [];
+
+  // Apply each edit batch against the CURRENT text, never the original:
+  // two insertions at the same location (e.g. missing mcp + missing plugins,
+  // both inserted before the closing brace) overlap when computed against one
+  // shared base text and make jsonc-parser throw "Overlapping edit".
+  let current = text;
+  const apply = (edits) => {
+    if (edits.length) current = applyEdits(current, edits);
+  };
 
   // ---- MCP server entry ----
   const mcpNode = findNodeAtLocation(root, ['mcp']);
@@ -115,24 +130,18 @@ export function patchText(
       if (deepEqual(existing, serverConfig)) {
         report.mcp = 'unchanged';
       } else {
-        edits = edits.concat(
-          modify(text, ['mcp', 'servers', serverName], serverConfig, { formattingOptions }),
-        );
+        apply(modify(current, ['mcp', 'servers', serverName], serverConfig, { formattingOptions }));
         report.mcp = 'updated';
       }
     } else {
-      report.warnings.push(
-        `mcp.servers.${serverName} exists but is not an object; left untouched`,
-      );
+      report.warnings.push(`mcp.servers.${serverName} exists but is not an object; left untouched`);
     }
   } else if (mcpNode && mcpNode.type !== 'object') {
     report.warnings.push('existing "mcp" key is not an object; left untouched');
   } else if (serversNode && serversNode.type !== 'object') {
     report.warnings.push('existing "mcp.servers" is not an object; left untouched');
   } else {
-    edits = edits.concat(
-      modify(text, ['mcp', 'servers', serverName], serverConfig, { formattingOptions }),
-    );
+    apply(modify(current, ['mcp', 'servers', serverName], serverConfig, { formattingOptions }));
     report.mcp = 'added';
   }
 
@@ -150,12 +159,11 @@ export function patchText(
         (entry) => /^file:/.test(entry) && entry.toLowerCase().includes('regent'),
       );
       const hasNpmPin =
-        entries.some((entry) => entry.startsWith('regent-code@') && !/^regent-code@git/.test(entry)) ||
-        entries.includes('regent-code');
+        entries.some(
+          (entry) => entry.startsWith('regent-code@') && !/^regent-code@git/.test(entry),
+        ) || entries.includes('regent-code');
 
-      const next = entries
-        .filter((entry) => !gitEntries.includes(entry))
-        .concat(nonString);
+      const next = entries.filter((entry) => !gitEntries.includes(entry)).concat(nonString);
       let reportPlugin;
       if (hasNpmPin && gitEntries.length === 0) {
         reportPlugin = 'unchanged';
@@ -164,31 +172,32 @@ export function patchText(
       }
       if (!hasNpmPin) next.push(pluginSpec);
       if (filePin) {
-        report.warnings.push(
-          'regent plugin pinned via file:// (dev loop); entry left untouched',
-        );
+        report.warnings.push('regent plugin pinned via file:// (dev loop); entry left untouched');
       }
       if (!deepEqual(next, existing)) {
-        edits = edits.concat(modify(text, ['plugins'], next, { formattingOptions }));
+        apply(modify(current, ['plugins'], next, { formattingOptions }));
         report.plugin = reportPlugin;
       }
     }
   } else {
-    edits = edits.concat(modify(text, ['plugins'], [pluginSpec], { formattingOptions }));
+    apply(modify(current, ['plugins'], [pluginSpec], { formattingOptions }));
     report.plugin = 'added';
   }
 
-  return { text: applyEdits(text, edits), report };
+  return { text: current, report };
 }
 
 // Full install against the filesystem: resolves the target config, patches it
 // (creating the file with only the regent entries when none exists), and
 // returns the report plus target info.
+/**
+ * @param {InstallOptions} [options]
+ */
 export function install(options = {}) {
   const target = resolveTarget(options);
   const existingText = existsSync(target.path) ? readFileSync(target.path, 'utf8') : null;
   const base = existingText ?? `{\n}\n`;
-  const { text, report } = patchText(base, options);
+  const { text, report } = patchText(base);
 
   if (text !== existingText) {
     mkdirSync(dirname(target.path), { recursive: true });
@@ -201,4 +210,4 @@ export function install(options = {}) {
     scope: target.scope,
     created: existingText === null,
   };
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regent-code",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Agent orchestration for OpenCode. From idea to shipped — zero ceremony. Plugin + MCP server.",
   "type": "module",
   "main": ".opencode/plugins/regent.js",
@@ -30,7 +30,7 @@
     "format": "prettier --write .opencode/plugins/ skills/ mcp/ --no-error-on-unmatched-pattern",
     "format:check": "prettier --check .opencode/plugins/ skills/ mcp/ --no-error-on-unmatched-pattern",
     "typecheck": "tsc --noEmit",
-    "test": "node --test .opencode/tests/regent.test.js .opencode/tests/regent.live-test.js .opencode/tests/regent.v2.test.js .opencode/tests/regent.hybrid.v2.6.1.test.js .opencode/tests/regent.runtime.v2.6.1.test.js mcp/tests/mcp.test.js",
+    "test": "node --test .opencode/tests/regent.test.js .opencode/tests/regent.live-test.js .opencode/tests/regent.v2.test.js .opencode/tests/regent.hybrid.v2.6.1.test.js .opencode/tests/regent.runtime.v2.6.1.test.js mcp/tests/mcp.test.js mcp/tests/install.test.js",
     "verify": "npm run format:check && npm run lint && npm run typecheck && npm test"
   },
   "devDependencies": {