@raidiant/notifai 10.1.7 → 11.0.2

package/dist/install-hooks.d.ts

@@ -3,14 +3,20 @@ import { type HookInstallableHarness } from './harnesses.js';
 /**
  * Harness hook installation.
  *
+ * Notifai owns exactly one lifecycle mechanism per harness, in the current
+ * User's account and that harness's active home. There is no second install
+ * scope: whether Notifai activates in a Project is Project Enablement's
+ * question, and Project-scoped hook files are read only as migration evidence
+ * to remove.
+ *
  * Claude Code's `settings.json` and Codex's hook files use the same shape —
  * `hooks` maps an event name to matcher groups, each holding command handlers
  * with an optional timeout — so one generator serves both. Only the file
  * location and the event set differ. Codex supports either a dedicated
- * `hooks.json` or inline `[hooks]` tables in the same layer's `config.toml`.
- * We default a hook-empty layer to inline config and preserve whichever single
- * representation a populated layer already uses. Notifai lives in one of them,
- * never both.
+ * `hooks.json` or inline `[hooks]` tables in the same layer's `config.toml`;
+ * Notifai preserves whichever one already owns its approved handlers. A fresh
+ * install writes `hooks.json`, except when the User's own hooks already live
+ * inline. Notifai lives in one of them, never both.
  *
  * Cursor's native format is flat and lower-camel-cased, while OpenCode's
  * extension point is a JavaScript plugin module. Each therefore has a bounded
@@ -22,20 +28,17 @@ export interface HookHandler {
     timeout?: number;
     async?: boolean;
     statusMessage?: string;
+    /**
+     * Codex-only. Approximate token threshold for spilling `additionalContext`.
+     * Unset uses Codex's 2,500-token default; `0` passes the full context.
+     */
+    additionalContextLimit?: number;
 }
 export interface HookGroup {
     matcher?: string;
     hooks: HookHandler[];
 }
 export type HookConfig = Record<string, HookGroup[]>;
-export interface InstallPlan {
-    harness: HookInstallableHarness;
-    /** Absolute path of the settings file that will be written. */
-    file: string;
-    /** True when the file is machine-wide rather than per-project. */
-    global: boolean;
-    config: HookConfig;
-}
 export interface HookCommandOptions {
     platform?: NodeJS.Platform | HookHostPlatform;
     /** Registered Node used to interpret the Windows adapter. Ignored on POSIX. */
@@ -111,11 +114,20 @@ interface CursorSettingsDocument {
 /** Cursor's native schema is flat and uses lower-camel lifecycle event names. */
 export declare function buildCursorHookConfig(options: BuildOptions): CursorHookConfig;
 /**
- * Where each harness reads hooks from. Project installs deliberately target the
- * gitignored file where one exists: which devices a person wants their
- * questions pushed to is not a property of the repository.
+ * The one file each harness reads Notifai's lifecycle wiring from: the current
+ * User's account, in that harness's active home.
+ */
+export declare function settingsFile(harness: HookInstallableHarness, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string;
+/**
+ * Files an older build may have left inside this Project, which Notifai now
+ * only ever reads in order to remove.
+ *
+ * Nothing installs here any more. Every path is still enumerated because a
+ * leftover Project-scoped handler keeps firing beside the Machine one, and
+ * silently leaving it would be exactly the duplicate-routing defect dropping
+ * the second scope was meant to end.
  */
-export declare function settingsFile(harness: HookInstallableHarness, global: boolean, cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string;
+export declare function legacyProjectHookFiles(harness: HookInstallableHarness, cwd: string): string[];
 /**
  * The account home harness config roots are resolved against.
  *
@@ -139,21 +151,6 @@ export declare function harnessAccountHome(env?: NodeJS.ProcessEnv, platform?: N
  * `.claude/settings.local.json` — so this deliberately applies to Codex only.
  */
 export declare function codexProjectRoot(cwd: string): string;
-/**
- * The `.codex` directory that has to exist for Codex to load project hooks at
- * all, or null when nothing extra is needed.
- *
- * Codex splits the two halves of "which project am I in": it discovers the
- * project layer by walking up from cwd for a `.codex` directory, but resolves
- * the hook file inside that layer against the main repository. In an ordinary
- * checkout both land on the same directory and the split is invisible. In a
- * worktree they diverge, and writing only the main repository's file leaves it
- * unread — Codex never looks, because nothing at or above cwd told it there was
- * a project layer to load. Proven 2026-08-03: with cwd in a worktree, an *empty*
- * `.codex` directory there was the difference between the main repository's
- * handler running and nothing running.
- */
-export declare function codexLayerDir(cwd: string): string | null;
 /**
  * Harness-specific home variables relocate the whole active harness home.
  * This matters under session managers that give each Codex account its own
@@ -180,8 +177,17 @@ export interface CodexLayerPaths {
     hooksJson: string;
     configToml: string;
 }
-/** The two files Codex will look at for one config layer. */
-export declare function codexLayerPaths(global: boolean, cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): CodexLayerPaths;
+/** The two files Codex will look at in the Machine layer Notifai installs into. */
+export declare function codexMachineLayerPaths(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): CodexLayerPaths;
+/**
+ * Project layers an older build may have written into, for removal only.
+ *
+ * Codex resolves a project hook file against the main repository, so a linked
+ * worktree has two candidate directories: the main checkout's `.codex`, which
+ * Codex reads, and the worktree's own, which older builds sometimes created and
+ * Codex never reads. Both are legacy residue and both are enumerated here.
+ */
+export declare function codexLegacyProjectLayers(cwd: string): CodexLayerPaths[];
 export interface CodexLayerInspection {
     paths: CodexLayerPaths;
     /** Every event this file defines a handler for, whoever owns it. */
@@ -190,23 +196,27 @@ export interface CodexLayerInspection {
     /** The subset of those events whose handlers are Notifai's own. */
     ourJsonEvents: string[];
     ourTomlEvents: string[];
+    /** Whether `config.toml` holds at least one hook handler Notifai does not own. */
+    foreignTomlHooks: boolean;
     writeTarget: string;
 }
 /**
- * Where Notifai writes in this Codex layer: wherever Notifai already is, then
- * whichever single hook representation the layer already uses, and inline
- * `config.toml` for a hook-empty or already-mixed layer.
+ * Where Notifai writes in this Codex layer. An existing single Notifai
+ * representation is stable: upgrades refresh it in place because Codex keys
+ * approval by both handler identity and source path. Only a fresh installation
+ * chooses between `hooks.json` and inline `config.toml`.
  *
- * Codex supports `hooks.json` and inline `[hooks]` side by side, loads both,
- * and runs every matching handler. Reusing the one populated representation is
- * the generic layer contract: it avoids creating Codex's dual-representation
- * warning and, for a managed layer, writes through the same authority that
- * persists the layer rather than a sibling file it may regenerate away.
+ * `config.toml` is the User's whole Codex configuration and Codex rewrites it
+ * itself for `[hooks.state]`; keeping Notifai out of it bounds the blast radius
+ * to hooks, removes a second writer racing those trust records, and replaces
+ * TOML splicing with the same JSON merge Claude Code uses. Joining an inline
+ * layer that already has the User's handlers is the one exception, and it
+ * exists only so Codex never prints its dual-representation warning.
  *
- * Staying put where Notifai already is also keeps reinstalls idempotent and
- * preserves the `[hooks.state]` trust hash, which Codex keys by file path and
- * handler index. `[hooks.state]` is the trust store, not a hook definition, so
- * it does not count as a representation.
+ * A fresh installation uses `hooks.json` unless foreign inline handlers make
+ * `config.toml` the layer's established representation. `[hooks.state]` is the
+ * trust store rather than a hook definition, so it never counts as a
+ * representation and is preserved through every write.
  */
 export declare function inspectCodexLayer(paths: CodexLayerPaths): CodexLayerInspection;
 /**
@@ -214,10 +224,10 @@ export declare function inspectCodexLayer(paths: CodexLayerPaths): CodexLayerIns
  * layer, then inspect that layer only after acquiring the shared anchor.
  */
 export declare function withCodexLayerTransaction<T>(paths: CodexLayerPaths, action: (inspection: CodexLayerInspection) => T): T;
-/** Every file in this layer Codex might already be reading hooks from. */
-export declare function hookDefinitionFiles(harness: HookInstallableHarness, global: boolean, cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
+/** Every Machine-layer file this harness might already be reading hooks from. */
+export declare function machineHookFiles(harness: HookInstallableHarness, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
 /**
- * Layers where *Notifai* is installed in both Codex representations.
+ * The Machine layer with *Notifai* installed in both Codex representations.
  *
  * A layer that uses `hooks.json` and inline `[hooks]` at once is not by itself
  * a Notifai fault: Codex supports both, loads both, runs every matching
@@ -233,9 +243,10 @@ export declare function hookDefinitionFiles(harness: HookInstallableHarness, glo
  * the other one. Uninstall strips Notifai from both files, so the remedy is
  * exact — and it never touches a foreign handler.
  */
-export declare function codexRepresentationProblems(cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
+export declare function codexRepresentationProblems(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
 /**
- * Layers where Notifai and someone else each own one Codex representation.
+ * The Machine layer where Notifai and someone else each own one Codex
+ * representation.
  *
  * This is not a fault and never fails a check. Codex loads `hooks.json` and
  * inline `[hooks]` together and runs every matching handler, so both sets fire
@@ -244,7 +255,7 @@ export declare function codexRepresentationProblems(cwd: string, env?: NodeJS.Pr
  * Notifai's, which is not, and that Notifai will not touch the one it does not
  * own. Saying nothing here is what made the warning look like Notifai's bug.
  */
-export declare function codexCoexistenceNotes(cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
+export declare function codexCoexistenceNotes(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
 /**
  * What `CODEX_HOME` is doing to this shell, when it is doing anything.
  *
@@ -336,21 +347,15 @@ export interface InstalledHandler {
     timeout?: number;
     async?: boolean;
     statusMessage?: string;
+    additionalContextLimit?: number;
 }
 export interface Installation {
     harness: HookInstallableHarness;
     file: string;
-    global: boolean;
     handlers: InstalledHandler[];
     /** Structural defects that require reinstalling this generated adapter. */
     problems?: string[];
 }
-/**
- * Best-effort mirror of the identity current Codex builds compare with
- * `hooks.state.*.trusted_hash`. This persisted format is diagnostic evidence,
- * not an API: Codex's `/hooks` UI remains authoritative and Notifai never
- * writes the trust store.
- */
 export declare function codexHookIdentityHash(handler: InstalledHandler): string;
 /** Best-effort mirror of current Codex's persisted key for one handler. */
 export declare function codexTrustKey(installation: Installation, handler: InstalledHandler): string;
@@ -373,7 +378,17 @@ export declare function codexStopDefinitionFingerprint(installations: Installati
  * `/hooks` remains the source of truth.
  */
 export declare function codexTrustProblems(installations: Installation[], env?: NodeJS.ProcessEnv): string[];
-/** Every place either harness would read a Notifai handler from. */
-export declare function findInstallations(cwd: string, env?: NodeJS.ProcessEnv, adapterHome?: string, platform?: NodeJS.Platform | HookHostPlatform): Installation[];
+/**
+ * The one Machine installation each harness would read a Notifai handler from.
+ */
+export declare function findInstallations(env?: NodeJS.ProcessEnv, adapterHome?: string, platform?: NodeJS.Platform | HookHostPlatform): Installation[];
+/**
+ * Notifai handlers a previous build left in Project-scoped files.
+ *
+ * These are never an install target and never a fallback: they are residue to
+ * report and remove once the Machine installation is proven current. Foreign
+ * handlers sharing those files are not returned and are never touched.
+ */
+export declare function findLegacyProjectInstallations(cwd: string, env?: NodeJS.ProcessEnv, adapterHome?: string, platform?: NodeJS.Platform | HookHostPlatform): Installation[];
 /** The hook event a handler's command actually invokes, e.g. `stop`. */
 export declare function handlerEvent(command: string): string | null;