auriga-cli 1.25.0 → 1.26.0

package/dist/hooks.js

@@ -1,965 +0,0 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { checkbox, confirm, input, select } from "@inquirer/prompts";
-import { atomicWriteFile, exec, fetchExtraContentBinary, log, withEsc, } from "./utils.js";
-// --- Registry validation ---
-// The root hooks registry is legacy-only, but when present it may still be
-// loaded from runtime-fetched content. Any downstream code that interpolates
-// registry values into shell commands or filesystem paths is one bad config
-// away from RCE / arbitrary-file-write. Validate every untrusted value once at
-// load time, then trust it through the rest of the install flow.
-const HOOK_NAME_RE = /^[a-z][a-z0-9-]*$/;
-// Matches a flat brew formula name (`jq`, `pngquant`) OR a fully
-// qualified tap-prefixed name (`vjeantet/tap/alerter`) — up to 2
-// slashes separating segments. Each segment is the same charset as
-// the flat-name form. No shell metachars; safe to pass to `brew install`
-// as a single argv item.
-const DEP_NAME_RE = /^[a-z0-9][a-z0-9._+-]*(\/[a-z0-9][a-z0-9._+-]*){0,2}$/;
-const EVENT_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
-// Whitelist for hook command templates. The registry is fetched from raw
-// GitHub at runtime, and the command string is written verbatim into
-// settings.json then executed by Claude Code on every hook fire — so an
-// unconstrained string here is direct registry-RCE. We require:
-//   <runtime> "$HOOK_DIR/<flat-basename>.<ext>"
-// where runtime ∈ {node, python3, bash}, the path literal starts with
-// $HOOK_DIR/, the basename is a flat alphanumeric identifier (no slashes,
-// no dots — so no nested paths and no `..` traversal), the extension is
-// alphanumeric, and there are no trailing arguments. Anything else is
-// rejected at load time. Adding a runtime, allowing args, or relaxing
-// the form requires a code change here, intentionally — see the security
-// review trail in PR #7 for context.
-const COMMAND_RE = /^(node|python3|bash) "\$HOOK_DIR\/[A-Za-z0-9_-]+\.[A-Za-z0-9]+"$/;
-// Claude Code permission-rule syntax for the `if` field:
-//   <ToolName>(<substring>)
-// Tool name: EVENT_NAME-shape identifier, bounded to 64 chars so a
-// malicious registry can't inflate settings.json with a gigantic prefix.
-// Substring body: 1-200 printable-ASCII chars, with parens, backslash,
-// and backtick explicitly excluded so the anchored `\(...\)` wrapper
-// actually delimits a well-formed outer parenthesis pair.
-//
-// The safety argument is NOT that IF_RE strips shell metacharacters —
-// `$ " ' ; | & < > *` are all inside the allowed byte range and left
-// intact. The defense is that this string never reaches a shell: it's
-// written verbatim into settings.json as a JSON string and read by
-// Claude Code's in-process permission-rule matcher. A registry
-// compromise can widen or misdirect the match pattern (causing the hook
-// to fire on unintended inputs or not fire at all) but cannot pivot
-// into command execution from this field.
-//
-// Body range decomposition (what the char class actually covers):
-//   0x20-0x27  space through single-quote       (excludes nothing)
-//   0x2A-0x5B  asterisk through left-bracket    (excludes `(` 0x28, `)` 0x29)
-//   0x5D-0x5F  right-bracket through underscore (excludes `\` 0x5C)
-//   0x61-0x7E  lowercase through tilde          (excludes `` ` `` 0x60)
-const IF_RE = /^[A-Z][A-Za-z0-9_-]{0,63}\([\x20-\x27\x2A-\x5B\x5D-\x5F\x61-\x7E]{1,200}\)$/;
-function isSafeRelativePath(file) {
-    if (typeof file !== "string" || file.length === 0)
-        return false;
-    if (file.startsWith("/") || file.startsWith("\\"))
-        return false;
-    if (file.includes("\0"))
-        return false;
-    const normalized = path.posix.normalize(file);
-    if (normalized !== file)
-        return false;
-    if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../"))
-        return false;
-    return true;
-}
-function validateHookEntry(hook, idx) {
-    if (!hook || typeof hook !== "object") {
-        throw new Error(`hooks.json: hooks[${idx}] is not an object`);
-    }
-    const h = hook;
-    if (typeof h.name !== "string" || !HOOK_NAME_RE.test(h.name)) {
-        throw new Error(`hooks.json: hooks[${idx}].name must match ${HOOK_NAME_RE} (got ${JSON.stringify(h.name)})`);
-    }
-    if (!Array.isArray(h.files)) {
-        throw new Error(`hooks.json: hooks[${idx}].files must be an array`);
-    }
-    for (const f of h.files) {
-        if (!isSafeRelativePath(f)) {
-            throw new Error(`hooks.json: hooks[${idx}].files contains unsafe path ${JSON.stringify(f)}`);
-        }
-    }
-    if (h.preserveFiles !== undefined) {
-        if (!Array.isArray(h.preserveFiles)) {
-            throw new Error(`hooks.json: hooks[${idx}].preserveFiles must be an array`);
-        }
-        for (const f of h.preserveFiles) {
-            if (!isSafeRelativePath(f)) {
-                throw new Error(`hooks.json: hooks[${idx}].preserveFiles contains unsafe path ${JSON.stringify(f)}`);
-            }
-        }
-    }
-    if (h.deps !== undefined) {
-        if (!Array.isArray(h.deps)) {
-            throw new Error(`hooks.json: hooks[${idx}].deps must be an array`);
-        }
-        for (const d of h.deps) {
-            if (!d || typeof d !== "object") {
-                throw new Error(`hooks.json: hooks[${idx}].deps entry is not an object`);
-            }
-            const dn = d.name;
-            if (typeof dn !== "string" || !DEP_NAME_RE.test(dn)) {
-                throw new Error(`hooks.json: hooks[${idx}].deps name must match ${DEP_NAME_RE} (got ${JSON.stringify(dn)})`);
-            }
-        }
-    }
-    if (!Array.isArray(h.runtimePlatforms)) {
-        throw new Error(`hooks.json: hooks[${idx}].runtimePlatforms must be an array`);
-    }
-    if (!Array.isArray(h.settingsEvents)) {
-        throw new Error(`hooks.json: hooks[${idx}].settingsEvents must be an array`);
-    }
-    for (const evt of h.settingsEvents) {
-        if (!evt || typeof evt !== "object") {
-            throw new Error(`hooks.json: hooks[${idx}].settingsEvents entry is not an object`);
-        }
-        const en = evt.event;
-        if (typeof en !== "string" || !EVENT_NAME_RE.test(en)) {
-            throw new Error(`hooks.json: hooks[${idx}].settingsEvents.event must match ${EVENT_NAME_RE} (got ${JSON.stringify(en)})`);
-        }
-        const matcher = evt.matcher;
-        if (matcher !== undefined && (typeof matcher !== "string" || !EVENT_NAME_RE.test(matcher))) {
-            throw new Error(`hooks.json: hooks[${idx}].settingsEvents.matcher must match ${EVENT_NAME_RE} (got ${JSON.stringify(matcher)})`);
-        }
-        const ifRule = evt.if;
-        if (ifRule !== undefined && (typeof ifRule !== "string" || !IF_RE.test(ifRule))) {
-            throw new Error(`hooks.json: hooks[${idx}].settingsEvents.if must match ${IF_RE} (got ${JSON.stringify(ifRule)})`);
-        }
-    }
-    if (typeof h.command !== "string" || !COMMAND_RE.test(h.command)) {
-        throw new Error(`hooks.json: hooks[${idx}].command must match the safe template ${COMMAND_RE} (got ${JSON.stringify(h.command)})`);
-    }
-    if (typeof h.marker !== "string" || h.marker.length === 0) {
-        throw new Error(`hooks.json: hooks[${idx}].marker must be a non-empty string`);
-    }
-    if (h.customizeHints !== undefined) {
-        if (!Array.isArray(h.customizeHints)) {
-            throw new Error(`hooks.json: hooks[${idx}].customizeHints must be an array`);
-        }
-        for (const hint of h.customizeHints) {
-            if (typeof hint !== "string" || hint.length === 0 || hint.length > 200) {
-                throw new Error(`hooks.json: hooks[${idx}].customizeHints entries must be non-empty strings ≤200 chars`);
-            }
-        }
-    }
-    if (h.defaultOn !== undefined && typeof h.defaultOn !== "boolean") {
-        throw new Error(`hooks.json: hooks[${idx}].defaultOn must be a boolean`);
-    }
-}
-/**
- * Pure, idempotent settings merge. Deep-clones input, dedupes by two
- * checks in priority order:
- *
- *   1. sentinel `_marker` field — primary key. Survives path drift, lets
- *      a future uninstall command find our entries unambiguously.
- *   2. command-string equality — secondary, catches the case where the
- *      user (or another tool) already added an equivalent entry by hand
- *      and never wrote our marker. Without this fallback we would happily
- *      append a duplicate next to it and the hook would fire twice.
- *
- * `options.matcher` writes to the container-level `matcher` (tool-name
- * filter); `options.ifRule` writes to the action-level `if` (permission-
- * rule substring filter, Claude Code ≥ 2026-04). Either or both may be
- * absent.
- *
- * Upgrade path: if an entry with our marker already exists but its
- * matcher / if disagrees with the desired values, we update those two
- * fields in place (preserving everything else — command, sibling
- * actions, the user's other groups — untouched). This is the path for
- * a user who installed an older registry version and re-runs the
- * installer after hooks.json changed. Pure no-op when the existing
- * fields already match.
- *
- * Inputs are defense-in-depth revalidated here against IF_RE + the
- * event-name regex even though registry callers already passed
- * loadHooksConfig, so a direct library caller can't write malformed
- * values into settings.json by bypassing the registry loader.
- *
- * Throws if `settings.hooks[event]` exists but is not an array — that
- * means the user has hand-edited their settings into a shape we do not
- * recognize, and silently replacing it with an empty array would lose
- * data. Callers should catch and surface the error to the user.
- */
-export function addHookToSettings(settings, event, command, marker, options = {}) {
-    // Defense-in-depth: registry callers pre-validate via loadHooksConfig,
-    // but a direct programmatic caller could bypass that. Refuse values
-    // that wouldn't have cleared the registry validator, so settings.json
-    // can never receive a malformed string through this function.
-    if (options.matcher !== undefined && !EVENT_NAME_RE.test(options.matcher)) {
-        throw new Error(`addHookToSettings: options.matcher must match ${EVENT_NAME_RE} (got ${JSON.stringify(options.matcher)})`);
-    }
-    if (options.ifRule !== undefined && !IF_RE.test(options.ifRule)) {
-        throw new Error(`addHookToSettings: options.ifRule must match ${IF_RE} (got ${JSON.stringify(options.ifRule)})`);
-    }
-    const next = JSON.parse(JSON.stringify(settings ?? {}));
-    if (next.hooks !== undefined && (typeof next.hooks !== "object" || Array.isArray(next.hooks))) {
-        throw new Error(`settings.hooks exists but is not an object; refusing to clobber it`);
-    }
-    if (!next.hooks)
-        next.hooks = {};
-    const existing = next.hooks[event];
-    if (existing !== undefined && !Array.isArray(existing)) {
-        throw new Error(`settings.hooks.${event} exists but is not an array; refusing to clobber it`);
-    }
-    const list = existing ?? [];
-    for (const group of list) {
-        if (!group?.hooks || !Array.isArray(group.hooks))
-            continue;
-        for (const action of group.hooks) {
-            if (!action)
-                continue;
-            if (action._marker === marker) {
-                // Our entry already exists. Upgrade matcher / if in place if
-                // they drifted from the desired values; leave command + other
-                // fields alone (users may have hand-tweaked; we only own the
-                // two fields registry declares).
-                let drifted = false;
-                if (options.matcher !== undefined && group.matcher !== options.matcher) {
-                    group.matcher = options.matcher;
-                    drifted = true;
-                }
-                if (options.ifRule !== undefined && action.if !== options.ifRule) {
-                    action.if = options.ifRule;
-                    drifted = true;
-                }
-                next.hooks[event] = list;
-                return { settings: next, mutated: drifted };
-            }
-            if (action.type === "command" && action.command === command) {
-                // A pre-existing entry (manual or from another tool) already
-                // points at the same command. Coexist with it; do not add a
-                // duplicate. We deliberately do NOT stamp our marker onto someone
-                // else's entry — that would silently take ownership of it.
-                next.hooks[event] = list;
-                return { settings: next, mutated: false };
-            }
-        }
-    }
-    const action = { type: "command", command, _marker: marker };
-    if (options.ifRule !== undefined)
-        action.if = options.ifRule;
-    const group = { hooks: [action] };
-    if (options.matcher !== undefined)
-        group.matcher = options.matcher;
-    list.push(group);
-    next.hooks[event] = list;
-    return { settings: next, mutated: true };
-}
-/**
- * Pure inverse of addHookToSettings: removes every action carrying
- * `_marker` from every event in the settings tree. Returns the mutated
- * copy and the count of actions removed. If a group becomes empty after
- * removal, the whole group is dropped; if an event becomes empty, the
- * event key is dropped.
- */
-export function removeHookFromSettings(settings, marker) {
-    const next = JSON.parse(JSON.stringify(settings ?? {}));
-    if (!next.hooks || typeof next.hooks !== "object" || Array.isArray(next.hooks)) {
-        return { settings: next, removed: 0 };
-    }
-    let removed = 0;
-    for (const event of Object.keys(next.hooks)) {
-        const list = next.hooks[event];
-        if (!Array.isArray(list))
-            continue;
-        const newGroups = [];
-        for (const group of list) {
-            if (!group?.hooks || !Array.isArray(group.hooks)) {
-                newGroups.push(group);
-                continue;
-            }
-            const remainingActions = group.hooks.filter((action) => {
-                if (action && action._marker === marker) {
-                    removed++;
-                    return false;
-                }
-                return true;
-            });
-            if (remainingActions.length > 0) {
-                newGroups.push({ ...group, hooks: remainingActions });
-            }
-        }
-        if (newGroups.length > 0) {
-            next.hooks[event] = newGroups;
-        }
-        else {
-            delete next.hooks[event];
-        }
-    }
-    return { settings: next, removed };
-}
-const settingsBackedUp = new Set();
-function resolveScope(scope, projectBase, hookName) {
-    if (scope === "user") {
-        const home = os.homedir();
-        const dir = path.join(home, ".claude", "hooks", hookName);
-        return {
-            scope,
-            hookDir: dir,
-            settingsPath: path.join(home, ".claude", "settings.json"),
-            commandHookDir: dir,
-        };
-    }
-    const projectClaude = path.join(projectBase, ".claude");
-    return {
-        scope,
-        hookDir: path.join(projectClaude, "hooks", hookName),
-        settingsPath: scope === "project-local"
-            ? path.join(projectClaude, "settings.local.json")
-            : path.join(projectClaude, "settings.json"),
-        commandHookDir: `$CLAUDE_PROJECT_DIR/.claude/hooks/${hookName}`,
-    };
-}
-/**
- * Non-interactive scope map for hooks.
- *
- * Non-interactive surface only knows about two values — `project` (the
- * default) and `user`. `project-local` exists only in the TTY menu; it's
- * a per-developer uncommitted scope and carries enough "did you really
- * mean this?" surface area that we gate it behind an interactive
- * confirmation rather than exposing it as a CLI flag value.
- *
- * Exported so `tests/hooks.test.ts` can lock the contract down as a
- * unit test.
- */
-export function mapNonInteractiveScope(scope) {
-    return scope === "user" ? "user" : "project";
-}
-function scopeChoices() {
-    return [
-        {
-            name: "Project local — files in ./.claude/hooks/, settings in ./.claude/settings.local.json (per-developer, not committed)",
-            value: "project-local",
-        },
-        {
-            name: "Project — files in ./.claude/hooks/, settings in ./.claude/settings.json (committed, shared with team)",
-            value: "project",
-        },
-        {
-            name: "User — files in ~/.claude/hooks/, settings in ~/.claude/settings.json (global, all your projects)",
-            value: "user",
-        },
-    ];
-}
-// brew package names can be tap-prefixed (`vjeantet/tap/alerter`) but
-// the binary the formula installs into PATH is the bare formula name
-// (`alerter`). Strip the tap prefix to get the binary to `which` for.
-// Hook authors with a brew package whose binary name doesn't match the
-// formula name will need to ship a wrapper `bin` field in the future;
-// no such hook exists today.
-export function depBinary(dep) {
-    const segments = dep.name.split("/");
-    return segments[segments.length - 1];
-}
-function depReady(dep) {
-    try {
-        exec(`which ${depBinary(dep)}`);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function brewAvailable() {
-    try {
-        exec("which brew");
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function installDep(dep) {
-    // Defense-in-depth: the registry validator already enforced this regex,
-    // but re-check here so a future code path that constructs a HookDep
-    // outside the validator still can't shell-inject through this function.
-    if (!DEP_NAME_RE.test(dep.name)) {
-        log.error(`refusing to install dep with unsafe name: ${JSON.stringify(dep.name)}`);
-        return false;
-    }
-    console.log(`  Installing ${dep.name} via Homebrew (may prompt for password)...`);
-    // argv form, NOT shell-interpolated — registry compromise can't escape into a shell command.
-    const result = spawnSync("brew", ["install", dep.name], { stdio: "inherit" });
-    return result.status === 0;
-}
-/**
- * Pre-flight: ensure all deps are present (or gracefully degraded) before
- * touching any files. Returns false to hard-abort the hook install.
- */
-function preflightDeps(hook) {
-    for (const dep of hook.deps ?? []) {
-        if (depReady(dep)) {
-            log.ok(`${dep.name} ready`);
-            continue;
-        }
-        if (dep.via === "brew") {
-            if (brewAvailable()) {
-                if (installDep(dep)) {
-                    log.ok(`${dep.name} installed`);
-                    continue;
-                }
-                if (dep.optional) {
-                    log.warn(`${dep.name} install failed; runtime fallback will be used`);
-                    continue;
-                }
-                log.error(`${dep.name} install failed (required); aborting`);
-                return false;
-            }
-            if (dep.optional) {
-                log.warn(`Homebrew not found; ${dep.name} will be skipped. Runtime fallback will be used (no brand icon). Install brew at https://brew.sh and re-run for full features.`);
-                continue;
-            }
-            log.error(`Homebrew not found and ${dep.name} is required. Install brew at https://brew.sh, then re-run.`);
-            return false;
-        }
-    }
-    return true;
-}
-/**
- * Lazy-fetch a hook's payload files into `packageRoot` so they can be
- * copied from there into the user's target directory.
- *
- * IMPORTANT: this is retained for legacy root-hook installs. New hooks should
- * ship inside plugins instead. In production, `packageRoot` is the temp dir
- * created by `fetchContentRoot()` (utils.ts) — not the npm package install
- * dir. In DEV mode `packageRoot` is the live repo root, so the files are
- * already on disk and we skip the fetch.
- *
- * The hook payload list is owned by `hook.files` in `hooks.json`, which
- * loadHooksConfig already validated for path-traversal safety, so each
- * `file` here is a known-good relative path.
- */
-async function ensureHookFilesFetched(hook, packageRoot) {
-    if (process.env.DEV === "1")
-        return;
-    for (const file of hook.files) {
-        const repoPath = path.posix.join(".claude/hooks", hook.name, file);
-        const localPath = path.join(packageRoot, repoPath);
-        if (fs.existsSync(localPath))
-            continue;
-        await fetchExtraContentBinary(packageRoot, repoPath);
-    }
-}
-function copyHookFiles(hook, packageRoot, destDir) {
-    fs.mkdirSync(destDir, { recursive: true });
-    const preserve = new Set(hook.preserveFiles ?? []);
-    let written = 0;
-    let preserved = 0;
-    for (const file of hook.files) {
-        const dest = path.join(destDir, file);
-        if (preserve.has(file) && fs.existsSync(dest)) {
-            preserved++;
-            continue;
-        }
-        const src = path.join(packageRoot, ".claude", "hooks", hook.name, file);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.copyFileSync(src, dest);
-        written++;
-    }
-    return { written, preserved };
-}
-/**
- * Snapshot a settings file to `.bak` before the first mutation in this
- * session. The naive `copyFileSync(src, dst)` follows symlinks, which
- * would let a local attacker pre-symlink `settings.json.bak` at, say,
- * `~/.ssh/authorized_keys` and have us clobber the target on the next
- * install — same threat class as the tmp-file TOCTOU that
- * `atomicWriteFile` plugs. We use the same defense: read the source,
- * write to a fresh fd opened with O_CREAT|O_EXCL|O_WRONLY (refuses any
- * pre-existing path, including a symlink), then rely on the no-op-if-
- * already-backed-up-this-session guard for re-runs.
- *
- * If the .bak already exists from a previous session, leave it alone —
- * the FIRST backup is the one that captures the user's pre-auriga state,
- * which is what they care about restoring to.
- */
-function backupOnce(filePath) {
-    if (settingsBackedUp.has(filePath))
-        return;
-    settingsBackedUp.add(filePath);
-    if (!fs.existsSync(filePath))
-        return;
-    const bakPath = filePath + ".bak";
-    if (fs.existsSync(bakPath))
-        return;
-    const data = fs.readFileSync(filePath);
-    const fd = fs.openSync(bakPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
-    try {
-        fs.writeSync(fd, data);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-/**
- * Read and JSON.parse a settings file. Returns {} for missing file.
- * Throws on parse error so the caller can abort cleanly *before* any
- * file copy, instead of leaving orphan hook files in the target after a
- * mid-flight failure.
- */
-function readSettings(settingsPath) {
-    if (!fs.existsSync(settingsPath))
-        return {};
-    try {
-        return JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-    }
-    catch (e) {
-        throw new Error(`${settingsPath} is not valid JSON: ${e.message}`);
-    }
-}
-/**
- * Apply a hook's settingsEvents to an already-parsed settings object,
- * write the result atomically if anything changed. The caller MUST have
- * pre-validated the file via readSettings() before any file copy.
- */
-function writeMergedSettings(resolved, hook, parsed) {
-    let mutated = false;
-    let next = parsed;
-    for (const evt of hook.settingsEvents) {
-        const cmd = hook.command.replace(/\$HOOK_DIR/g, resolved.commandHookDir);
-        const result = addHookToSettings(next, evt.event, cmd, hook.marker, {
-            matcher: evt.matcher,
-            ifRule: evt.if,
-        });
-        if (result.mutated)
-            mutated = true;
-        next = result.settings;
-    }
-    if (mutated) {
-        backupOnce(resolved.settingsPath);
-        fs.mkdirSync(path.dirname(resolved.settingsPath), { recursive: true });
-        atomicWriteFile(resolved.settingsPath, JSON.stringify(next, null, 2) + "\n");
-    }
-    return { mutated };
-}
-export function loadHooksConfig(packageRoot) {
-    const configPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
-    if (!fs.existsSync(configPath))
-        return { hooks: [] };
-    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-    if (!raw || !Array.isArray(raw.hooks)) {
-        throw new Error(`${configPath} must have a "hooks" array at the top level`);
-    }
-    raw.hooks.forEach((h, i) => validateHookEntry(h, i));
-    return raw;
-}
-function relativeFromCwd(absPath) {
-    const rel = path.relative(process.cwd(), absPath);
-    return rel.startsWith("..") ? absPath : rel;
-}
-/**
- * Non-interactive single-hook install. Driven by installHooks (which
- * collects user choices via prompts) and by tools/verify-hooks.mjs (which
- * exercises the install path end-to-end without prompts).
- *
- * Failure ordering matters: deps run first (no state changes), then
- * settings is read AND parsed (still no state changes), and only after
- * parsing succeeds do we touch the filesystem to copy hook files. A
- * malformed settings file therefore aborts cleanly and leaves nothing
- * behind.
- */
-export async function installHook(hook, scope, projectBase, packageRoot) {
-    const resolved = resolveScope(scope, projectBase, hook.name);
-    const base = {
-        hook: hook.name,
-        written: 0,
-        preserved: 0,
-        scope,
-        hookDir: resolved.hookDir,
-        settingsPath: resolved.settingsPath,
-        settingsMutated: false,
-    };
-    if (!preflightDeps(hook)) {
-        return { ...base, aborted: "deps preflight failed" };
-    }
-    // Pre-validate settings BEFORE any filesystem writes. If the file is
-    // malformed we abort here, before copyHookFiles, so the caller never
-    // ends up with orphan hook files in the target.
-    let parsedSettings;
-    try {
-        parsedSettings = readSettings(resolved.settingsPath);
-    }
-    catch (e) {
-        return { ...base, aborted: e.message };
-    }
-    await ensureHookFilesFetched(hook, packageRoot);
-    const { written, preserved } = copyHookFiles(hook, packageRoot, resolved.hookDir);
-    let mutated = false;
-    let settingsError;
-    try {
-        mutated = writeMergedSettings(resolved, hook, parsedSettings).mutated;
-    }
-    catch (e) {
-        settingsError = e.message;
-    }
-    return {
-        ...base,
-        written,
-        preserved,
-        settingsMutated: mutated,
-        settingsError,
-    };
-}
-export function findStaleScopes(hook, currentScope, projectBase) {
-    const all = ["project-local", "project", "user"];
-    const stale = [];
-    for (const s of all) {
-        if (s === currentScope)
-            continue;
-        const r = resolveScope(s, projectBase, hook.name);
-        if (!fs.existsSync(r.settingsPath))
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(fs.readFileSync(r.settingsPath, "utf8"));
-        }
-        catch {
-            continue;
-        }
-        const removed = removeHookFromSettings(parsed, hook.marker).removed;
-        if (removed > 0) {
-            stale.push({ scope: s, settingsPath: r.settingsPath, count: removed });
-        }
-    }
-    return stale;
-}
-/**
- * Remove every action carrying `hook.marker` from the given scope's
- * settings file. Atomic write, snapshot-once .bak. Returns the count of
- * actions removed (0 if nothing matched or file did not exist).
- */
-export function cleanHookFromScope(hook, scope, projectBase) {
-    const r = resolveScope(scope, projectBase, hook.name);
-    if (!fs.existsSync(r.settingsPath)) {
-        return { removed: 0, settingsPath: r.settingsPath };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(r.settingsPath, "utf8"));
-    }
-    catch {
-        return { removed: 0, settingsPath: r.settingsPath };
-    }
-    const result = removeHookFromSettings(parsed, hook.marker);
-    if (result.removed > 0) {
-        backupOnce(r.settingsPath);
-        atomicWriteFile(r.settingsPath, JSON.stringify(result.settings, null, 2) + "\n");
-    }
-    return { removed: result.removed, settingsPath: r.settingsPath };
-}
-/**
- * Non-interactive selection resolver for hooks.
- *
- * Diverges from resolvePluginSelection in the no-filter case. Hooks can
- * carry intrusive side effects (OS notifications, brew deps), so the
- * safe default is NOT "install everything". Three cases:
- *
- * - undefined (no --hook passed) → default-on set (filter on defaultOn !== false)
- * - ["*"] (explicit opt-in to everything) → full compatible set
- * - explicit names → exactly those (even if defaultOn is false)
- */
-export function resolveHookSelection(compatible, selected) {
-    if (!selected)
-        return compatible.filter((h) => h.defaultOn !== false);
-    if (selected.length === 1 && selected[0] === "*")
-        return compatible;
-    const wanted = new Set(selected);
-    return compatible.filter((h) => wanted.has(h.name));
-}
-/**
- * Given the full registry and the platform-filtered compatible subset,
- * return the names in `selected` that refer to real hooks but aren't
- * available on the current platform. Empty result means the selection
- * is either fully compatible or references unknown hooks (that case is
- * left to the catalog validator — we don't pretend unknown names are
- * platform issues).
- */
-export function findIncompatibleExplicit(all, compatible, selected) {
-    const compatibleNames = new Set(compatible.map((h) => h.name));
-    const allNames = new Set(all.map((h) => h.name));
-    return selected.filter((n) => allNames.has(n) && !compatibleNames.has(n));
-}
-export async function installHooks(packageRoot, opts) {
-    const config = loadHooksConfig(packageRoot);
-    const compatible = config.hooks.filter((h) => h.runtimePlatforms.includes(process.platform));
-    if (compatible.length === 0) {
-        if (config.hooks.length === 0) {
-            log.warn("No legacy hooks are defined. The notify hook moved to the opt-in auriga-notify plugin.");
-        }
-        else {
-            log.warn(`No hooks available for your platform (${process.platform}). Skipping.`);
-        }
-        return;
-    }
-    // Non-interactive explicit `--hook <name>` has stronger intent than
-    // the default set: if the caller named a hook that isn't available
-    // on this platform, fail fast. A silent no-op would let CI pipelines
-    // report success with the intended hook missing.
-    if (!opts.interactive && opts.selected && opts.selected[0] !== "*") {
-        const missing = findIncompatibleExplicit(config.hooks, compatible, opts.selected);
-        if (missing.length > 0) {
-            throw new Error(`hook${missing.length > 1 ? "s" : ""} not available on ${process.platform}: ${missing.join(", ")}. Run \`npx -y auriga-cli install hooks --help\` to see platform compatibility.`);
-        }
-    }
-    const selected = opts.interactive
-        ? await withEsc(checkbox({
-            message: "Select hooks to install:",
-            choices: compatible.map((h) => ({
-                name: `${h.name} — ${h.description}`,
-                value: h,
-                checked: h.defaultOn !== false,
-            })),
-        }))
-        : resolveHookSelection(compatible, opts.selected);
-    // Surface any opt-in hooks skipped by the default set so the user
-    // isn't silently missing a hook they can see in --help / the README.
-    // Only fires on the non-interactive undefined-selection path (TTY
-    // checkbox already shows them unchecked).
-    if (!opts.interactive && opts.selected === undefined) {
-        const skippedOptIn = compatible.filter((h) => h.defaultOn === false);
-        for (const h of skippedOptIn) {
-            log.skip(`${h.name} (opt-in; re-run \`npx -y auriga-cli install hooks --hook ${h.name}\` to install)`);
-        }
-    }
-    if (selected.length === 0) {
-        log.skip("No hooks selected");
-        return;
-    }
-    // Non-interactive scope (two values only):
-    //   undefined / "project" → project (shared .claude/settings.json)
-    //   "user"                → user    (~/.claude/settings.json)
-    // project-local is reachable only via the TTY menu.
-    const nonInteractiveScope = mapNonInteractiveScope(opts.scope);
-    // Lazily prompted on the first project-scoped hook, then reused. Users
-    // who pick only "user" scope are never asked about a project directory.
-    //
-    // Non-interactive path always falls back to `process.cwd()` — the
-    // parser rejects `--cwd` for any non-workflow type (§3.5 rule 5), so
-    // reading `opts.cwd` here would just be dead dispatch.
-    let projectBaseResolved = null;
-    async function ensureProjectBase() {
-        if (projectBaseResolved !== null)
-            return projectBaseResolved;
-        const projectBase = opts.interactive
-            ? await withEsc(input({
-                message: "Hooks install target directory:",
-                default: process.cwd(),
-            }))
-            : process.cwd();
-        const resolvedPath = path.resolve(projectBase);
-        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isDirectory()) {
-            log.error(`Not a valid directory: ${resolvedPath}`);
-            return null;
-        }
-        projectBaseResolved = resolvedPath;
-        return projectBaseResolved;
-    }
-    const failures = [];
-    for (const hook of selected) {
-        console.log(`\n· ${hook.name}`);
-        // Per-hook scope is intentional (not a single upfront prompt like
-        // plugins.ts / skills.ts): a future user may want personal dev tools
-        // at user level and project-specific hooks at project level. The
-        // single-hook case is functionally identical to a single prompt.
-        const scope = opts.interactive
-            ? await withEsc(select({
-                message: `Where to install the ${hook.name} hook?`,
-                choices: scopeChoices(),
-                default: "project-local",
-            }))
-            : nonInteractiveScope;
-        // User scope mutates ~/.claude/settings.json — global, affects every
-        // project on this machine. A passive select label and a one-line warn
-        // both scroll past quickly. Make the user explicitly opt in to the
-        // global mutation; default to "no" so a missed Enter is the safe path.
-        // In non-interactive mode the caller has already expressed intent via
-        // `--scope user`, so we honor it without another confirmation gate.
-        if (opts.interactive && scope === "user") {
-            const proceed = await withEsc(confirm({
-                message: `Modify your global ~/.claude/settings.json? This affects every project on this machine. A .bak snapshot is taken before any change.`,
-                default: false,
-            }));
-            if (!proceed) {
-                log.skip(`${hook.name} skipped (user cancelled global install)`);
-                continue;
-            }
-        }
-        // Project scopes need a target directory; user scope does not.
-        let projectBaseForHook = "";
-        if (scope !== "user") {
-            const base = await ensureProjectBase();
-            if (base === null)
-                continue;
-            projectBaseForHook = base;
-        }
-        // Cross-scope cleanup: if this hook's marker is already present in a
-        // *different* scope's settings file, leaving it there means the hook
-        // will fire from both scopes. Detect, prompt, clean before installing.
-        // In non-interactive mode the default (remove stale) is applied
-        // silently — matches the interactive default: true.
-        const stale = findStaleScopes(hook, scope, projectBaseForHook);
-        for (const entry of stale) {
-            log.warn(`Found existing ${hook.name} hook in ${relativeFromCwd(entry.settingsPath)} (${entry.scope} scope, ${entry.count} entr${entry.count === 1 ? "y" : "ies"})`);
-            const remove = opts.interactive
-                ? await withEsc(confirm({
-                    message: `Remove the stale registration so the hook only fires once?`,
-                    default: true,
-                }))
-                : true;
-            if (remove) {
-                const cleaned = cleanHookFromScope(hook, entry.scope, projectBaseForHook);
-                log.ok(`removed ${cleaned.removed} from ${relativeFromCwd(cleaned.settingsPath)}`);
-            }
-            else {
-                // The user explicitly chose not to clean — make the consequence
-                // visible so it isn't a silent footgun. The hook will fire from
-                // BOTH scopes on every Notification event.
-                log.warn(`${hook.name} will fire from BOTH ${entry.scope} and ${scope} on every event. Run \`auriga-cli\` again or edit ${relativeFromCwd(entry.settingsPath)} to clean it up later.`);
-            }
-        }
-        let result;
-        try {
-            result = await installHook(hook, scope, projectBaseForHook, packageRoot);
-        }
-        catch (e) {
-            log.error(`${hook.name}: ${e.message}`);
-            failures.push(hook.name);
-            continue;
-        }
-        if (result.aborted) {
-            log.error(`${hook.name} aborted: ${result.aborted}`);
-            failures.push(hook.name);
-            continue;
-        }
-        const settingsRel = relativeFromCwd(result.settingsPath);
-        const dirRel = relativeFromCwd(result.hookDir);
-        const summary = result.preserved > 0
-            ? `${hook.name} hook installed at ${dirRel} (${result.written} written, ${result.preserved} preserved)`
-            : `${hook.name} hook installed at ${dirRel}`;
-        log.ok(summary);
-        if (result.settingsError) {
-            log.error(`${hook.name}: ${result.settingsError}`);
-            log.warn(`Files were copied to ${dirRel} but settings not updated. Add the hook entry manually if you want it active.`);
-            // Registration failure leaves the hook installed-but-inactive. Count
-            // it as a failure so non-interactive `install hooks` exits 2 and the
-            // caller can retry — quietly reporting success would ship a dead hook.
-            failures.push(hook.name);
-        }
-        else if (result.settingsMutated) {
-            log.ok(`registered in ${settingsRel}`);
-        }
-        else {
-            log.skip(`already registered in ${settingsRel}`);
-        }
-        // Per-hook customize tips, sourced from registry metadata so adding a
-        // new hook doesn't require touching the installer. `{hookDir}` is
-        // substituted with the resolved install directory.
-        const hints = hook.customizeHints ?? [];
-        if (hints.length > 0) {
-            console.log(`  Customize ${hook.name}:`);
-            for (const hint of hints) {
-                console.log(`    • ${hint.replace(/\{hookDir\}/g, dirRel)}`);
-            }
-        }
-        else {
-            console.log(`  See ${dirRel}/README.md for customization options.`);
-        }
-    }
-    if (failures.length > 0 && !opts.interactive) {
-        throw new Error(`${failures.length} hook(s) failed to install: ${failures.join(", ")}`);
-    }
-}
-// --- Uninstall ----------------------------------------------------------------
-const HOOK_NAME_RE_STRICT = /^[a-z][a-z0-9-]*$/;
-/**
- * Uninstall a single hook. Defaults to project scope; explicit
- * `scope:"user"` cleans `~/.claude/...` instead.
- *
- * Project scope (default):
- *   - rm `<cwd>/.claude/hooks/<name>/` directory.
- *   - Strip the hook's marker from `<cwd>/.claude/settings.json` AND
- *     `<cwd>/.claude/settings.local.json` (project + project-local share
- *     the on-disk hook dir, so cleaning both settings files keeps users
- *     who switched scopes from accumulating dangling registrations).
- *
- * User scope:
- *   - rm `~/.claude/hooks/<name>/` directory.
- *   - Strip the hook's marker from `~/.claude/settings.json`.
- *   - Project files are NOT touched.
- *
- * Marker discovery: tries the live registry at `<cwd>` (or the npx
- * package root if that fails) so we use the same marker the install path
- * stamped in. If the registry can't resolve the hook (renamed / removed
- * upstream), we fall back to a `auriga:<name>` convention — every shipped
- * hook to date follows it, so the fallback is reliable for the common
- * case.
- *
- * Idempotent: missing hook dir / missing settings / absent marker → no-op.
- */
-export async function uninstallHook(name, opts) {
-    if (!HOOK_NAME_RE_STRICT.test(name)) {
-        throw new Error(`uninstallHook: invalid hook name ${JSON.stringify(name)}`);
-    }
-    const cwd = path.resolve(opts.cwd);
-    const scope = opts.scope ?? "project";
-    const emit = (line) => { opts.onLog?.(line); };
-    // Look up marker from the registry. If the registry is absent or the
-    // hook isn't listed, fall back to `auriga:<name>` (the shipped naming
-    // convention for every hook in this repo).
-    let marker = `auriga:${name}`;
-    try {
-        const cfg = loadHooksConfig(cwd);
-        const def = cfg.hooks.find((h) => h.name === name);
-        if (def)
-            marker = def.marker;
-    }
-    catch {
-        // No registry at cwd — fine, fall back to the convention.
-    }
-    // Build a minimal HookDef stub for cleanHookFromScope. It only reads
-    // `marker` and `name` (via resolveScope), both of which we have.
-    const stub = {
-        name,
-        description: "",
-        runtimePlatforms: [],
-        settingsEvents: [],
-        command: 'node "$HOOK_DIR/index.mjs"',
-        files: [],
-        marker,
-    };
-    // resolveScope picks the settings/hooks paths based on scope.
-    // Project scope covers both project + project-local settings (shared
-    // on-disk hook dir); user scope covers only ~/.claude/settings.json.
-    const cleanScopes = scope === "user" ? ["user"] : ["project", "project-local"];
-    let totalRemoved = 0;
-    for (const s of cleanScopes) {
-        const r = cleanHookFromScope(stub, s, cwd);
-        if (r.removed > 0) {
-            totalRemoved += r.removed;
-            log.ok(`${name}: removed ${r.removed} entr${r.removed === 1 ? "y" : "ies"} from ${r.settingsPath}`);
-            emit(`removed ${r.removed} entr${r.removed === 1 ? "y" : "ies"} from ${r.settingsPath}`);
-        }
-    }
-    if (totalRemoved === 0) {
-        log.skip(`${name}: no settings entries found`);
-        emit(`${name}: no settings entries found`);
-    }
-    // Hook directory: user → ~/.claude/hooks/<name>; project → <cwd>/.claude/hooks/<name>.
-    const hookDir = scope === "user"
-        ? path.join(os.homedir(), ".claude", "hooks", name)
-        : path.join(cwd, ".claude", "hooks", name);
-    if (fs.existsSync(hookDir)) {
-        fs.rmSync(hookDir, { recursive: true, force: true });
-        log.ok(`${name}: directory removed`);
-        emit(`removed ${hookDir}`);
-    }
-    else {
-        log.skip(`${name}: directory not present`);
-        emit(`${name}: directory not present`);
-    }
-}