harnery 0.40.0 → 0.42.0

package/src/core/hooks/adapter/wiring.ts

@@ -14,6 +14,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { codexWindowsBridgeConfig, resolveBinName } from "../../config.ts";
 import {
   ADAPTER_SPECS,
   type AdapterId,
@@ -21,20 +22,35 @@ import {
   type HookEntryShape,
   type HookEvent,
 } from "./events.ts";
+import { checkOpenCodePlugin, isOwnedOpenCodePlugin } from "./opencode-plugin.ts";
 
-/** Claude Code + Codex entry: `{ hooks: [{ type, command }] }`. */
+/** One Claude Code or Codex command handler. */
+export interface ClaudeHookHandler {
+  type: string;
+  command: string;
+  /** Codex: run instead of `command` on Windows. */
+  commandWindows?: string;
+  timeout?: number;
+}
+
+/** Claude Code + Codex entry: `{ hooks: [{ type, command, commandWindows?, timeout? }] }`. */
 export interface ClaudeHookGroup {
   matcher?: string;
-  hooks: { type: string; command: string }[];
+  hooks: ClaudeHookHandler[];
 }
 /** Cursor entry: a flat `{ command }`. */
 export interface CursorHookGroup {
   command: string;
   type?: string;
   matcher?: string;
+  /** Cursor Stop followup cap. Harnery pins 2; Cursor's own default is 5. */
+  loop_limit?: number;
 }
 export type HookGroup = ClaudeHookGroup | CursorHookGroup;
 
+/** Bound Cursor Stop `followup_message` retries so a missed ritual cannot loop 5 times. */
+export const CURSOR_STOP_FOLLOWUP_LOOP_LIMIT = 2;
+
 export interface SettingsFile {
   version?: number;
   description?: string;
@@ -43,8 +59,102 @@ export interface SettingsFile {
 }
 
 /** Build a hook entry in the adapter's shape. */
-export function makeEntry(shape: HookEntryShape, command: string): HookGroup {
-  return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
+export function makeEntry(
+  shape: HookEntryShape,
+  command: string,
+  extras?: { loop_limit?: number; timeout?: number; commandWindows?: string },
+): HookGroup {
+  if (shape !== "cursor") {
+    return {
+      hooks: [
+        orderHandlerKeys({
+          type: "command",
+          command,
+          commandWindows: extras?.commandWindows,
+          timeout: extras?.timeout,
+        }),
+      ],
+    };
+  }
+  return extras?.loop_limit !== undefined
+    ? { command, loop_limit: extras.loop_limit }
+    : { command };
+}
+
+/**
+ * Rebuild a handler with Harnery's fields first in a fixed order, dropping
+ * undefined ones and keeping any other fields after them.
+ */
+export function orderHandlerKeys(handler: ClaudeHookHandler): ClaudeHookHandler {
+  const { type, command, commandWindows, timeout, ...rest } = handler;
+  return {
+    type,
+    command,
+    ...(commandWindows !== undefined ? { commandWindows } : {}),
+    ...(timeout !== undefined ? { timeout } : {}),
+    ...rest,
+  };
+}
+
+/**
+ * The Windows command for an opted-in project (ADR 0197). It hands the hook to
+ * the bridge entry point when that is on PATH and the working directory is a
+ * WSL UNC path, and otherwise runs the usual command. `ProviderPath` drops the
+ * provider prefix that `Path` carries. The trailing `exit $LASTEXITCODE` is
+ * required: without it PowerShell reports any non-zero exit from inside the
+ * `if` block as 1, which would turn a hook's blocking exit 2 into a failure.
+ */
+export function hookCommandWindows(
+  spec: AdapterSpec,
+  agentHookPath: string,
+  subcommand: string,
+  adapter: AdapterId,
+  entryPoint: string,
+): string {
+  const direct = hookCommand(spec, agentHookPath, subcommand, adapter);
+  return (
+    `if ((Get-Command ${entryPoint} -ErrorAction Ignore) -and $PWD.ProviderPath -like '\\\\wsl*') ` +
+    `{ ${entryPoint} ${subcommand} --adapter ${adapter} } else { ${direct} }; exit $LASTEXITCODE`
+  );
+}
+
+/** Project-level choices that change what init writes. */
+export interface WiringOptions {
+  /** Bridge entry point from `hooks.codexWindowsBridge`, or null when not opted in. */
+  windowsBridgeEntryPoint?: string | null;
+}
+
+/** The `commandWindows` init writes for one event, or undefined for none. */
+export function expectedCommandWindows(
+  spec: AdapterSpec,
+  agentHookPath: string,
+  subcommand: string,
+  adapter: AdapterId,
+  options?: WiringOptions,
+): string | undefined {
+  if (!spec.windowsBridgeHooks || !options?.windowsBridgeEntryPoint) return undefined;
+  return hookCommandWindows(
+    spec,
+    agentHookPath,
+    subcommand,
+    adapter,
+    options.windowsBridgeEntryPoint,
+  );
+}
+
+/** The `timeout` init writes on one event's Harnery hook, or undefined for none. */
+export function hookTimeoutFor(spec: AdapterSpec, subcommand: string): number | undefined {
+  if (!spec.hookTimeouts) return undefined;
+  return spec.hookTimeouts.bySubcommand?.[subcommand] ?? spec.hookTimeouts.default;
+}
+
+/** Pin Cursor Stop followups to Harnery's loop cap. Returns true when the entry changed. */
+export function applyCursorStopLoopLimit(group: HookGroup, subcommand: string): boolean {
+  if (subcommand !== "stop") return false;
+  if (!("command" in group) || typeof group.command !== "string") return false;
+  if (group.loop_limit === CURSOR_STOP_FOLLOWUP_LOOP_LIMIT) return false;
+  group.loop_limit = CURSOR_STOP_FOLLOWUP_LOOP_LIMIT;
+  return true;
 }
 
 /** Pull every command string out of a hook entry, regardless of shape. */
@@ -121,7 +231,7 @@ export interface WiringDiff {
   duplicates: HookEvent[];
   /** Spec events wired under an event key other than the canonical one. */
   misplaced: HookEvent[];
-  /** Spec events whose correct-key command differs from init's canonical command. */
+  /** Spec events whose correct-key command, `commandWindows`, or `timeout` differs from what init writes. */
   stale: HookEvent[];
   /** Settings fields rejected by a adapter with a strict top-level schema. */
   invalidTopLevelKeys: string[];
@@ -136,7 +246,7 @@ export interface WiringDiff {
 export function diffWiring(
   settings: SettingsFile,
   spec: AdapterSpec,
-  expected?: { agentHookPath: string; adapter: AdapterId },
+  expected?: { agentHookPath: string; adapter: AdapterId } & WiringOptions,
 ): WiringDiff {
   const missing: HookEvent[] = [];
   const present: HookEvent[] = [];
@@ -159,7 +269,27 @@ export function diffWiring(
         event.subcommand,
         expected.adapter,
       );
-      if (commands.some((command) => command !== canonical)) stale.push(event);
+      const timeout = hookTimeoutFor(spec, event.subcommand);
+      const commandWindows = expectedCommandWindows(
+        spec,
+        expected.agentHookPath,
+        event.subcommand,
+        expected.adapter,
+        expected,
+      );
+      const handlerDrift = groups.some(
+        (group) =>
+          "hooks" in group &&
+          Array.isArray(group.hooks) &&
+          group.hooks.some(
+            (hook) =>
+              typeof hook.command === "string" &&
+              commandWiresSubcommand(hook.command, event.subcommand) &&
+              ((timeout !== undefined && hook.timeout !== timeout) ||
+                (spec.windowsBridgeHooks === true && hook.commandWindows !== commandWindows)),
+          ),
+      );
+      if (handlerDrift || commands.some((command) => command !== canonical)) stale.push(event);
     }
     const wrongKey = Object.entries(hooks).some(
       ([key, otherGroups]) =>
@@ -219,6 +349,48 @@ export interface AdapterWiringStatus {
   invalidTopLevelKeys: string[];
   invalidEventKeys: string[];
   parseError?: string;
+  /**
+   * `opencode-plugin` install mode only: why the installed plugin differs from
+   * what init writes now (stale source, missing/stale `harnery.json`, or a
+   * foreign file at the harnery path). Hook-map fields stay empty for it.
+   */
+  pluginIssues?: string[];
+}
+
+function emptyWiringStatus(adapter: AdapterId, settingsFile: string): AdapterWiringStatus {
+  return {
+    adapter,
+    settingsFile,
+    missing: [],
+    orphans: [],
+    duplicates: [],
+    misplaced: [],
+    stale: [],
+    invalidTopLevelKeys: [],
+    invalidEventKeys: [],
+  };
+}
+
+/**
+ * Plugin-mode drift: the installed entry exists but is not what init would
+ * write now. Absent entry → not opted in → null (mirrors the hook-map rule).
+ * Without a resolvable package root the launcher cannot be compared, so only
+ * the source freshness is judged.
+ */
+function pluginDrift(
+  projectRoot: string,
+  id: AdapterId,
+  spec: AdapterSpec,
+): AdapterWiringStatus | null {
+  if (!existsSync(resolve(projectRoot, spec.settingsFile))) return null;
+  const packageRoot = harneryPackageRoot();
+  const check = checkOpenCodePlugin(projectRoot, {
+    binName: resolveBinName(projectRoot),
+    agentHook: packageRoot ? agentHookPathForProject(projectRoot, packageRoot) : "agent-hook",
+  });
+  if (check.status === "fresh") return null;
+  if (check.status === "missing") return null;
+  return { ...emptyWiringStatus(id, spec.settingsFile), pluginIssues: check.issues };
 }
 
 /**
@@ -235,6 +407,11 @@ export interface AdapterWiringStatus {
 export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
   const out: AdapterWiringStatus[] = [];
   for (const [id, spec] of Object.entries(ADAPTER_SPECS) as [AdapterId, AdapterSpec][]) {
+    if (spec.installMode === "opencode-plugin") {
+      const drift = pluginDrift(projectRoot, id, spec);
+      if (drift) out.push(drift);
+      continue;
+    }
     const settingsPath = resolve(projectRoot, spec.settingsFile);
     if (!existsSync(settingsPath)) continue;
     let settings: SettingsFile;
@@ -242,15 +419,7 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
       settings = JSON.parse(readFileSync(settingsPath, "utf8")) as SettingsFile;
     } catch (error) {
       out.push({
-        adapter: id,
-        settingsFile: spec.settingsFile,
-        missing: [],
-        orphans: [],
-        duplicates: [],
-        misplaced: [],
-        stale: [],
-        invalidTopLevelKeys: [],
-        invalidEventKeys: [],
+        ...emptyWiringStatus(id, spec.settingsFile),
         parseError: (error as Error).message,
       });
       continue;
@@ -263,6 +432,7 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
         ? {
             agentHookPath: agentHookPathForProject(projectRoot, packageRoot),
             adapter: id,
+            windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
           }
         : undefined,
     );
@@ -325,6 +495,18 @@ export function summarizeAdapterWiring(projectRoot: string): AdapterWiringSummar
       unwired.push(id);
       continue;
     }
+    if (spec.installMode === "opencode-plugin") {
+      // The entry counts as wired only when harnery owns it; a foreign file at
+      // that path is drift (surfaced by loadAdapterWiring), not a wiring.
+      let content: string;
+      try {
+        content = readFileSync(settingsPath, "utf8");
+      } catch {
+        continue;
+      }
+      (isOwnedOpenCodePlugin(content) ? wired : unwired).push(id);
+      continue;
+    }
     let settings: SettingsFile;
     try {
       settings = JSON.parse(readFileSync(settingsPath, "utf8")) as SettingsFile;