auriga-cli 1.0.0 → 1.2.0

package/README.md

@@ -12,7 +12,9 @@ This repo itself is a fully configured harness project. You can clone it to see
 |---|---|
 | **Workflow** | `CLAUDE.md` development workflow: requirement clarification -> TDD -> Review, Harness principles, Subagent usage guide |
 | **Skills** | Development process skills — brainstorming, systematic-debugging, TDD, verification, planning, playwright |
-| **Plugins** | Recommended Claude Code plugins — skill-creator, claude-md-management, hookify, codex |
+| **Recommended Skills** | Optional utility skills (e.g. `ui-ux-pro-max`) you can add on top of the workflow skills |
+| **Plugins** | Recommended Claude Code plugins — skill-creator, claude-md-management, codex |
+| **Hooks** | Claude Code hooks (currently: `notify` — native macOS notification with brand icon + sound) |
 
 ## Quick Start
 
@@ -26,10 +28,12 @@ Interactive menu — select what to install:
 ? Select module types to install:
   ◉ Workflow — CLAUDE.md + AGENTS.md
   ◉ Skills — Development process skills
+  ◉ Recommended Skills — Extra utility skills
   ◉ Plugins — Claude Code plugins
+  ◉ Hooks — Claude Code hooks
 ```
 
-Each module supports scope selection (Skills: project/global, Plugins: user/project).
+Each module supports scope selection (Skills: project/global, Plugins: user/project, Hooks: project local / project / user).
 
 ## Module Details
 
@@ -64,13 +68,29 @@ Installs selected plugins via `claude plugins install`, automatically adding req
 |---|---|
 | skill-creator | Create and manage custom skills |
 | claude-md-management | Audit and improve CLAUDE.md |
-| hookify | Create hooks from conversation analysis |
 | codex | Codex cross-model collaboration |
 
+### Hooks
+
+Installs Claude Code hooks into a chosen scope. Each hook is self-contained under `.claude/hooks/<name>/` and can be customized without editing code.
+
+| Hook | Description |
+|---|---|
+| notify | Native macOS notification when Claude needs your attention. Shows the brand mark in the small app-icon position, with click-to-activate that brings the originating terminal back to the foreground. Auto-installs `alerter` via Homebrew (`vjeantet/tap/alerter`). Customize sound and icon by editing `.claude/hooks/notify/config.json` and replacing `.claude/hooks/notify/icon.png`. macOS-only at runtime; silent no-op on other platforms. |
+
+Scope choices:
+
+- **Project local** (recommended for cross-platform teams): files under `./.claude/hooks/`, registered in `./.claude/settings.local.json` — per-developer, not committed.
+- **Project**: same files, registered in `./.claude/settings.json` — shared with the team via git.
+- **User**: files under `~/.claude/hooks/`, registered in `~/.claude/settings.json` — global across all your projects.
+
+Re-running the installer preserves your customized `config.json` and `icon.png`, overwrites the runtime, and never produces duplicate hook entries (idempotent merge by sentinel marker).
+
 ## Requirements
 
 - Node.js >= 18
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (required for Plugins module)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (required for Plugins and Hooks modules)
+- [Homebrew](https://brew.sh) (recommended for the `notify` hook to install `alerter`)
 
 ## License
 

package/README.zh-CN.md

@@ -12,7 +12,9 @@
 |---|---|
 | **Workflow** | `CLAUDE.md` 开发工作流：需求澄清 → TDD → Review，Harness 原则，Subagent 使用指南 |
 | **Skills** | 开发流程 skills —— brainstorming、systematic-debugging、TDD、verification、planning、playwright |
-| **Plugins** | 推荐的 Claude Code 插件 —— skill-creator、claude-md-management、hookify、codex |
+| **Recommended Skills** | 可选的工具类 skills（如 `ui-ux-pro-max`），在 workflow skills 之外按需追加 |
+| **Plugins** | 推荐的 Claude Code 插件 —— skill-creator、claude-md-management、codex |
+| **Hooks** | Claude Code hooks（当前包含 `notify` —— 带品牌图标和提示音的原生 macOS 通知） |
 
 ## 快速开始
 
@@ -26,10 +28,12 @@ npx auriga-cli
 ? 选择要安装的模块类型：
   ◉ Workflow — CLAUDE.md + AGENTS.md
   ◉ Skills — 开发流程 skills
+  ◉ Recommended Skills — 额外的工具 skills
   ◉ Plugins — Claude Code 插件
+  ◉ Hooks — Claude Code hooks
 ```
 
-每个模块支持作用域选择（Skills: project/global，Plugins: user/project）。
+每个模块支持作用域选择（Skills: project/global，Plugins: user/project，Hooks: project local / project / user）。
 
 ## 模块详情
 
@@ -64,13 +68,29 @@ npx auriga-cli
 |---|---|
 | skill-creator | 创建和管理自定义 skills |
 | claude-md-management | 审计和改进 CLAUDE.md |
-| hookify | 从对话分析创建 hooks |
 | codex | Codex 跨模型协作 |
 
+### Hooks
+
+把 Claude Code hooks 安装到选定的作用域。每个 hook 都是 `.claude/hooks/<name>/` 下一个自包含目录，可以**不改代码**自定义。
+
+| Hook | 说明 |
+|---|---|
+| notify | 当 Claude 需要你关注时弹一条原生 macOS 通知。在通知小图标位显示品牌图，点击通知可把发起 Claude 的终端拉回前台。会自动通过 Homebrew 安装 `alerter`（`vjeantet/tap/alerter`）。改 `.claude/hooks/notify/config.json` 即可换提示音、替换 `.claude/hooks/notify/icon.png` 即可换图标。仅 macOS 运行时生效，其它平台静默 no-op。 |
+
+作用域选择：
+
+- **Project local**（推荐给跨平台团队）：文件落在 `./.claude/hooks/`，注册到 `./.claude/settings.local.json` —— 每个开发者各自安装，不进 git。
+- **Project**：同样的文件，注册到 `./.claude/settings.json` —— 整个团队共享。
+- **User**：文件落在 `~/.claude/hooks/`，注册到 `~/.claude/settings.json` —— 全局生效。
+
+重新跑安装器时会保留你修改过的 `config.json` 和 `icon.png`，覆盖运行时本身，并通过 marker 字段幂等去重，绝不会产生重复的 hook 条目。
+
 ## 环境要求
 
 - Node.js >= 18
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（Plugins 模块需要）
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（Plugins 和 Hooks 模块需要）
+- [Homebrew](https://brew.sh)（`notify` hook 用来安装 `alerter`，可选）
 
 ## License
 

package/dist/cli.js

@@ -5,6 +5,7 @@ import { fetchContentRoot, printBanner, withEsc } from "./utils.js";
 import { installWorkflow } from "./workflow.js";
 import { installSkills, installRecommendedSkills } from "./skills.js";
 import { installPlugins } from "./plugins.js";
+import { installHooks } from "./hooks.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 async function main() {
@@ -38,10 +39,15 @@ async function main() {
                 checked: true,
             },
             {
-                name: "Plugins — Claude Code plugins (skill-creator, hookify, codex...)",
+                name: "Plugins — Claude Code plugins (skill-creator, claude-md-management, codex...)",
                 value: "plugins",
                 checked: true,
             },
+            {
+                name: "Hooks — Claude Code hooks (notifications, etc.)",
+                value: "hooks",
+                checked: true,
+            },
         ],
     }));
     if (moduleTypes.length === 0) {
@@ -64,6 +70,10 @@ async function main() {
         console.log("\n--- Plugins ---\n");
         await installPlugins(packageRoot);
     }
+    if (moduleTypes.includes("hooks")) {
+        console.log("\n--- Hooks ---\n");
+        await installHooks(packageRoot);
+    }
     console.log("\n\u2728 Installation complete!\n");
 }
 main().catch((err) => {

package/dist/hooks.d.ts

@@ -0,0 +1,127 @@
+export interface HookDep {
+    name: string;
+    via: "brew";
+    optional?: boolean;
+}
+export interface HookSettingsEvent {
+    event: string;
+    matcher?: string;
+}
+export interface HookDef {
+    name: string;
+    description: string;
+    runtimePlatforms: string[];
+    settingsEvents: HookSettingsEvent[];
+    command: string;
+    files: string[];
+    preserveFiles?: string[];
+    deps?: HookDep[];
+    marker: string;
+    /**
+     * Per-hook customization hints rendered in the post-install summary.
+     * The literal `{hookDir}` is substituted with the hook's resolved
+     * install directory at print time. Empty / omitted → installer falls
+     * back to a generic "see <dir>/README.md" pointer.
+     */
+    customizeHints?: string[];
+}
+export interface HooksConfig {
+    hooks: HookDef[];
+}
+export interface SettingsHookAction {
+    type: "command";
+    command: string;
+    _marker?: string;
+}
+export interface SettingsHookGroup {
+    matcher?: string;
+    hooks: SettingsHookAction[];
+}
+export interface SettingsFile {
+    hooks?: Record<string, SettingsHookGroup[]>;
+    [key: string]: unknown;
+}
+/**
+ * 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.
+ *
+ * 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 declare function addHookToSettings(settings: SettingsFile, event: string, command: string, marker: string): {
+    settings: SettingsFile;
+    mutated: boolean;
+};
+/**
+ * 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 declare function removeHookFromSettings(settings: SettingsFile, marker: string): {
+    settings: SettingsFile;
+    removed: number;
+};
+type Scope = "project-local" | "project" | "user";
+export declare function depBinary(dep: HookDep): string;
+export declare function loadHooksConfig(packageRoot: string): HooksConfig;
+export interface InstallHookResult {
+    hook: string;
+    written: number;
+    preserved: number;
+    scope: Scope;
+    hookDir: string;
+    settingsPath: string;
+    settingsMutated: boolean;
+    settingsError?: string;
+    aborted?: string;
+}
+/**
+ * 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 declare function installHook(hook: HookDef, scope: Scope, projectBase: string, packageRoot: string): Promise<InstallHookResult>;
+/**
+ * Scan all 3 scope settings files for a hook's marker, returning every
+ * scope where the marker is currently present and is NOT the scope the
+ * caller is about to install into. Used by installHooks to detect
+ * cross-scope leftovers from a previous install — which would cause the
+ * hook to fire multiple times if not cleaned up.
+ *
+ * Pure-ish: reads files but does not mutate. Silently skips files that
+ * fail to parse — surfacing those errors is the install path's job.
+ */
+export interface StaleScope {
+    scope: Scope;
+    settingsPath: string;
+    count: number;
+}
+export declare function findStaleScopes(hook: HookDef, currentScope: Scope, projectBase: string): StaleScope[];
+/**
+ * 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 declare function cleanHookFromScope(hook: HookDef, scope: Scope, projectBase: string): {
+    removed: number;
+    settingsPath: string;
+};
+export declare function installHooks(packageRoot: string): Promise<void>;
+export {};

package/dist/hooks.js

@@ -0,0 +1,720 @@
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { checkbox, confirm, input, select } from "@inquirer/prompts";
+import { exec, fetchExtraContentBinary, log, withEsc, } from "./utils.js";
+// --- Registry validation ---
+// hooks.json is fetched at runtime from raw.githubusercontent.com, so any
+// downstream code that interpolates registry values into shell commands or
+// filesystem paths is one force-push away from RCE / arbitrary-file-write
+// for every user running `npx auriga-cli`. 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]+"$/;
+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)})`);
+        }
+    }
+    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`);
+            }
+        }
+    }
+}
+/**
+ * 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.
+ *
+ * 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) {
+    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) {
+                next.hooks[event] = list;
+                return { settings: next, mutated: false };
+            }
+            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 };
+            }
+        }
+    }
+    list.push({
+        hooks: [{ type: "command", command, _marker: marker }],
+    });
+    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}`,
+    };
+}
+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: in production, `packageRoot` is the temp dir created by
+ * `fetchContentRoot()` (utils.ts) — not the npm package install dir.
+ * Only `.claude/hooks/hooks.json` is preloaded by `CONTENT_FILES`; we
+ * fetch each hook's individual files on demand here so users who pick
+ * no hooks pay no network cost. 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);
+        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 };
+}
+/**
+ * Write `content` to `filePath` atomically and TOCTOU-safely.
+ *
+ * A predictable tmp name like `settings.json.tmp` lets a local attacker
+ * pre-create that path as a symlink pointing at, say, ~/.ssh/authorized_keys
+ * — the next install would then clobber the link target. Defenses: random
+ * suffix so the tmp name can't be predicted, plus O_CREAT|O_EXCL so we
+ * refuse to open the path at all if anything (file or symlink) exists
+ * there. Restrictive 0o600 perms in case the parent directory is
+ * world-writable. Final rename(2) is the atomic step.
+ */
+function atomicWriteFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    const suffix = crypto.randomBytes(8).toString("hex");
+    const tmp = path.join(dir, `.${base}.${suffix}.tmp`);
+    const fd = fs.openSync(tmp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+    try {
+        fs.writeSync(fd, content);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, filePath);
+}
+export function loadHooksConfig(packageRoot) {
+    const configPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
+    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 };
+}
+export async function installHooks(packageRoot) {
+    const config = loadHooksConfig(packageRoot);
+    const compatible = config.hooks.filter((h) => h.runtimePlatforms.includes(process.platform));
+    if (compatible.length === 0) {
+        log.warn(`No hooks available for your platform (${process.platform}). Skipping.`);
+        return;
+    }
+    const selected = await withEsc(checkbox({
+        message: "Select hooks to install:",
+        choices: compatible.map((h) => ({
+            name: `${h.name} — ${h.description}`,
+            value: h,
+            checked: true,
+        })),
+    }));
+    if (selected.length === 0) {
+        log.skip("No hooks selected");
+        return;
+    }
+    // Lazily prompted on the first project-scoped hook, then reused. Users
+    // who pick only "user" scope are never asked about a project directory.
+    let projectBaseResolved = null;
+    async function ensureProjectBase() {
+        if (projectBaseResolved !== null)
+            return projectBaseResolved;
+        const projectBase = await withEsc(input({
+            message: "Hooks install target directory:",
+            default: 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;
+    }
+    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 = await withEsc(select({
+            message: `Where to install the ${hook.name} hook?`,
+            choices: scopeChoices(),
+            default: "project-local",
+        }));
+        // 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.
+        if (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.
+        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 = await withEsc(confirm({
+                message: `Remove the stale registration so the hook only fires once?`,
+                default: 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}`);
+            continue;
+        }
+        if (result.aborted) {
+            log.error(`${hook.name} aborted: ${result.aborted}`);
+            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.`);
+        }
+        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.`);
+        }
+    }
+}

package/dist/utils.d.ts

@@ -32,6 +32,7 @@ export interface LangOption {
 export declare const LANGUAGES: LangOption[];
 export declare function fetchContentRoot(): Promise<string>;
 export declare function fetchExtraContent(tmpDir: string, file: string): Promise<void>;
+export declare function fetchExtraContentBinary(tmpDir: string, file: string): Promise<void>;
 export declare function withEsc<T>(prompt: Promise<T> & {
     cancel?: () => void;
 }): Promise<T>;

package/dist/utils.js

@@ -28,6 +28,7 @@ const CONTENT_FILES = [
     "CLAUDE.md",
     "skills-lock.json",
     ".claude/plugins.json",
+    ".claude/hooks/hooks.json",
 ];
 async function fetchFile(file) {
     const url = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${file}`;
@@ -36,6 +37,13 @@ async function fetchFile(file) {
         throw new Error(`Failed to fetch ${url}: ${res.status}`);
     return res.text();
 }
+async function fetchFileBinary(file) {
+    const url = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${file}`;
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Failed to fetch ${url}: ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
 export async function fetchContentRoot() {
     if (process.env.DEV === "1") {
         return getPackageRoot();
@@ -55,6 +63,12 @@ export async function fetchExtraContent(tmpDir, file) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.writeFileSync(dest, content);
 }
+export async function fetchExtraContentBinary(tmpDir, file) {
+    const buf = await fetchFileBinary(file);
+    const dest = path.join(tmpDir, file);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, buf);
+}
 // --- ESC support ---
 export function withEsc(prompt) {
     const onKeypress = (_, key) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "auriga-cli",
-  "version": "1.0.0",
-  "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Plugins)",
+  "version": "1.2.0",
+  "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "type": "module",
   "bin": {
     "auriga-cli": "dist/cli.js"
@@ -12,7 +12,9 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/cli.js"
+    "start": "node dist/cli.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test dist-test/tests/hooks.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch dist-test/tests/hooks.test.js"
   },
   "engines": {
     "node": ">=18"