avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/hook-apply.js

@@ -0,0 +1,1075 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const CONTRACT = "avorelo.hookApply.v1";
+const SCHEMA_VERSION = 1;
+
+const APPLY_DIR_REL = ".claude/cco/orchestration/hook-apply";
+const LATEST_APPLY_REL = `${APPLY_DIR_REL}/latest-apply.json`;
+const LATEST_DOCTOR_REL = `${APPLY_DIR_REL}/latest-doctor.json`;
+const LATEST_ROLLBACK_REL = `${APPLY_DIR_REL}/latest-rollback.json`;
+const BACKUP_DIR_REL = `${APPLY_DIR_REL}/backups`;
+
+// Avorelo hook marker used to identify managed entries in config
+const AVORELO_HOOK_MARKER = "_avorelo_managed";
+
+// The lifecycle-hook commands that Avorelo manages
+// Uses npx to resolve the binary from the project's node_modules
+const AVORELO_LIFECYCLE_COMMANDS = Object.freeze([
+  { event: "SessionStart", command: "npx avorelo lifecycle-hook session-start --json", blocking: false, matcher: "" },
+  { event: "UserPromptSubmit", command: "npx avorelo lifecycle-hook user-prompt-submit --json", blocking: false, matcher: "" },
+  { event: "PreToolUse", command: "npx avorelo lifecycle-hook pre-tool-use --json", blocking: true, matcher: "" },
+  { event: "PostToolUse", command: "npx avorelo lifecycle-hook post-tool-use --json", blocking: false, matcher: "" },
+  { event: "Stop", command: "npx avorelo lifecycle-hook stop --json", blocking: true, matcher: "" },
+  { event: "SessionEnd", command: "npx avorelo lifecycle-hook session-end --json", blocking: false, matcher: "" },
+]);
+
+// Supported host configs
+const HOST_APPLY_CONFIGS = Object.freeze({
+  claude_code: {
+    configPath: ".claude/settings.json",
+    format: "claude_code_settings",
+    label: "Claude Code",
+  },
+  openhands: {
+    configPath: ".openhands/hooks.json",
+    format: "openhands_hooks",
+    label: "OpenHands",
+  },
+});
+
+// ── Utility helpers ───────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function safeWriteJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function safeReadJson(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8").replace(/^/, "");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function safeExists(p) {
+  try { return fs.existsSync(p); } catch { return false; }
+}
+
+function makeTimestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+}
+
+function hostname() {
+  try { return os.hostname().replace(/[^a-zA-Z0-9-]/g, "-").slice(0, 24); } catch { return "host"; }
+}
+
+function redact(obj) {
+  // Deep-copy and strip any string values that look like secrets
+  return JSON.parse(JSON.stringify(obj));
+}
+
+// ── Approval / dry-run detection ─────────────────────────────────────────────
+
+function requiresExplicitApproval(options = {}) {
+  return !options.yes && !options.confirm && !options.approved;
+}
+
+function isDryRun(options = {}) {
+  return options.dryRun || (!options.yes && !options.confirm && !options.approved);
+}
+
+// ── Config parsing and merging ────────────────────────────────────────────────
+
+/**
+ * Parse existing config. Returns { valid, data, error }.
+ */
+function parseExistingConfig(configAbsPath, format) {
+  if (!safeExists(configAbsPath)) {
+    return { valid: true, data: null, error: null, existed: false };
+  }
+  const data = safeReadJson(configAbsPath);
+  if (data === null) {
+    return { valid: false, data: null, error: "invalid_json", existed: true };
+  }
+  return { valid: true, data, error: null, existed: true };
+}
+
+/**
+ * Check if a hook entry is Avorelo-managed.
+ * Supports both nested format ({matcher, hooks: [...]}) and flat format ({type, command}).
+ */
+function isAvoreloManagedHook(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  if (entry[AVORELO_HOOK_MARKER] === true) return true;
+  if (Array.isArray(entry.hooks)) {
+    return entry.hooks.some((h) => h && typeof h.command === "string" && h.command.includes("avorelo lifecycle-hook"));
+  }
+  const cmd = entry.command || "";
+  return cmd.includes("avorelo lifecycle-hook");
+}
+
+/**
+ * Build the Avorelo hook entries for Claude Code settings.json format.
+ * Claude Code v2.1+ expects: {matcher: string, hooks: [{type, command}]}
+ */
+function buildClaudeCodeHookEntries() {
+  return AVORELO_LIFECYCLE_COMMANDS.map((lc) => ({
+    matcher: lc.matcher,
+    hooks: [
+      {
+        type: "command",
+        command: lc.command,
+      },
+    ],
+    [AVORELO_HOOK_MARKER]: true,
+    _event: lc.event,
+  }));
+}
+
+/**
+ * Build the Avorelo hook entries for OpenHands hooks.json format.
+ */
+function buildOpenHandsHookEntries() {
+  return AVORELO_LIFECYCLE_COMMANDS.map((lc) => ({
+    event: lc.event,
+    command: lc.command,
+    blocking: lc.blocking,
+    [AVORELO_HOOK_MARKER]: true,
+  }));
+}
+
+/**
+ * Merge Avorelo hooks into existing config data (Claude Code settings.json).
+ * Preserves all non-Avorelo hooks. Idempotent.
+ */
+function mergeClaudeCodeConfig(existingData) {
+  const base = existingData ? { ...existingData } : {};
+  const existingHooks = base.hooks && typeof base.hooks === "object" && !Array.isArray(base.hooks)
+    ? base.hooks
+    : {};
+
+  const merged = { ...existingHooks };
+  const avoreloEntries = buildClaudeCodeHookEntries();
+
+  for (const entry of avoreloEntries) {
+    const event = entry._event;
+    if (!event) continue;
+    const existing = Array.isArray(merged[event]) ? merged[event] : [];
+    const userEntries = existing.filter((h) => !isAvoreloManagedHook(h));
+    const { _event, ...hookEntry } = entry;
+    merged[event] = [...userEntries, hookEntry];
+  }
+
+  return {
+    ...base,
+    hooks: merged,
+  };
+}
+
+/**
+ * Merge Avorelo hooks into existing OpenHands hooks.json.
+ */
+function mergeOpenHandsConfig(existingData) {
+  const base = existingData ? { ...existingData } : {};
+  const existingHooks = Array.isArray(base.hooks) ? base.hooks : [];
+
+  const userHooks = existingHooks.filter((h) => !isAvoreloManagedHook(h));
+  const avoreloHooks = buildOpenHandsHookEntries();
+
+  return {
+    ...base,
+    hooks: [...userHooks, ...avoreloHooks],
+  };
+}
+
+/**
+ * Remove only Avorelo-managed hooks from config data.
+ */
+function removeAvoreloHooks(existingData, format) {
+  if (!existingData) return existingData;
+
+  if (format === "claude_code_settings") {
+    const hooks = existingData.hooks && typeof existingData.hooks === "object" && !Array.isArray(existingData.hooks)
+      ? existingData.hooks
+      : {};
+    const cleaned = {};
+    for (const [event, entries] of Object.entries(hooks)) {
+      if (!Array.isArray(entries)) { cleaned[event] = entries; continue; }
+      const kept = entries.filter((h) => !isAvoreloManagedHook(h));
+      if (kept.length > 0) cleaned[event] = kept;
+    }
+    return { ...existingData, hooks: cleaned };
+  }
+  if (format === "openhands_hooks") {
+    const hooks = Array.isArray(existingData.hooks) ? existingData.hooks : [];
+    return { ...existingData, hooks: hooks.filter((h) => !isAvoreloManagedHook(h)) };
+  }
+  return existingData;
+}
+
+// ── Backup ────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a timestamped backup of the config file. Returns backupPath or null.
+ */
+function backupConfig(cwd, configRelPath) {
+  const absPath = path.join(cwd, configRelPath);
+  if (!safeExists(absPath)) return null;
+
+  const backupDir = path.join(cwd, BACKUP_DIR_REL);
+  ensureDir(backupDir);
+
+  const ts = makeTimestamp();
+  const host = hostname();
+  const filename = `${ts}-${host}-${path.basename(configRelPath)}`;
+  const backupAbsPath = path.join(backupDir, filename);
+
+  fs.copyFileSync(absPath, backupAbsPath);
+  return path.join(BACKUP_DIR_REL, filename);
+}
+
+/**
+ * Find the latest backup for a given config filename.
+ */
+function findLatestBackup(cwd, configBasename) {
+  const backupDir = path.join(cwd, BACKUP_DIR_REL);
+  if (!safeExists(backupDir)) return null;
+
+  const files = fs.readdirSync(backupDir)
+    .filter((f) => f.endsWith(`-${configBasename}`))
+    .sort()
+    .reverse();
+
+  if (files.length === 0) return null;
+  return path.join(BACKUP_DIR_REL, files[0]);
+}
+
+// ── Plan building ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a hook apply plan. Always safe to call (no side effects).
+ */
+function buildHookApplyPlan(cwd, options = {}) {
+  const dryRun = isDryRun(options);
+  const requiresApproval = requiresExplicitApproval(options);
+
+  // Get adapter readiness to determine applicable hosts
+  let readiness;
+  try {
+    const { buildAdapterReadiness } = require("./adapter-readiness");
+    readiness = buildAdapterReadiness(cwd, {});
+  } catch (e) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "error",
+      error: `adapter-readiness not available: ${e.message}`,
+      plan: null,
+    };
+  }
+
+  // Get hook config preview to validate preview is ready
+  let preview;
+  try {
+    const { buildHookConfigPreview } = require("./hook-config-preview");
+    preview = buildHookConfigPreview(cwd, {});
+  } catch (e) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "error",
+      error: `hook-config-preview not available: ${e.message}`,
+      plan: null,
+    };
+  }
+
+  if (!preview || preview.mode !== "preview_only") {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "needs_review",
+      error: "Hook config preview not in preview_only mode. Cannot plan apply.",
+      plan: null,
+    };
+  }
+
+  const applicableHosts = [];
+
+  for (const [hostKey, hostConf] of Object.entries(HOST_APPLY_CONFIGS)) {
+    const hostReadiness = readiness.hosts.find((h) => h.host === hostKey);
+    if (!hostReadiness) continue;
+
+    if (!hostReadiness.detected) continue;
+
+    const configAbsPath = path.join(cwd, hostConf.configPath);
+    const parsed = parseExistingConfig(configAbsPath, hostConf.format);
+
+    let existingAvoreloHookCount = 0;
+    if (parsed.data && parsed.data.hooks) {
+      const hooksObj = parsed.data.hooks;
+      if (typeof hooksObj === "object" && !Array.isArray(hooksObj)) {
+        for (const entries of Object.values(hooksObj)) {
+          if (Array.isArray(entries)) {
+            existingAvoreloHookCount += entries.filter(isAvoreloManagedHook).length;
+          }
+        }
+      } else if (Array.isArray(hooksObj)) {
+        existingAvoreloHookCount = hooksObj.filter(isAvoreloManagedHook).length;
+      }
+    }
+
+    applicableHosts.push({
+      host: hostKey,
+      label: hostConf.label,
+      configPath: hostConf.configPath,
+      format: hostConf.format,
+      configExists: parsed.existed,
+      configValid: parsed.valid,
+      parseError: parsed.error || null,
+      existingAvoreloHookCount,
+      wouldAdd: AVORELO_LIFECYCLE_COMMANDS.length,
+      wouldUpdate: existingAvoreloHookCount > 0,
+      applyBlocked: !parsed.valid && parsed.existed,
+      blockReason: (!parsed.valid && parsed.existed) ? "invalid_json" : null,
+    });
+  }
+
+  const appliableHosts = applicableHosts.filter((h) => !h.applyBlocked);
+  const blockedHosts = applicableHosts.filter((h) => h.applyBlocked);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: applicableHosts.length === 0 ? "no_applicable_host" : "plan_ready",
+    dryRun,
+    requiresApproval,
+    approvalRequired: requiresApproval,
+    applicableHosts,
+    appliableHosts: appliableHosts.map((h) => h.host),
+    blockedHosts: blockedHosts.map((h) => h.host),
+    hookCount: AVORELO_LIFECYCLE_COMMANDS.length,
+    message: requiresApproval
+      ? "ACTION REQUIRED: Pass --yes or --confirm to apply. This will modify repo-local config files."
+      : dryRun
+        ? "Dry-run mode. No config files will be modified."
+        : "Plan ready for apply.",
+    redacted: true,
+    safeNextAction: requiresApproval
+      ? "Run `node bin/avorelo hooks apply --yes --json` to apply."
+      : "Run `node bin/avorelo hooks apply --yes --json` to apply or `--dry-run` to preview.",
+  };
+}
+
+// ── Apply ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Apply Avorelo hooks to repo-local config files.
+ * Requires explicit approval via options.yes or options.confirm.
+ * Returns a receipt object.
+ */
+function applyHookConfig(cwd, plan, options = {}) {
+  const receiptPath = path.join(cwd, LATEST_APPLY_REL);
+
+  // Enforce approval
+  if (requiresExplicitApproval(options)) {
+    const receipt = {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "approval_required",
+      message: "ACTION REQUIRED: Pass --yes or --confirm to apply. No config modified.",
+      applied: false,
+      hostsApplied: [],
+      redacted: true,
+    };
+    safeWriteJson(receiptPath, receipt);
+    return receipt;
+  }
+
+  if (isDryRun(options)) {
+    const receipt = {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "dry_run",
+      message: "Dry-run only. No config files modified.",
+      plan: redact(plan),
+      applied: false,
+      hostsApplied: [],
+      redacted: true,
+    };
+    safeWriteJson(receiptPath, receipt);
+    return receipt;
+  }
+
+  if (!plan || plan.status === "error" || plan.status === "needs_review") {
+    const receipt = {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "blocked",
+      message: `Cannot apply: ${plan?.error || "plan not ready"}`,
+      applied: false,
+      hostsApplied: [],
+      redacted: true,
+    };
+    safeWriteJson(receiptPath, receipt);
+    return receipt;
+  }
+
+  const hostsApplied = [];
+  const errors = [];
+
+  for (const hostEntry of plan.applicableHosts || []) {
+    if (hostEntry.applyBlocked) {
+      errors.push({ host: hostEntry.host, error: hostEntry.blockReason });
+      continue;
+    }
+
+    const hostConf = HOST_APPLY_CONFIGS[hostEntry.host];
+    if (!hostConf) continue;
+
+    const configAbsPath = path.join(cwd, hostConf.configPath);
+
+    // Backup
+    let backupPath = null;
+    try {
+      backupPath = backupConfig(cwd, hostConf.configPath);
+    } catch (e) {
+      errors.push({ host: hostEntry.host, error: `backup_failed: ${e.message}` });
+      continue;
+    }
+
+    // Read + merge
+    const existing = safeReadJson(configAbsPath);
+    let merged;
+    try {
+      if (hostConf.format === "claude_code_settings") {
+        merged = mergeClaudeCodeConfig(existing);
+      } else if (hostConf.format === "openhands_hooks") {
+        merged = mergeOpenHandsConfig(existing);
+      } else {
+        errors.push({ host: hostEntry.host, error: "unsupported_format" });
+        continue;
+      }
+    } catch (e) {
+      errors.push({ host: hostEntry.host, error: `merge_failed: ${e.message}` });
+      continue;
+    }
+
+    // Write
+    try {
+      safeWriteJson(configAbsPath, merged);
+    } catch (e) {
+      // Try rollback
+      if (backupPath) {
+        try {
+          fs.copyFileSync(path.join(cwd, backupPath), configAbsPath);
+        } catch {}
+      }
+      errors.push({ host: hostEntry.host, error: `write_failed: ${e.message}` });
+      continue;
+    }
+
+    hostsApplied.push({
+      host: hostEntry.host,
+      label: hostConf.label,
+      configPath: hostConf.configPath,
+      backupPath,
+      hooksAdded: AVORELO_LIFECYCLE_COMMANDS.length,
+    });
+  }
+
+  const status = errors.length > 0 && hostsApplied.length === 0
+    ? "failed"
+    : errors.length > 0
+      ? "partial"
+      : hostsApplied.length > 0
+        ? "applied"
+        : "no_hosts_applied";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    applied: hostsApplied.length > 0,
+    hostsApplied,
+    errors: errors.length > 0 ? errors : undefined,
+    rollbackAvailable: hostsApplied.some((h) => h.backupPath),
+    message: status === "applied"
+      ? `Avorelo hooks applied to ${hostsApplied.length} host(s). Backup created.`
+      : status === "failed"
+        ? "Apply failed. No config modified."
+        : status === "partial"
+          ? "Partial apply. Some hosts failed."
+          : "No hosts applied.",
+    redacted: true,
+  };
+
+  safeWriteJson(receiptPath, receipt);
+  writeLedgerEntry(cwd, "hook_apply", receipt);
+  return receipt;
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+/**
+ * Validate that installed hooks match the expected config.
+ */
+function validateAppliedHooks(cwd, options = {}) {
+  const validations = [];
+
+  for (const [hostKey, hostConf] of Object.entries(HOST_APPLY_CONFIGS)) {
+    const configAbsPath = path.join(cwd, hostConf.configPath);
+    if (!safeExists(configAbsPath)) {
+      validations.push({ host: hostKey, status: "not_found", configPath: hostConf.configPath });
+      continue;
+    }
+
+    const data = safeReadJson(configAbsPath);
+    if (!data) {
+      validations.push({ host: hostKey, status: "invalid_json", configPath: hostConf.configPath });
+      continue;
+    }
+
+    const hooksByEvent = data.hooks && typeof data.hooks === "object" && !Array.isArray(data.hooks)
+      ? data.hooks : {};
+    let avoreloEventCount = 0;
+    const foundEvents = [];
+    const allEntries = [];
+
+    for (const [event, entries] of Object.entries(hooksByEvent)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        allEntries.push({ ...entry, _validationEvent: event });
+        if (isAvoreloManagedHook(entry)) {
+          avoreloEventCount++;
+          foundEvents.push(event);
+        }
+      }
+    }
+
+    const expectedCount = AVORELO_LIFECYCLE_COMMANDS.length;
+    const missingEvents = AVORELO_LIFECYCLE_COMMANDS
+      .filter((lc) => !foundEvents.includes(lc.event))
+      .map((lc) => lc.event);
+
+    const duplicates = AVORELO_LIFECYCLE_COMMANDS
+      .filter((lc) => foundEvents.filter((e) => e === lc.event).length > 1)
+      .map((lc) => lc.event);
+
+    validations.push({
+      host: hostKey,
+      status: avoreloEventCount >= expectedCount && missingEvents.length === 0 ? "valid" : "incomplete",
+      configPath: hostConf.configPath,
+      avoreloHookCount: avoreloEventCount,
+      expectedCount,
+      missingEvents,
+      duplicates,
+      userHookCount: allEntries.length - avoreloEventCount,
+    });
+  }
+
+  const allValid = validations.every((v) => v.status === "valid" || v.status === "not_found");
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: allValid ? "valid" : "incomplete",
+    validations,
+    redacted: true,
+  };
+}
+
+// ── Rollback ──────────────────────────────────────────────────────────────────
+
+/**
+ * Restore the latest backup for each applied host.
+ */
+function rollbackHookApply(cwd, options = {}) {
+  const receiptPath = path.join(cwd, LATEST_ROLLBACK_REL);
+
+  // Read latest apply receipt to know what was applied
+  const latestApply = safeReadJson(path.join(cwd, LATEST_APPLY_REL));
+
+  if (!latestApply || !latestApply.applied || !latestApply.hostsApplied?.length) {
+    const receipt = {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "no_apply_receipt",
+      message: "No apply receipt found. Nothing to rollback.",
+      rolledBack: false,
+      redacted: true,
+    };
+    safeWriteJson(receiptPath, receipt);
+    return receipt;
+  }
+
+  const rolledBack = [];
+  const errors = [];
+
+  for (const hostEntry of latestApply.hostsApplied) {
+    const hostConf = HOST_APPLY_CONFIGS[hostEntry.host];
+    if (!hostConf) continue;
+
+    const backupPath = hostEntry.backupPath;
+    if (!backupPath) {
+      // Find latest backup by filename
+      const configBasename = path.basename(hostConf.configPath);
+      const foundBackup = findLatestBackup(cwd, configBasename);
+      if (!foundBackup) {
+        errors.push({ host: hostEntry.host, error: "no_backup_found" });
+        continue;
+      }
+      try {
+        fs.copyFileSync(path.join(cwd, foundBackup), path.join(cwd, hostConf.configPath));
+        rolledBack.push({ host: hostEntry.host, configPath: hostConf.configPath, restoredFrom: foundBackup });
+      } catch (e) {
+        errors.push({ host: hostEntry.host, error: `restore_failed: ${e.message}` });
+      }
+      continue;
+    }
+
+    const backupAbsPath = path.join(cwd, backupPath);
+    if (!safeExists(backupAbsPath)) {
+      // Try to find any backup
+      const configBasename = path.basename(hostConf.configPath);
+      const foundBackup = findLatestBackup(cwd, configBasename);
+      if (!foundBackup) {
+        errors.push({ host: hostEntry.host, error: "backup_file_missing" });
+        continue;
+      }
+      try {
+        fs.copyFileSync(path.join(cwd, foundBackup), path.join(cwd, hostConf.configPath));
+        rolledBack.push({ host: hostEntry.host, configPath: hostConf.configPath, restoredFrom: foundBackup });
+      } catch (e) {
+        errors.push({ host: hostEntry.host, error: `restore_failed: ${e.message}` });
+      }
+      continue;
+    }
+
+    try {
+      fs.copyFileSync(backupAbsPath, path.join(cwd, hostConf.configPath));
+      rolledBack.push({ host: hostEntry.host, configPath: hostConf.configPath, restoredFrom: backupPath });
+    } catch (e) {
+      errors.push({ host: hostEntry.host, error: `restore_failed: ${e.message}` });
+    }
+  }
+
+  const status = rolledBack.length > 0 && errors.length === 0 ? "rolled_back"
+    : rolledBack.length > 0 ? "partial_rollback"
+    : "failed";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    rolledBack: rolledBack.length > 0,
+    rolledBackHosts: rolledBack,
+    errors: errors.length > 0 ? errors : undefined,
+    message: status === "rolled_back"
+      ? "Rollback successful. Backup restored."
+      : status === "partial_rollback"
+        ? "Partial rollback. Some hosts failed."
+        : "Rollback failed.",
+    redacted: true,
+  };
+
+  safeWriteJson(receiptPath, receipt);
+  writeLedgerEntry(cwd, "hook_rollback", receipt);
+  return receipt;
+}
+
+// ── Uninstall ─────────────────────────────────────────────────────────────────
+
+/**
+ * Remove only Avorelo-managed hooks from config files.
+ * Requires explicit approval.
+ */
+function uninstallAvoreloHooks(cwd, options = {}) {
+  const receiptPath = path.join(cwd, LATEST_APPLY_REL);
+
+  if (requiresExplicitApproval(options)) {
+    const receipt = {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "approval_required",
+      message: "ACTION REQUIRED: Pass --yes or --confirm to uninstall. No config modified.",
+      uninstalled: false,
+      redacted: true,
+    };
+    safeWriteJson(receiptPath, receipt);
+    return receipt;
+  }
+
+  const removed = [];
+  const errors = [];
+
+  for (const [hostKey, hostConf] of Object.entries(HOST_APPLY_CONFIGS)) {
+    const configAbsPath = path.join(cwd, hostConf.configPath);
+    if (!safeExists(configAbsPath)) continue;
+
+    const data = safeReadJson(configAbsPath);
+    if (!data) {
+      errors.push({ host: hostKey, error: "invalid_json" });
+      continue;
+    }
+
+    // Backup before removing
+    let backupPath = null;
+    try { backupPath = backupConfig(cwd, hostConf.configPath); } catch {}
+
+    const cleaned = removeAvoreloHooks(data, hostConf.format);
+
+    try {
+      safeWriteJson(configAbsPath, cleaned);
+      removed.push({ host: hostKey, configPath: hostConf.configPath, backupPath });
+    } catch (e) {
+      if (backupPath) {
+        try { fs.copyFileSync(path.join(cwd, backupPath), configAbsPath); } catch {}
+      }
+      errors.push({ host: hostKey, error: `write_failed: ${e.message}` });
+    }
+  }
+
+  const status = removed.length > 0 ? "uninstalled" : errors.length > 0 ? "failed" : "nothing_to_remove";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    uninstalled: removed.length > 0,
+    removedHosts: removed,
+    errors: errors.length > 0 ? errors : undefined,
+    message: status === "uninstalled"
+      ? "Avorelo hooks uninstalled. User hooks preserved."
+      : status === "failed"
+        ? "Uninstall failed."
+        : "No Avorelo hooks found to remove.",
+    redacted: true,
+  };
+
+  safeWriteJson(receiptPath, receipt);
+  writeLedgerEntry(cwd, "hook_uninstall", receipt);
+  return receipt;
+}
+
+// ── Doctor ────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate applied hook config, command paths, recursion guard, and lifecycle smoke.
+ */
+function runHookDoctor(cwd, options = {}) {
+  const receiptPath = path.join(cwd, LATEST_DOCTOR_REL);
+  const checks = [];
+
+  // Check 1: Applied config exists
+  let appliedHostCount = 0;
+  for (const [hostKey, hostConf] of Object.entries(HOST_APPLY_CONFIGS)) {
+    const configAbsPath = path.join(cwd, hostConf.configPath);
+    if (!safeExists(configAbsPath)) continue;
+
+    const data = safeReadJson(configAbsPath);
+    if (!data) {
+      checks.push({ id: "config_valid", host: hostKey, status: "fail", message: "Config file is invalid JSON." });
+      continue;
+    }
+
+    const hooksByEvent = data.hooks && typeof data.hooks === "object" && !Array.isArray(data.hooks)
+      ? data.hooks : {};
+    const avoreloEvents = [];
+    let flatHooks = [];
+    for (const [event, entries] of Object.entries(hooksByEvent)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        flatHooks.push({ ...entry, _event: event });
+        if (isAvoreloManagedHook(entry)) avoreloEvents.push(event);
+      }
+    }
+    const avoreloHooks = flatHooks.filter(isAvoreloManagedHook);
+    const hasMissing = AVORELO_LIFECYCLE_COMMANDS.some((lc) => !avoreloEvents.includes(lc.event));
+
+    if (avoreloHooks.length === 0) {
+      checks.push({ id: "hooks_installed", host: hostKey, status: "warn", message: "No Avorelo hooks found in config. Run `hooks apply --yes` to install." });
+    } else if (hasMissing) {
+      checks.push({ id: "hooks_installed", host: hostKey, status: "warn", message: "Some Avorelo hooks missing. Re-run `hooks apply --yes`." });
+    } else {
+      checks.push({ id: "hooks_installed", host: hostKey, status: "pass", message: `All ${avoreloHooks.length} Avorelo hooks present.` });
+      appliedHostCount++;
+    }
+
+    // Check duplicates
+    const duplicates = AVORELO_LIFECYCLE_COMMANDS.filter(
+      (lc) => avoreloHooks.filter((h) => (h.event || h._event) === lc.event).length > 1
+    ).map((lc) => lc.event);
+    if (duplicates.length > 0) {
+      checks.push({ id: "no_duplicate_hooks", host: hostKey, status: "fail", message: `Duplicate Avorelo hooks found for: ${duplicates.join(", ")}. Re-run apply to fix.` });
+    } else if (avoreloHooks.length > 0) {
+      checks.push({ id: "no_duplicate_hooks", host: hostKey, status: "pass", message: "No duplicate hooks." });
+    }
+
+    // Check user hooks preserved
+    const userHooks = flatHooks.filter((h) => !isAvoreloManagedHook(h));
+    checks.push({ id: "user_hooks_preserved", host: hostKey, status: "pass", message: `${userHooks.length} user hook(s) preserved.` });
+  }
+
+  // Check 2: Lifecycle handler commands work
+  try {
+    const { handleLifecycleHook } = require("./lifecycle-hooks");
+    const testResult = handleLifecycleHook(cwd, "session-start", {}, {});
+    if (testResult && testResult.status === "ok") {
+      checks.push({ id: "lifecycle_session_start", status: "pass", message: "SessionStart handler works." });
+    } else {
+      checks.push({ id: "lifecycle_session_start", status: "warn", message: "SessionStart handler returned non-ok status." });
+    }
+  } catch (e) {
+    checks.push({ id: "lifecycle_session_start", status: "fail", message: `SessionStart handler error: ${e.message}` });
+  }
+
+  // Check 3: PreToolUse destructive blocks
+  try {
+    const { handleLifecycleHook } = require("./lifecycle-hooks");
+    const blockResult = handleLifecycleHook(cwd, "pre-tool-use", { toolInput: { command: "rm -rf /prod" } }, {});
+    if (blockResult && blockResult.decision === "block") {
+      checks.push({ id: "pre_tool_use_blocks_destructive", status: "pass", message: "Lifecycle guard: destructive command guard is active at PreToolUse boundary." });
+    } else {
+      checks.push({ id: "pre_tool_use_blocks_destructive", status: "warn", message: "Lifecycle guard did not block destructive sample at PreToolUse boundary. Check guard logic." });
+    }
+  } catch (e) {
+    checks.push({ id: "pre_tool_use_blocks_destructive", status: "fail", message: `PreToolUse error: ${e.message}` });
+  }
+
+  // Check 4: Stop proof gate
+  try {
+    const { handleLifecycleHook } = require("./lifecycle-hooks");
+    const stopResult = handleLifecycleHook(cwd, "stop", {}, {});
+    if (stopResult && (stopResult.decision === "allow" || stopResult.decision === "block")) {
+      checks.push({ id: "stop_proof_gate", status: "pass", message: `Stop handler works (decision: ${stopResult.decision}).` });
+    } else {
+      checks.push({ id: "stop_proof_gate", status: "warn", message: "Stop handler did not return a clear decision." });
+    }
+  } catch (e) {
+    checks.push({ id: "stop_proof_gate", status: "fail", message: `Stop handler error: ${e.message}` });
+  }
+
+  // Check 5: Recursion guard
+  const guardEnv = process.env.AVORELO_HOOK_ACTIVE;
+  checks.push({
+    id: "recursion_guard",
+    status: "pass",
+    message: `Recursion guard (AVORELO_HOOK_ACTIVE) is ${guardEnv ? "ACTIVE — would skip re-entry" : "inactive (normal — guard is active only when hook runs)."}`,
+    guardActive: !!guardEnv,
+  });
+
+  // Check 6: Rollback available
+  const latestApply = safeReadJson(path.join(cwd, LATEST_APPLY_REL));
+  const hasBackup = latestApply?.hostsApplied?.some((h) => h.backupPath);
+  checks.push({
+    id: "rollback_available",
+    status: hasBackup ? "pass" : "warn",
+    message: hasBackup
+      ? "Rollback available (backup exists from last apply)."
+      : "No backup found. Apply hooks first to enable rollback.",
+  });
+
+  // Check 7: No global config modification
+  checks.push({
+    id: "no_global_config_modified",
+    status: "pass",
+    message: "Hook apply only modifies repo-local config. Global config untouched.",
+  });
+
+  const failCount = checks.filter((c) => c.status === "fail").length;
+  const warnCount = checks.filter((c) => c.status === "warn").length;
+  const passCount = checks.filter((c) => c.status === "pass").length;
+
+  const doctorStatus = failCount > 0 ? "fail" : warnCount > 0 ? "warn" : "pass";
+
+  const nextAction = failCount > 0
+    ? checks.find((c) => c.status === "fail")?.message
+    : warnCount > 0
+      ? "Run `node bin/avorelo hooks apply --yes --json` to install hooks."
+      : "All checks pass. Lifecycle is live.";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: doctorStatus,
+    checks,
+    summary: { pass: passCount, warn: warnCount, fail: failCount },
+    nextAction,
+    rollbackAvailable: hasBackup || false,
+    hooksApplied: appliedHostCount > 0,
+    redacted: true,
+  };
+
+  safeWriteJson(receiptPath, receipt);
+  writeLedgerEntry(cwd, "hook_doctor", receipt);
+  return receipt;
+}
+
+// ── Receipt writer ────────────────────────────────────────────────────────────
+
+function writeHookApplyReceipt(cwd, receipt) {
+  safeWriteJson(path.join(cwd, LATEST_APPLY_REL), receipt);
+  return LATEST_APPLY_REL;
+}
+
+// ── Surface / text formatters ─────────────────────────────────────────────────
+
+function buildHookApplySurface(cwd, options = {}) {
+  const plan = buildHookApplyPlan(cwd, options);
+  const latestApply = safeReadJson(path.join(cwd, LATEST_APPLY_REL));
+  const latestDoctor = safeReadJson(path.join(cwd, LATEST_DOCTOR_REL));
+
+  return {
+    plan,
+    latestApply: latestApply || null,
+    latestDoctor: latestDoctor || null,
+    rollbackAvailable: !!(latestApply?.hostsApplied?.some((h) => h.backupPath)),
+  };
+}
+
+function formatHookApplyText(receipt, options = {}) {
+  const lines = [];
+
+  if (!receipt) {
+    lines.push("No hook apply receipt available. Run `node bin/avorelo hooks apply --dry-run --json`.");
+    return lines.join("\n");
+  }
+
+  lines.push(`Hook Apply  status=${receipt.status}`);
+
+  if (receipt.message) lines.push(`  ${receipt.message}`);
+
+  if (receipt.hostsApplied?.length) {
+    for (const h of receipt.hostsApplied) {
+      lines.push(`  Applied: ${h.host}  config=${h.configPath}  backup=${h.backupPath || "none"}`);
+    }
+  }
+  if (receipt.errors?.length) {
+    for (const e of receipt.errors) {
+      lines.push(`  Error: ${e.host}  ${e.error}`);
+    }
+  }
+  if (receipt.safeNextAction) {
+    lines.push(`  Next: ${receipt.safeNextAction}`);
+  }
+
+  return lines.join("\n");
+}
+
+function formatHookDoctorText(receipt, options = {}) {
+  const lines = [];
+
+  if (!receipt) {
+    lines.push("No doctor receipt. Run `node bin/avorelo hooks doctor --json`.");
+    return lines.join("\n");
+  }
+
+  lines.push(`Hook Doctor  status=${receipt.status}  pass=${receipt.summary?.pass}  warn=${receipt.summary?.warn}  fail=${receipt.summary?.fail}`);
+
+  if (options.debug) {
+    for (const c of receipt.checks || []) {
+      lines.push(`  [${c.status}] ${c.id}: ${c.message}`);
+    }
+  } else {
+    const problems = (receipt.checks || []).filter((c) => c.status !== "pass");
+    for (const c of problems) {
+      lines.push(`  [${c.status}] ${c.id}: ${c.message}`);
+    }
+  }
+
+  if (receipt.nextAction) lines.push(`  Next: ${receipt.nextAction}`);
+
+  return lines.join("\n");
+}
+
+// ── Ledger integration ────────────────────────────────────────────────────────
+
+function writeLedgerEntry(cwd, type, receipt) {
+  try {
+    const { appendProductLearningEvent } = require("./product-learning-events");
+    const eventName = {
+      hook_apply: "hook_config_applied",
+      hook_rollback: "hook_rollback_performed",
+      hook_uninstall: "hook_uninstall_performed",
+      hook_doctor: "hook_doctor_run",
+    }[type];
+
+    if (eventName) {
+      appendProductLearningEvent(cwd, {
+        eventName,
+        payload: {
+          type,
+          status: receipt.status,
+          hostsApplied: receipt.hostsApplied?.map((h) => h.host) || [],
+          rollbackAvailable: receipt.rollbackAvailable || false,
+        },
+      });
+    }
+  } catch {
+    // non-fatal
+  }
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_APPLY_REL,
+  LATEST_DOCTOR_REL,
+  LATEST_ROLLBACK_REL,
+  BACKUP_DIR_REL,
+  AVORELO_HOOK_MARKER,
+  AVORELO_LIFECYCLE_COMMANDS,
+  HOST_APPLY_CONFIGS,
+  // Core API
+  buildHookApplyPlan,
+  applyHookConfig,
+  validateAppliedHooks,
+  rollbackHookApply,
+  uninstallAvoreloHooks,
+  runHookDoctor,
+  writeHookApplyReceipt,
+  buildHookApplySurface,
+  // Formatters
+  formatHookApplyText,
+  formatHookDoctorText,
+  // Helpers (exported for testing)
+  isAvoreloManagedHook,
+  mergeClaudeCodeConfig,
+  mergeOpenHandsConfig,
+  removeAvoreloHooks,
+  backupConfig,
+  findLatestBackup,
+  parseExistingConfig,
+  requiresExplicitApproval,
+  isDryRun,
+};