auriga-cli 1.24.0 → 1.26.0

package/dist/preset.js

@@ -0,0 +1,84 @@
+// src/preset.ts
+//
+// installPreset —— 「推荐预设安装」的单一编排入口。
+//
+// 预设由三部分组成,按下面的顺序安装:
+//   1. workflow 文档 (CLAUDE.md + AGENTS.md)
+//   2. 工作流 skill (WORKFLOW_SKILLS 全集 —— installSkills 自身已限定)
+//   3. auriga-workflow 插件
+//
+// CLI 的 `--preset`、TUI 的「推荐预设」、Web UI 的一键按钮全部走这一个
+// 函数,因此「预设由什么构成」只有这一处真相。
+//
+// installPreset 返回逐步成败摘要 (PresetStepResult[]):
+//   - CLI 用它计算分级退出码(全成功 0 / 部分或全部失败 2),与 runAll
+//     的 graded-exit 语义对齐;
+//   - TUI / Web UI 忽略该摘要 —— 各自走 log-and-continue / 流式进度。
+//
+// 三个 installer 经动态 import 引入而非静态 import:这样 preset.ts 是一个
+// 零重依赖的薄编排层 —— 只想读 PRESET_PLUGINS 常量的调用方(参数校验、
+// 帮助文案)不会被迫拉入 plugins.ts 这张大依赖图;installer 模块也只在
+// installPreset 真正被调用时才进入模块图。
+/**
+ * 预设安装的插件成员 —— 固定只装 auriga-workflow。
+ * installPlugins 的 `selected` 过滤把安装面收敛到这一个插件。
+ * `as const` 冻结这个「单一真相」常量,调用方无法 .push() 篡改它。
+ */
+export const PRESET_PLUGINS = ["auriga-workflow"];
+/** 预设的安装顺序:文档 → skill → 插件。 */
+const PRESET_STEPS = [
+    "workflow",
+    "skills",
+    "plugins",
+];
+/**
+ * 按 workflow → skills → plugins 顺序执行预设安装。
+ *
+ * 每一步独立 try/catch:一步失败不阻断后续步骤(与 runAll 的
+ * log-and-continue 一致),逐步成败汇总后返回给调用方。
+ */
+export async function installPreset(packageRoot, opts) {
+    const results = [];
+    for (const category of PRESET_STEPS) {
+        try {
+            await runPresetStep(category, packageRoot, opts);
+            results.push({ category, ok: true });
+        }
+        catch (e) {
+            results.push({ category, ok: false, err: e.message });
+        }
+    }
+    return results;
+}
+async function runPresetStep(category, packageRoot, opts) {
+    // scope / agent / lang 一并透传给每个 installer —— installer 各取所需
+    // (workflow 只用 lang/cwd,skills/plugins 只用 scope/agent),用不到的
+    // 字段被忽略。
+    const base = {
+        interactive: opts.interactive,
+        scope: opts.scope,
+        agent: opts.agent,
+        lang: opts.lang,
+        cwd: opts.cwd,
+        onLog: opts.onLog,
+    };
+    switch (category) {
+        case "workflow": {
+            const { installWorkflow } = await import("./workflow.js");
+            return installWorkflow(packageRoot, base);
+        }
+        case "skills": {
+            // installSkills 内部已把安装范围限定到 WORKFLOW_SKILLS 全集 ——
+            // 不传 selected 即安装这组工作流 skill,无需在此重复列举。
+            const { installSkills } = await import("./skills.js");
+            return installSkills(packageRoot, base);
+        }
+        case "plugins": {
+            const { installPlugins } = await import("./plugins.js");
+            return installPlugins(packageRoot, {
+                ...base,
+                selected: [...PRESET_PLUGINS],
+            });
+        }
+    }
+}

package/dist/scan-catalog.js

@@ -7,7 +7,7 @@ import { loadCatalog } from "./catalog.js";
 export async function buildScanCatalog(packageRoot) {
     const dist = loadCatalog(packageRoot);
     // v1.19.0 dropped update-available status. The scanner is now presence-
-    // only: skills / hooks / plugins / workflow all report installed iff their
+    // only: skills / plugins / workflow all report installed iff their
     // truth source exists, not-installed otherwise. No version / hash / event
     // comparison happens, so the build-time catalog is reduced to the bare
     // {description, agents?, external?} shape per entry.
@@ -35,9 +35,5 @@ export async function buildScanCatalog(packageRoot) {
             ...(entry.external === true ? { external: true } : {}),
         };
     }
-    const hooks = {};
-    for (const entry of dist.hooks) {
-        hooks[entry.name] = { description: entry.description };
-    }
-    return { skills, recommendedSkills, plugins, hooks };
+    return { skills, recommendedSkills, plugins };
 }

package/dist/server.d.ts

@@ -5,9 +5,12 @@ export interface ApplyHandlerOptions {
      *  translate into the per-installer flag (`--scope project|user`). The
      *  workflow handler ignores it (workflow has no scope concept). */
     scope?: "project" | "user";
-    /** Workflow CLAUDE.md language variant. Only meaningful for the workflow
-     *  handler; other handlers ignore it. Omitted = "en". */
+    /** Workflow CLAUDE.md language variant. Meaningful for the workflow and
+     *  preset handlers; other handlers ignore it. Omitted = "en". */
     lang?: "en" | "zh-CN";
+    /** Preset install runtime. Only meaningful for the preset handler;
+     *  other handlers ignore it. Omitted = "both". */
+    agent?: "claude" | "codex" | "both";
 }
 export type ApplyHandler = (action: ApplyAction, name: string, opts: ApplyHandlerOptions) => Promise<void>;
 export interface ApplyHandlers {
@@ -15,14 +18,14 @@ export interface ApplyHandlers {
     skill: ApplyHandler;
     "recommended-skill": ApplyHandler;
     plugin: ApplyHandler;
-    hook: ApplyHandler;
+    preset: ApplyHandler;
 }
 export interface ApplyCatalog {
     workflow: Set<string>;
     skill: Set<string>;
     "recommended-skill": Set<string>;
     plugin: Set<string>;
-    hook: Set<string>;
+    preset: Set<string>;
 }
 export interface StartServerOptions {
     port?: number;

package/dist/server.js

@@ -169,11 +169,12 @@ const VALID_CATEGORIES = new Set([
     "skill",
     "recommended-skill",
     "plugin",
-    "hook",
+    "preset",
 ]);
 const VALID_ACTIONS = new Set(["install", "uninstall"]);
 const VALID_SCOPES = new Set(["project", "user"]);
 const VALID_LANGS = new Set(["en", "zh-CN"]);
+const VALID_AGENTS = new Set(["claude", "codex", "both"]);
 function parseApplyRequest(raw) {
     let parsed;
     try {
@@ -190,7 +191,7 @@ function parseApplyRequest(raw) {
     for (const it of items) {
         if (!it || typeof it !== "object")
             return null;
-        const { category, name, action, scope, lang } = it;
+        const { category, name, action, scope, lang, agent } = it;
         if (typeof category !== "string" || !VALID_CATEGORIES.has(category)) {
             return null;
         }
@@ -207,12 +208,21 @@ function parseApplyRequest(raw) {
             if (category === "workflow")
                 return null;
         }
-        // Lang is optional and only meaningful for category="workflow". Any
-        // other pairing is a client bug and we reject loudly.
+        // Lang is optional and meaningful for category="workflow" and
+        // category="preset" (the preset installs the workflow doc). Any other
+        // pairing is a client bug and we reject loudly.
         if (lang !== undefined) {
             if (typeof lang !== "string" || !VALID_LANGS.has(lang))
                 return null;
-            if (category !== "workflow")
+            if (category !== "workflow" && category !== "preset")
+                return null;
+        }
+        // Agent is optional and only meaningful for category="preset" (the
+        // per-plugin agent is derived from the catalog, not client-supplied).
+        if (agent !== undefined) {
+            if (typeof agent !== "string" || !VALID_AGENTS.has(agent))
+                return null;
+            if (category !== "preset")
                 return null;
         }
     }
@@ -375,6 +385,7 @@ export async function startServer(opts) {
                         onLog: (line, level) => emit(job, { type: "item:log", index: i, line, level }),
                         scope: item.scope,
                         lang: item.lang,
+                        agent: item.agent,
                     });
                     emit(job, { type: "item:done", index: i, success: true });
                 }
@@ -752,7 +763,7 @@ function parseScopesParam(searchParams) {
     const raw = searchParams.get("scopes");
     if (!raw)
         return null;
-    const allowedCategories = new Set(["workflow", "skills", "plugins", "hooks"]);
+    const allowedCategories = new Set(["workflow", "skills", "plugins"]);
     const allowedScopes = new Set(["user", "project"]);
     const out = {};
     for (const pair of raw.split(",")) {
@@ -801,5 +812,5 @@ const defaultHandlersNotConfigured = {
     skill: handlerNotConfigured,
     "recommended-skill": handlerNotConfigured,
     plugin: handlerNotConfigured,
-    hook: handlerNotConfigured,
+    preset: handlerNotConfigured,
 };

package/dist/state.d.ts

@@ -18,9 +18,6 @@ export interface Catalog {
          *  reporting; that surface was removed). */
         external?: boolean;
     }>;
-    hooks: Record<string, {
-        description: string;
-    }>;
 }
 export interface ScanOptions {
     /** Run `claude plugins list` for the given scope. The scope argument is
@@ -37,13 +34,11 @@ export interface ScanOptions {
     readCodexPluginsDir?: () => Promise<Map<string, string>>;
     /** Per-category scope picker. Each field is independently routed to the
      *  right truth source. Defaults match the Web UI's per-column picker:
-     *    workflow = 'project', skills = 'project',
-     *    plugins  = 'user',    hooks  = 'user'. */
+     *    workflow = 'project', skills = 'project', plugins = 'user'. */
     scopes?: {
         workflow?: ScanScope;
         skills?: ScanScope;
         plugins?: ScanScope;
-        hooks?: ScanScope;
     };
     /** Test-time HOME override. When unset the scanner reads os.homedir()
      *  (which itself consults process.env.HOME / USERPROFILE), so tests that

package/dist/state.js

@@ -8,7 +8,6 @@
 //              <proj>/.claude/skills/<name>/SKILL.md        (project scope)
 //   Plugins(Claude): execPluginList(scope) + settings.json enabledPlugins
 //   Plugins(Codex):  ~/.codex/config.toml + ~/.codex/plugins/cache (user only)
-//   Hooks:     <scope>/.claude/settings.json `hooks` segment, matched by _marker
 //
 // Scanner is presence-only: states are `installed` / `not-installed` /
 // `partial-install` (dual-Agent half-install). v1.19.0 dropped
@@ -46,7 +45,6 @@ const DEFAULT_SCOPES = {
     workflow: "project",
     skills: "project",
     plugins: "user",
-    hooks: "user",
 };
 export async function scanState(projectRoot, catalog, opts = {}) {
     const warnings = [];
@@ -56,7 +54,6 @@ export async function scanState(projectRoot, catalog, opts = {}) {
     const skills = scanSkills(scopes.skills, projectRoot, home, catalog.skills, 
     /* recommended */ false, warnings);
     const recommendedSkills = scanRecommendedSkills(scopes.skills, projectRoot, home, catalog.recommendedSkills, warnings);
-    const hooks = scanHooks(scopes.hooks, projectRoot, home, catalog.hooks, warnings);
     const claudePluginEntries = filterPluginsByAgent(catalog.plugins, "claude");
     const codexPluginEntries = filterPluginsByAgent(catalog.plugins, "codex");
     const claudePlugins = await scanClaudePlugins(scopes.plugins, claudePluginEntries, opts.execPluginList, warnings);
@@ -79,7 +76,6 @@ export async function scanState(projectRoot, catalog, opts = {}) {
         skills,
         recommendedSkills,
         plugins: mergePluginsById([...claudePlugins, ...codexPlugins]),
-        hooks,
         warnings,
     };
 }
@@ -462,106 +458,6 @@ function parseCodexEnabledPluginIds(tomlContent) {
     return ids;
 }
 // ---------------------------------------------------------------------------
-// Hooks — read from <scope>/.claude/settings.json `hooks` segment, matched by
-// `_marker` sentinel against catalog hook names. Settings.json shape (Claude
-// Code convention):
-//
-//   {
-//     "hooks": {
-//       "<EventName>": [
-//         {
-//           "matcher": "<pattern>",
-//           "if": "<optional Claude-Code filter>",
-//           "hooks": [
-//             { "type": "command", "command": "...", "_marker": "<name>" }
-//           ]
-//         }
-//       ]
-//     }
-//   }
-//
-// ---------------------------------------------------------------------------
-function settingsPathForScope(scope, projectRoot, home) {
-    if (scope === "user")
-        return path.join(home, ".claude", "settings.json");
-    return path.join(projectRoot, ".claude", "settings.json");
-}
-/** Returns the set of `_marker` sentinel values present in the settings
- *  `hooks` segment. Malformed sub-shapes are skipped silently. v1.19.0
- *  reduced this from a full {event, matcher, if, command} record (used for
- *  drift detection) to a presence-only Set — re-install is the update
- *  path now, so the scanner doesn't need to compare entry shapes. */
-function indexSettingsMarkers(settings) {
-    const out = new Set();
-    if (!settings || typeof settings !== "object" || Array.isArray(settings))
-        return out;
-    const hooksSeg = settings.hooks;
-    if (!hooksSeg || typeof hooksSeg !== "object" || Array.isArray(hooksSeg))
-        return out;
-    for (const blocks of Object.values(hooksSeg)) {
-        if (!Array.isArray(blocks))
-            continue;
-        for (const block of blocks) {
-            if (!block || typeof block !== "object" || Array.isArray(block))
-                continue;
-            const actions = block.hooks;
-            if (!Array.isArray(actions))
-                continue;
-            for (const action of actions) {
-                if (!action || typeof action !== "object" || Array.isArray(action))
-                    continue;
-                const marker = action._marker;
-                if (typeof marker === "string")
-                    out.add(marker);
-            }
-        }
-    }
-    return out;
-}
-function scanHooks(scope, projectRoot, home, catalogHooks, warnings) {
-    const settingsPath = settingsPathForScope(scope, projectRoot, home);
-    let settingsRaw = null;
-    let settingsErr = null;
-    try {
-        settingsRaw = fs.readFileSync(settingsPath, "utf8");
-    }
-    catch (err) {
-        if (err && err.code === "ENOENT") {
-            settingsErr = "absent";
-        }
-        else {
-            settingsErr = "unreadable";
-        }
-    }
-    let parsed = null;
-    if (settingsRaw !== null) {
-        try {
-            parsed = JSON.parse(settingsRaw);
-        }
-        catch {
-            settingsErr = "unreadable";
-            parsed = null;
-        }
-    }
-    if (settingsErr === "unreadable") {
-        warnings.push({
-            code: "settings-unreadable",
-            message: `Settings file unreadable or corrupt JSON: ${settingsPath}`,
-        });
-    }
-    const markers = indexSettingsMarkers(parsed);
-    const out = [];
-    for (const [name, def] of Object.entries(catalogHooks)) {
-        out.push({
-            name,
-            description: def.description,
-            status: markers.has(name) ? "installed" : "not-installed",
-            observedScope: scope,
-        });
-    }
-    return out;
-}
-// ---------------------------------------------------------------------------
 // Default external-I/O implementations (used when ScanOptions are not
 // injected — server.ts wires these up in production).
 // ---------------------------------------------------------------------------

package/dist/types.d.ts

@@ -4,5 +4,5 @@
  * forcing leaf renderers (help.ts, guide.ts) to depend on the CLI
  * entrypoint just to pull one union.
  */
-export type CategoryName = "workflow" | "skills" | "recommended" | "plugins" | "hooks";
+export type CategoryName = "workflow" | "skills" | "recommended" | "plugins";
 export declare const CATEGORY_NAMES: readonly CategoryName[];

package/dist/types.js

@@ -9,5 +9,4 @@ export const CATEGORY_NAMES = [
     "skills",
     "recommended",
     "plugins",
-    "hooks",
 ];

package/dist/utils.d.ts

@@ -33,10 +33,16 @@ export interface InstallOpts {
     lang?: string;
     /** workflow only — install target directory (absolute or cwd-relative). */
     cwd?: string;
-    /** skills / recommended / plugins / hooks — `"user"` means install globally. */
+    /** skills / recommended / plugins — `"user"` means install globally. */
     scope?: "project" | "user";
     /** plugins only — runtime to install plugins for. Defaults to Claude Code. */
     agent?: PluginAgent;
+    /**
+     * plugins only — plugin names to drop from the interactive selection
+     * list. The TUI's「其他插件」item sets this to `["auriga-workflow"]`
+     * so the plugin already covered by the preset isn't offered twice.
+     */
+    excludePlugins?: string[];
     /**
      * sub-item filter. `undefined` = full set of this category.
      * Names are validated against the catalog by the CLI layer; installers

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "auriga-cli",
-  "version": "1.24.0",
-  "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
+  "version": "1.26.0",
+  "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,8 +25,8 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "pretest": "npm run build",
-    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
-    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
     "pretest:e2e": "npm run build",
     "test:e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/e2e-install.test.js",
     "pretest:web-ui-e2e": "npm run build && npm --prefix ui ci && npm --prefix ui run build",

package/dist/hooks.d.ts

@@ -1,236 +0,0 @@
-import { type InstallOpts } from "./utils.js";
-export interface HookDep {
-    name: string;
-    via: "brew";
-    optional?: boolean;
-}
-export interface HookSettingsEvent {
-    event: string;
-    /** Tool-name / regex filter; mapped onto the container-level
-     *  `matcher` field in settings.json. Absent → every tool fires. */
-    matcher?: string;
-    /** Permission-rule-syntax filter — mapped onto the nested action-level
-     *  `if` field in settings.json. Format: `<ToolName>(<substring>)`, e.g.
-     *  `Bash(gh pr create)` — see IF_RE for the exact grammar. Lets the
-     *  Claude Code runtime skip hook dispatch when the tool input doesn't
-     *  match, avoiding a Node subprocess spawn per unrelated call.
-     *  Absent → no registry-level content filter (the hook script runs
-     *  for every invocation that passed `matcher`). */
-    if?: 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[];
-    /**
-     * Whether the hook is part of the default-on set. `false` makes the
-     * hook opt-in: non-interactive `install hooks` with no `--hook` filter
-     * skips it, and the interactive checkbox leaves it unchecked. Absent
-     * / `true` → installed by default. Used for hooks with intrusive
-     * side effects (OS notifications, brew deps, platform constraints)
-     * that users probably want to pick up consciously.
-     */
-    defaultOn?: boolean;
-}
-export interface HooksConfig {
-    hooks: HookDef[];
-}
-export interface SettingsHookAction {
-    type: "command";
-    command: string;
-    _marker?: string;
-    /** Per-action permission-rule filter (Claude Code ≥ 2026-04 schema).
-     *  Format: `<ToolName>(<substring>)`. Older runtimes ignore unknown
-     *  fields, so emitting this is forward-safe. */
-    if?: 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.
- *
- * `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 declare function addHookToSettings(settings: SettingsFile, event: string, command: string, marker: string, options?: {
-    matcher?: string;
-    ifRule?: 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";
-/**
- * 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 declare function mapNonInteractiveScope(scope: string | undefined): Scope;
-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;
-};
-/**
- * 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 declare function resolveHookSelection(compatible: HookDef[], selected: string[] | undefined): HookDef[];
-/**
- * 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 declare function findIncompatibleExplicit(all: HookDef[], compatible: HookDef[], selected: string[]): string[];
-export declare function installHooks(packageRoot: string, opts: InstallOpts): Promise<void>;
-/**
- * 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 declare function uninstallHook(name: string, opts: {
-    cwd: string;
-    scope?: "project" | "user";
-    onLog?: (line: string) => void;
-}): Promise<void>;
-export {};