opencode-herdr-orchestration 0.2.1 → 0.3.1

package/src/installer.js

@@ -5,6 +5,13 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import spawn from "cross-spawn";
 import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+import {
+  STEER_COMMAND_AGENT as STEER_AGENT,
+  STEER_COMMAND_DESCRIPTION as STEER_DESCRIPTION,
+  STEER_COMMAND_NAME as STEER_NAME,
+  STEER_COMMAND_TEMPLATE as STEER_TEMPLATE,
+  steerCommandEntry as steerEntry,
+} from "./steer.js";
 
 export const PACKAGE_NAME = "opencode-herdr-orchestration";
 const NPM_COMMAND = "npm";
@@ -17,6 +24,7 @@ export const AGENT_NAMES = [
   "sheep",
   "shearer-low",
   "shearer-medium",
+  "developer",
 ];
 
 // Agents register dynamically through the plugin, so the package owns no agent
@@ -125,6 +133,199 @@ export function findConfigFile(configDir) {
   return join(configDir, "opencode.jsonc");
 }
 
+// 15-M1 project config semantics (live-evidenced on opencode 1.18.29 via
+// `opencode debug config` plus `opencode debug skill` in OS temp probes).
+// Project filename: `opencode.json` in the project root per docs Per project
+// ("Add `opencode.json` in your project root ... traverses up to the nearest
+// Git directory"); live probes show both `opencode.json` and `opencode.jsonc`
+// in cwd load as scope "local" (plugin_origins source project file, scope
+// local) while empty cwd shows global-only (2 globals); when both exist both
+// load as separate local layers, so helpers edit only the found file and
+// preserve the other. Default for a new project file is `opencode.json` per
+// docs; an existing `opencode.jsonc` is preferred when present for JSONC
+// comment coherence with the global helper.
+// Per-key merge: docs Locations ("merged together, not replaced ... later
+// overrides earlier only for conflicting keys") plus Permissions Agents
+// ("merged with the global config, and agent rules take precedence"); live
+// per-key probe shows project `agent.shepherd.permission.bash` probe key
+// merges with plugin keys (`herdr --help` preserved, `*` deny preserved) and
+// a conflicting project `deny` overrides a plugin `allow`; a project custom
+// agent preserves plugin agents (shepherd plus governor plus sheepdog plus
+// grazer plus sheep plus shearers); top-level `permission` does not leak into
+// agent blocks, so helpers target `["agent", name, "permission", ...]` only.
+// Reload: config loads at startup; existing processes keep old config, so quit
+// and restart intentionally, then verify the merged view with
+// `opencode debug config` in the project; invalid project JSON fails that
+// command with "not valid JSON(C)" and no automatic fallback, while
+// `OPENCODE_DISABLE_PROJECT_CONFIG=1 opencode debug config` shows the
+// global-only fallback (live-evidenced OK pluginLen 2 vs FAIL). Helpers below
+// reuse parse plus modify plus applyEdits and backup discipline, stay fail
+// closed inside the project root, and never touch global config.
+// Skill decision: `opencode debug skill` shows 4 skills with 3 file-based
+// globals (`graphify` in ~/.claude/skills plus `herdr` plus `find-skills` in
+// ~/.agents/skills) and zero project `.opencode/skills` files, so M1 stays
+// prompt-embedded with no native SKILL.md; see src/prompts.js plus README.
+export const PROJECT_CONFIG_FILE = "opencode.json";
+export const PROJECT_CONFIG_FILENAMES = Object.freeze(["opencode.jsonc", "opencode.json"]);
+
+export function findProjectConfigFile(projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    throw new Error("Project root must be a non-empty path.");
+  }
+  const root = resolve(projectRoot);
+  for (const name of PROJECT_CONFIG_FILENAMES) {
+    const candidate = join(root, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return join(root, PROJECT_CONFIG_FILE);
+}
+
+function isInsideDir(parent, child) {
+  const sep = join("a", "b").slice(1, -1) || (process.platform === "win32" ? "\\" : "/");
+  const resolvedParent = resolve(parent);
+  const resolvedChild = resolve(child);
+  if (process.platform === "win32") {
+    const lowerParent = resolvedParent.toLowerCase();
+    const lowerChild = resolvedChild.toLowerCase();
+    if (lowerChild === lowerParent) return true;
+    return lowerChild.startsWith(lowerParent + sep.toLowerCase());
+  }
+  if (resolvedChild === resolvedParent) return true;
+  return resolvedChild.startsWith(resolvedParent + sep);
+}
+
+function projectConfigConfinement(projectRoot, targetFile) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    throw new Error("Project root must be a non-empty path.");
+  }
+  if (typeof targetFile !== "string" || targetFile.length === 0) {
+    throw new Error("Project config file must be a non-empty path.");
+  }
+  const root = resolve(projectRoot);
+  const target = resolve(targetFile);
+  const globalDir = resolve(configDirectory());
+  const globalFile = resolve(findConfigFile(globalDir));
+  if (target === globalFile) {
+    throw new Error(`Refusing global config file ${target}; project helpers never touch global config.`);
+  }
+  if (isInsideDir(globalDir, target)) {
+    throw new Error(`Refusing path inside global config directory ${globalDir}; project helpers stay inside the project root.`);
+  }
+  if (root === globalDir || isInsideDir(globalDir, root)) {
+    throw new Error(`Refusing global config directory as project root ${root}; use a project checkout.`);
+  }
+  if (target !== root && !isInsideDir(root, target)) {
+    throw new Error(`Refusing outside path ${target}; project helpers stay inside ${root}.`);
+  }
+  const base = target.split(/[\\/]/).pop();
+  if (!PROJECT_CONFIG_FILENAMES.includes(base)) {
+    throw new Error(`Refusing non-project filename ${base}; project helpers edit only opencode.jsonc or opencode.json.`);
+  }
+  const directParent = resolve(join(target, ".."));
+  if (directParent !== root) {
+    throw new Error(`Refusing nested path ${target}; project helpers edit only the project root file.`);
+  }
+  return { root, target };
+}
+
+export function resolveProjectConfigFile(projectRoot, explicitFile) {
+  if (explicitFile !== undefined) {
+    const candidate = resolve(projectRoot, explicitFile);
+    projectConfigConfinement(projectRoot, candidate);
+    return candidate;
+  }
+  const found = findProjectConfigFile(projectRoot);
+  projectConfigConfinement(projectRoot, found);
+  return found;
+}
+
+const PROJECT_AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const PROJECT_PERMISSION_ACTIONS = new Set(["allow", "ask", "deny"]);
+
+function assertProjectAgentName(agentName) {
+  if (typeof agentName !== "string" || !PROJECT_AGENT_NAME_PATTERN.test(agentName)) {
+    throw new Error(`Invalid agent name ${JSON.stringify(agentName)}; use 1-64 letters, digits, dot, underscore, or hyphen starting alphanumeric.`);
+  }
+}
+
+function assertProjectPermissionUpdates(permissionUpdates) {
+  if (!permissionUpdates || typeof permissionUpdates !== "object" || Array.isArray(permissionUpdates)) {
+    throw new Error("Permission updates must be a non-array object mapping tool to action or pattern map.");
+  }
+  for (const [tool, value] of Object.entries(permissionUpdates)) {
+    if (typeof tool !== "string" || tool.length === 0 || tool.includes("/") || tool.includes("\\")) {
+      throw new Error(`Invalid permission tool ${JSON.stringify(tool)}.`);
+    }
+    if (value === undefined) continue;
+    if (typeof value === "string") {
+      if (!PROJECT_PERMISSION_ACTIONS.has(value)) {
+        throw new Error(`Invalid action ${JSON.stringify(value)} for ${tool}; use allow, ask, deny, or undefined to delete.`);
+      }
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(`Invalid permission value for ${tool}; use allow, ask, deny, undefined, or a pattern map.`);
+    }
+    for (const [pattern, action] of Object.entries(value)) {
+      if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new Error(`Invalid permission pattern ${JSON.stringify(pattern)} for ${tool}.`);
+      }
+      if (action !== undefined && !PROJECT_PERMISSION_ACTIONS.has(action)) {
+        throw new Error(`Invalid action ${JSON.stringify(action)} for ${tool} pattern ${JSON.stringify(pattern)}.`);
+      }
+    }
+  }
+}
+
+function parseProjectConfigText(text) {
+  const errors = [];
+  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)}.`);
+  }
+}
+
+// Per-key merge for one agent permission block. String values set the tool
+// shorthand; undefined deletes the tool; object values set per-pattern rules
+// with undefined deleting that pattern. Unrelated keys, plugins, tuples, and
+// sibling agents are preserved via modify plus applyEdits. Reapplying the
+// same updates is idempotent (no edits when values already match).
+export function updateProjectAgentPermissions(text, agentName, permissionUpdates) {
+  assertProjectAgentName(agentName);
+  assertProjectPermissionUpdates(permissionUpdates);
+  parseProjectConfigText(text);
+  const source = text || "{}";
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: source.includes("\r\n") ? "\r\n" : "\n" };
+  let updated = source;
+  for (const [tool, value] of Object.entries(permissionUpdates)) {
+    if (value === undefined) {
+      updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool], undefined, { formattingOptions }));
+    } else if (typeof value === "string") {
+      updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool], value, { formattingOptions }));
+    } else {
+      for (const [pattern, action] of Object.entries(value)) {
+        updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool, pattern], action, { formattingOptions }));
+      }
+    }
+  }
+  return updated;
+}
+
+export function writeProjectAgentPermissions(projectRoot, agentName, permissionUpdates, explicitFile) {
+  assertProjectAgentName(agentName);
+  assertProjectPermissionUpdates(permissionUpdates);
+  const file = resolveProjectConfigFile(projectRoot, explicitFile);
+  mkdirSync(resolve(projectRoot), { recursive: true });
+  const existed = existsSync(file);
+  const previous = existed ? readFileSync(file, "utf8") : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  const next = updateProjectAgentPermissions(previous, agentName, permissionUpdates);
+  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 backupFile(file, now = new Date()) {
   if (!existsSync(file)) return null;
   const stamp = now.toISOString().replace(/[:.]/g, "-");
@@ -198,6 +399,64 @@ export function writePluginConfig(configDir, remove = false, models) {
   return { file, backup, changed: true, existed };
 }
 
+// Native /steer command owned by the installer. Single source for the shape
+// lives in src/steer.js; these helpers persist it with the same JSONC
+// preserve-comments plus backup discipline as the plugin config. The entry
+// pins agent developer, carries an $ARGUMENTS template, and describes the
+// Developer-only direct-write hook.
+export {
+  STEER_COMMAND_AGENT,
+  STEER_COMMAND_DESCRIPTION,
+  STEER_COMMAND_NAME,
+  STEER_COMMAND_TEMPLATE,
+  steerCommandEntry,
+} from "./steer.js";
+
+export function updateCommandConfig(text, commandName, entry, remove = false) {
+  const errors = [];
+  const parsed = 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)}.`);
+  }
+  if (typeof commandName !== "string" || commandName.length === 0) {
+    throw new Error("Command name must be a non-empty string.");
+  }
+  const source = text || "{}";
+  if (remove && parsed?.command?.[commandName] === undefined) return source;
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: source.includes("\r\n") ? "\r\n" : "\n" };
+  const value = remove ? undefined : entry;
+  return applyEdits(source, modify(source, ["command", commandName], value, { formattingOptions }));
+}
+
+export function updateSteerCommand(text, entry = steerEntry(), remove = false) {
+  return updateCommandConfig(text, STEER_NAME, entry, remove);
+}
+
+export function isSteerCommandConfigured(text) {
+  const config = parse(text || "{}", [], { allowTrailingComma: true, disallowComments: false });
+  const entry = config?.command?.[STEER_NAME];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  return (
+    entry.agent === STEER_AGENT &&
+    typeof entry.template === "string" &&
+    entry.template.includes("$ARGUMENTS") &&
+    entry.description === STEER_DESCRIPTION
+  );
+}
+
+export function writeSteerCommand(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 = updateSteerCommand(previous, steerEntry(), 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 });
@@ -359,9 +618,16 @@ export function validateOpenCode(configDir) {
 export function status(configDir, packageRoot) {
   const file = findConfigFile(configDir);
   let configured = false;
+  let steerCommandConfigured = false;
   if (existsSync(file)) {
-    const config = parse(readFileSync(file, "utf8"), [], { allowTrailingComma: true, disallowComments: false });
+    const text = readFileSync(file, "utf8");
+    const config = parse(text, [], { allowTrailingComma: true, disallowComments: false });
     configured = Array.isArray(config?.plugin) && config.plugin.some(isOrchestrationPlugin);
+    try {
+      steerCommandConfigured = isSteerCommandConfigured(text);
+    } catch {
+      steerCommandConfigured = false;
+    }
   }
   const installed = installedVersion(configDir);
   let detectedAgents = [];
@@ -393,6 +659,7 @@ export function status(configDir, packageRoot) {
     updateAvailable: Boolean(installed && latest && installed !== latest),
     configFile: file,
     pluginConfigured: configured,
+    steerCommandConfigured,
     detectedAgents,
     agentsReady: detectedAgents.length === AGENT_NAMES.length,
     obsoleteAgentFiles,