opencode-herdr-orchestration 0.1.2 → 0.1.4

package/README.md

@@ -4,10 +4,45 @@ Capability-separated OpenCode agents for planning, implementation, independent r
 
 This package registers the agents, provides complete structured worker-response retrieval, injects session-specific orchestration mode into shell environments, and ships a reproducible Git `pre-push` policy for new and existing repositories.
 
-Requires Node.js 22.22.2 or newer when running the package CLI or tests.
+Requires Node.js 20 or newer when running the package CLI or tests.
 
 ## Installation
 
+Install or update the plugin with the cross-platform npm CLI:
+
+```bash
+npx -y opencode-herdr-orchestration@latest install
+npx -y opencode-herdr-orchestration@latest update
+```
+
+The installer:
+
+- locates the global OpenCode config directory;
+- installs an exact package version there;
+- preserves existing JSONC comments, trailing commas, plugins, and tuple options;
+- adds the stable file URL required by current OpenCode npm plugin loading;
+- creates timestamped backups of changed config and npm manifest files;
+- validates `shepherd-build` through a short-lived OpenCode debug process;
+- never restarts or signals a running OpenCode process.
+
+The shared Git push policy remains opt-in:
+
+```bash
+npx -y opencode-herdr-orchestration@latest install --with-hooks
+```
+
+Inspect or remove the installation:
+
+```bash
+npx -y opencode-herdr-orchestration@latest status
+npx -y opencode-herdr-orchestration@latest uninstall
+npx -y opencode-herdr-orchestration@latest uninstall --with-hooks
+```
+
+After installation or update, quit and restart OpenCode intentionally when ready. Existing processes keep their already-loaded configuration.
+
+## Manual Installation
+
 Add the published package to the global OpenCode configuration at `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`:
 
 ```jsonc
@@ -19,6 +54,23 @@ Add the published package to the global OpenCode configuration at `~/.config/ope
 
 If `plugin` already contains entries, append `"opencode-herdr-orchestration"` instead of replacing them. OpenCode installs npm plugins automatically when it starts.
 
+Install the package into that config directory so the stable file URL can resolve it:
+
+```bash
+cd ~/.config/opencode
+npm install --save-exact opencode-herdr-orchestration@latest
+```
+
+Current OpenCode releases may record but not execute npm plugins referenced only by package name. If that occurs, use the installed entry path in the plugin tuple instead:
+
+```jsonc
+{
+  "plugin": [
+    "file:///ABSOLUTE/PATH/TO/.config/opencode/node_modules/opencode-herdr-orchestration/src/plugin.js"
+  ]
+}
+```
+
 Optionally install the shared Git push policy for all current and future repositories:
 
 ```bash

package/bin/orchestration.js

@@ -5,6 +5,18 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
+import {
+  configDirectory,
+  installPackage,
+  latestVersion,
+  PACKAGE_NAME,
+  packageVersion,
+  restoreBackup,
+  status as installationStatus,
+  uninstallPackage,
+  validateOpenCode,
+  writePluginConfig,
+} from "../src/installer.js";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const hooksPath = join(homedir(), ".config", "opencode-herdr-orchestration", "hooks");
@@ -24,7 +36,7 @@ function currentHooksPath() {
   }
 }
 
-function install() {
+function installHooks() {
   const existing = currentHooksPath();
   const force = flags.includes("--force");
   if (existing && existing !== hooksPath && !force) {
@@ -37,7 +49,7 @@ function install() {
   process.stdout.write(`Installed pre-push hook and set global core.hooksPath=${hooksPath}\n`);
 }
 
-function uninstall() {
+function uninstallHooks() {
   if (currentHooksPath() === hooksPath) {
     git(["config", "--global", "--unset", "core.hooksPath"]);
     rmSync(hooksPath, { recursive: true, force: true });
@@ -47,21 +59,57 @@ function uninstall() {
   }
 }
 
-function status() {
-  process.stdout.write(`${JSON.stringify({
+function installOrUpdate(useLatest) {
+  const configDir = configDirectory();
+  const version = useLatest ? latestVersion() : packageVersion(packageRoot);
+  const packageBackups = installPackage(configDir, version);
+  const result = writePluginConfig(configDir);
+  try {
+    validateOpenCode(configDir);
+  } catch (error) {
+    restoreBackup(result.file, result.backup, result.existed);
+    throw new Error(`OpenCode validation failed; restored the previous config. ${error.message}`);
+  }
+  if (flags.includes("--with-hooks")) installHooks();
+  process.stdout.write(`Configured ${PACKAGE_NAME}@${version} in ${result.file}\n`);
+  if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
+  process.stdout.write("Restart OpenCode intentionally to load the new configuration.\n");
+}
+
+function uninstallOrchestration() {
+  const configDir = configDirectory();
+  const result = writePluginConfig(configDir, true);
+  const packageBackups = uninstallPackage(configDir);
+  if (flags.includes("--with-hooks")) uninstallHooks();
+  process.stdout.write(`Removed orchestration plugin configuration from ${result.file}\n`);
+  if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
+}
+
+function fullStatus() {
+  const result = { ...installationStatus(configDirectory(), packageRoot), hooks: JSON.parse(captureHookStatus()) };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+function captureHookStatus() {
+  return JSON.stringify({
     configuredHooksPath: currentHooksPath() || null,
     expectedHooksPath: hooksPath,
     hookInstalled: existsSync(installedHook),
     active: currentHooksPath() === hooksPath && existsSync(installedHook),
-  }, null, 2)}\n`);
+  });
 }
 
 try {
-  if (command === "install-hooks") install();
-  else if (command === "uninstall-hooks") uninstall();
-  else if (command === "status") status();
+  if (command === "install") installOrUpdate(false);
+  else if (command === "update") installOrUpdate(true);
+  else if (command === "uninstall") uninstallOrchestration();
+  else if (command === "install-hooks") installHooks();
+  else if (command === "uninstall-hooks") uninstallHooks();
+  else if (command === "status") fullStatus();
   else {
-    process.stderr.write("Usage: opencode-herdr-orchestration <install-hooks [--force]|uninstall-hooks|status>\n");
+    process.stderr.write("Usage: opencode-herdr-orchestration <install|update|status|uninstall|install-hooks|uninstall-hooks> [--with-hooks] [--force]\n");
     process.exitCode = 2;
   }
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-herdr-orchestration",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Capability-separated Herdr orchestration agents for OpenCode",
   "author": "CodingJinxx",
   "repository": {
@@ -31,13 +31,7 @@
     "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check bin/orchestration.js"
   },
   "engines": {
-    "node": ">=22.22.2"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.3.0 <2"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "1.3.14"
+    "node": ">=20"
   },
   "keywords": [
     "opencode",
@@ -45,5 +39,10 @@
     "orchestration",
     "agents"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "1.3.14",
+    "cross-spawn": "7.0.6",
+    "jsonc-parser": "3.3.1"
+  }
 }

package/src/installer.js

@@ -0,0 +1,199 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import spawn from "cross-spawn";
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+
+export const PACKAGE_NAME = "opencode-herdr-orchestration";
+const NPM_COMMAND = "npm";
+const OPENCODE_COMMAND = "opencode";
+export const AGENT_NAMES = [
+  "shepherd-plan",
+  "shepherd-build",
+  "sheep-plan",
+  "sheep-build",
+  "shearer-review-low",
+  "shearer-review-medium",
+];
+
+export function configDirectory(env = process.env) {
+  if (env.OPENCODE_CONFIG_DIR) return resolve(env.OPENCODE_CONFIG_DIR);
+  const home = env.HOME || env.USERPROFILE || homedir();
+  return join(home, ".config", "opencode");
+}
+
+export function packageEntry(configDir) {
+  return pathToFileURL(join(configDir, "node_modules", PACKAGE_NAME, "src", "plugin.js")).href;
+}
+
+export function isOrchestrationPlugin(entry) {
+  const spec = Array.isArray(entry) ? entry[0] : entry;
+  return (
+    typeof spec === "string" &&
+    (spec === PACKAGE_NAME || spec.startsWith(`${PACKAGE_NAME}@`) || spec.includes(`/node_modules/${PACKAGE_NAME}/`))
+  );
+}
+
+export function updatePluginConfig(text, entry, remove = false) {
+  const errors = [];
+  const config = parse(text || "{}", errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length) {
+    const first = errors[0];
+    throw new Error(`Invalid OpenCode JSONC at offset ${first.offset}: ${printParseErrorCode(first.error)}.`);
+  }
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+  const plugins = Array.isArray(config?.plugin) ? config.plugin : [];
+  const matches = plugins.map((candidate, index) => isOrchestrationPlugin(candidate) ? index : -1).filter((index) => index >= 0);
+  const existing = matches.length ? plugins[matches[0]] : undefined;
+  const source = text || "{}";
+
+  if (matches.length === 1 && !remove) {
+    const replacement = Array.isArray(existing) ? [entry, existing[1] ?? {}] : entry;
+    return applyEdits(source, modify(source, ["plugin", matches[0]], replacement, { formattingOptions }));
+  }
+  if (matches.length && (remove || matches.length > 1)) {
+    const remaining = plugins.filter((candidate) => !isOrchestrationPlugin(candidate));
+    if (!remove) remaining.push(Array.isArray(existing) ? [entry, existing[1] ?? {}] : entry);
+    return applyEdits(source, modify(source, ["plugin"], remaining, { formattingOptions }));
+  }
+  if (!remove) {
+    const path = Array.isArray(config?.plugin) ? ["plugin", -1] : ["plugin"];
+    const value = Array.isArray(config?.plugin) ? entry : [entry];
+    return applyEdits(source, modify(source, path, value, { formattingOptions }));
+  }
+  return source;
+}
+
+export function findConfigFile(configDir) {
+  for (const name of ["opencode.jsonc", "opencode.json"]) {
+    const candidate = join(configDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return join(configDir, "opencode.jsonc");
+}
+
+export function backupFile(file, now = new Date()) {
+  if (!existsSync(file)) return null;
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const backup = `${file}.backup-${stamp}`;
+  copyFileSync(file, backup);
+  return backup;
+}
+
+function run(command, args, options = {}) {
+  const result = spawn.sync(command, args, {
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const error = new Error(`${command} exited with status ${result.status}.`);
+    error.status = result.status;
+    error.stdout = result.stdout;
+    error.stderr = result.stderr;
+    throw error;
+  }
+  return result.stdout.trim();
+}
+
+export function installedVersion(configDir) {
+  const manifest = join(configDir, "node_modules", PACKAGE_NAME, "package.json");
+  if (!existsSync(manifest)) return null;
+  return JSON.parse(readFileSync(manifest, "utf8")).version;
+}
+
+export function packageVersion(packageRoot) {
+  return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
+}
+
+export function latestVersion() {
+  return JSON.parse(run(NPM_COMMAND, ["view", PACKAGE_NAME, "version", "--json", "--prefer-online"]));
+}
+
+export function installPackage(configDir, version) {
+  mkdirSync(configDir, { recursive: true });
+  const backups = ["package.json", "package-lock.json"]
+    .map((name) => backupFile(join(configDir, name)))
+    .filter(Boolean);
+  run(NPM_COMMAND, ["install", "--save-exact", `${PACKAGE_NAME}@${version}`], { cwd: configDir });
+  return backups;
+}
+
+export function uninstallPackage(configDir) {
+  const backups = ["package.json", "package-lock.json"]
+    .map((name) => backupFile(join(configDir, name)))
+    .filter(Boolean);
+  try {
+    run(NPM_COMMAND, ["uninstall", PACKAGE_NAME], { cwd: configDir });
+  } catch {}
+  return backups;
+}
+
+export function writePluginConfig(configDir, remove = false) {
+  mkdirSync(configDir, { recursive: true });
+  const file = findConfigFile(configDir);
+  const existed = existsSync(file);
+  const previous = existed ? readFileSync(file, "utf8") : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  const next = updatePluginConfig(previous, packageEntry(configDir), remove);
+  if (next === previous) return { file, backup: null, changed: false, existed };
+  const backup = backupFile(file);
+  writeFileSync(file, next, "utf8");
+  return { file, backup, changed: true, existed };
+}
+
+export function restoreBackup(file, backup, existed = true) {
+  if (backup && existsSync(backup)) copyFileSync(backup, file);
+  else if (!existed) rmSync(file, { force: true });
+}
+
+export function validateOpenCode(configDir) {
+  const output = run(OPENCODE_COMMAND, ["debug", "agent", "shepherd-build"], {
+    cwd: configDir,
+    env: { ...process.env, OPENCODE_DISABLE_PROJECT_CONFIG: "1" },
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const parsed = JSON.parse(output);
+  if (parsed.name !== "shepherd-build") throw new Error("OpenCode did not resolve shepherd-build after installation.");
+  return true;
+}
+
+export function status(configDir, packageRoot) {
+  const file = findConfigFile(configDir);
+  let configured = false;
+  if (existsSync(file)) {
+    const config = parse(readFileSync(file, "utf8"), [], { allowTrailingComma: true, disallowComments: false });
+    configured = Array.isArray(config?.plugin) && config.plugin.some(isOrchestrationPlugin);
+  }
+  const installed = installedVersion(configDir);
+  let detectedAgents = [];
+  try {
+    const output = run(OPENCODE_COMMAND, ["agent", "list"], {
+      cwd: configDir,
+      env: { ...process.env, OPENCODE_DISABLE_PROJECT_CONFIG: "1" },
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    detectedAgents = AGENT_NAMES.filter((name) => output.includes(`${name} (primary)`));
+  } catch {}
+  let latest = null;
+  let latestVersionError = null;
+  try {
+    latest = latestVersion();
+  } catch (error) {
+    latestVersionError = String(error?.stderr ?? error?.message ?? error).replace(/\s+/g, " ").trim().slice(0, 500);
+  }
+  return {
+    package: PACKAGE_NAME,
+    cliVersion: packageVersion(packageRoot),
+    installedVersion: installed,
+    latestVersion: latest,
+    latestVersionError,
+    updateAvailable: Boolean(installed && latest && installed !== latest),
+    configFile: file,
+    pluginConfigured: configured,
+    detectedAgents,
+    agentsReady: detectedAgents.length === AGENT_NAMES.length,
+  };
+}