opencode-herdr-orchestration 0.1.1 → 0.1.3

package/README.md

@@ -8,6 +8,41 @@ Requires Node.js 22.22.2 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.1",
+  "version": "0.1.3",
   "description": "Capability-separated Herdr orchestration agents for OpenCode",
   "author": "CodingJinxx",
   "repository": {
@@ -45,5 +45,8 @@
     "orchestration",
     "agents"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "jsonc-parser": "3.3.1"
+  }
 }

package/src/agents.js

@@ -52,6 +52,12 @@ const herdrInspection = {
   "herdr pane layout*": "allow",
   "herdr pane split*": "allow",
   "herdr pane read*": "allow",
+  "herdr worktree": "allow",
+  "herdr worktree list*": "allow",
+  "herdr worktree create *": "allow",
+  "herdr worktree open *": "allow",
+  "herdr worktree remove --workspace *": "allow",
+  "herdr worktree remove * --force*": "deny",
 };
 
 const markdownOnly = {

package/src/installer.js

@@ -0,0 +1,207 @@
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+
+export const PACKAGE_NAME = "opencode-herdr-orchestration";
+const NPM_COMMAND = process.platform === "win32" ? process.execPath : "npm";
+const NPM_PREFIX = process.platform === "win32" ? [resolveNpmCli()] : [];
+const OPENCODE_COMMAND = process.platform === "win32" ? "opencode.exe" : "opencode";
+export const AGENT_NAMES = [
+  "shepherd-plan",
+  "shepherd-build",
+  "sheep-plan",
+  "sheep-build",
+  "shearer-review-low",
+  "shearer-review-medium",
+];
+
+function resolveWindowsCommand(name) {
+  try {
+    return execFileSync("where.exe", [name], { encoding: "utf8", windowsHide: true })
+      .split(/\r?\n/)
+      .find(Boolean)
+      .trim();
+  } catch {
+    return name;
+  }
+}
+
+function resolveNpmCli() {
+  const npmShim = resolveWindowsCommand("npm.cmd");
+  return join(dirname(npmShim), "node_modules", "npm", "bin", "npm-cli.js");
+}
+
+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 = {}) {
+  return execFileSync(command, args, {
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  }).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, [...NPM_PREFIX, "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, [...NPM_PREFIX, "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, [...NPM_PREFIX, "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,
+  };
+}

package/src/prompts.js

@@ -13,6 +13,8 @@ Never pass another agent, model, --auto, or extra OpenCode argument. Use send-ke
 
 Worker names must be unique and satisfy Herdr's naming rules. Assign bounded work with herdr agent prompt <name> "..." --wait --timeout <milliseconds>. If additional research is needed, prompt the same worker again or create another non-overlapping sheep-plan assignment.
 
+When isolated planning needs a worktree, use Herdr's installed worktree commands. A worktree created from another worktree is a peer that shares the same Git common repository, not its child. Inspect existing worktrees first, use an explicit non-protected branch and base commit, and place the checkout outside the current worktree rather than nesting it. Record the worker, branch, path, and base commit. Remove only worktrees you created, only after their planning artifacts are preserved and the worktree is clean; never force removal.
+
 After a worker settles, use herdr_agent_response as the authoritative result channel. Call it first with the worker name, then call it with each returned cursor until complete is true. Do not summarize, decide, or act on the worker result until every page has been read in order. Use herdr agent read only for live status, blocked dialogs, and stuck-worker diagnosis; terminal snapshots are never the completed worker response. If retrieval says the worker is not settled, wait and retry. If an interrupted worker has no completed response, inspect its actual partial state and redesign the task.
 
 If a worker is blocked, inspect it with herdr agent get and herdr agent read; do not answer approvals or questions without applying the user's safety constraints. Treat unknown as inconclusive, not complete. Synthesize worker findings instead of forwarding raw reports. Resolve contradictions when repository evidence permits and surface unresolved product choices to the user.
@@ -45,6 +47,8 @@ Delegate using structured contracts containing, where relevant: task_id, plan_id
 
 Parallelize only tasks that will not conflict. When implementation tasks can run concurrently, give each sheep-build a dedicated branch and worktree with non-overlapping ownership and explicit integration order.
 
+Use Herdr's installed worktree commands for worker isolation. Worktrees created while you are already in a worktree are peers sharing the same Git common repository. Inspect the existing worktree list before creation, create each worker branch from the approved base commit, and never nest a worker checkout inside the current worktree. Record worker name, branch, path, base commit, and owned scope before delegation. Never reuse a branch checked out elsewhere. Remove only worktrees you created, only after their commits are integrated or otherwise preserved and the worktree is clean; never force removal.
+
 Spawn only these configured workers with no extra OpenCode arguments:
 
 herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-plan