avorelo 0.1.0 → 0.2.0

package/scripts/lib/hook-apply.js

@@ -1,1019 +0,0 @@
-"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
-const AVORELO_LIFECYCLE_COMMANDS = Object.freeze([
-  { event: "SessionStart", command: "node bin/avorelo lifecycle-hook session-start --json", blocking: false },
-  { event: "UserPromptSubmit", command: "node bin/avorelo lifecycle-hook user-prompt-submit --json", blocking: false },
-  { event: "PreToolUse", command: "node bin/avorelo lifecycle-hook pre-tool-use --json", blocking: true },
-  { event: "PostToolUse", command: "node bin/avorelo lifecycle-hook post-tool-use --json", blocking: false },
-  { event: "Stop", command: "node bin/avorelo lifecycle-hook stop --json", blocking: true },
-  { event: "SessionEnd", command: "node bin/avorelo lifecycle-hook session-end --json", blocking: false },
-]);
-
-// 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.
- * An entry is Avorelo-managed if its command matches one of our lifecycle commands.
- */
-function isAvoreloManagedHook(entry) {
-  if (!entry || typeof entry !== "object") return false;
-  // Check marker field
-  if (entry[AVORELO_HOOK_MARKER] === true) return true;
-  // Check command match
-  const cmd = entry.command || "";
-  return AVORELO_LIFECYCLE_COMMANDS.some((lc) => cmd.includes("lifecycle-hook"));
-}
-
-/**
- * Build the Avorelo hook entries for Claude Code settings.json format.
- * Each entry is tagged with _avorelo_managed for idempotent apply.
- */
-function buildClaudeCodeHookEntries() {
-  return AVORELO_LIFECYCLE_COMMANDS.map((lc) => ({
-    event: lc.event,
-    command: lc.command,
-    blocking: lc.blocking,
-    [AVORELO_HOOK_MARKER]: true,
-  }));
-}
-
-/**
- * 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 = Array.isArray(base.hooks) ? base.hooks : [];
-
-  // Remove old Avorelo-managed hooks
-  const userHooks = existingHooks.filter((h) => !isAvoreloManagedHook(h));
-
-  // Add new Avorelo hooks
-  const avoreloHooks = buildClaudeCodeHookEntries();
-
-  return {
-    ...base,
-    hooks: [...userHooks, ...avoreloHooks],
-  };
-}
-
-/**
- * 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 = Array.isArray(existingData.hooks) ? existingData.hooks : [];
-    return { ...existingData, hooks: hooks.filter((h) => !isAvoreloManagedHook(h)) };
-  }
-  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) {
-      const hooks = Array.isArray(parsed.data.hooks) ? parsed.data.hooks : [];
-      existingAvoreloHookCount = hooks.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 hooks = Array.isArray(data.hooks) ? data.hooks : [];
-    const avoreloHooks = hooks.filter(isAvoreloManagedHook);
-    const expectedCount = AVORELO_LIFECYCLE_COMMANDS.length;
-    const missingEvents = AVORELO_LIFECYCLE_COMMANDS
-      .filter((lc) => !avoreloHooks.some((h) => h.event === lc.event))
-      .map((lc) => lc.event);
-
-    const duplicates = AVORELO_LIFECYCLE_COMMANDS
-      .filter((lc) => avoreloHooks.filter((h) => h.event === lc.event).length > 1)
-      .map((lc) => lc.event);
-
-    validations.push({
-      host: hostKey,
-      status: avoreloHooks.length >= expectedCount && missingEvents.length === 0 ? "valid" : "incomplete",
-      configPath: hostConf.configPath,
-      avoreloHookCount: avoreloHooks.length,
-      expectedCount,
-      missingEvents,
-      duplicates,
-      userHookCount: hooks.length - avoreloHooks.length,
-    });
-  }
-
-  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 hooks = Array.isArray(data.hooks) ? data.hooks : [];
-    const avoreloHooks = hooks.filter(isAvoreloManagedHook);
-    const hasMissing = AVORELO_LIFECYCLE_COMMANDS.some((lc) => !avoreloHooks.some((h) => h.event === 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 === 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 = hooks.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: "PreToolUse blocks destructive commands." });
-    } else {
-      checks.push({ id: "pre_tool_use_blocks_destructive", status: "warn", message: "PreToolUse did not block destructive sample. 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,
-};