auriga-cli 1.25.0 → 1.27.0

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 {};