@raidiant/notifai 11.7.1 → 12.0.0-beta.11

package/dist/install-hooks.d.ts

@@ -1,470 +0,0 @@
-import { hookHostPlatform, type HookHostPlatform } from './hook-adapter.js';
-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`;
- * a fresh install writes `hooks.json`, except when the User's own hooks already
- * live inline. Notifai-owned inline handlers with no foreign inline neighbours
- * are moved to `hooks.json`. 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
- * adapter instead of being forced through this shared document shape.
- */
-export interface HookHandler {
-    type: 'command';
-    command: string;
-    timeout?: number;
-    async?: boolean;
-    asyncRewake?: 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 HookCommandOptions {
-    platform?: NodeJS.Platform | HookHostPlatform;
-    /** Registered Node used to interpret the Windows adapter. Ignored on POSIX. */
-    nodePath?: string;
-}
-/**
- * The command each hook runs. Harness definitions know only the stable
- * user-level adapter. Mutable Node, package-manager, version, and checkout
- * paths live behind that seam and never enter a trusted hook identity —
- * except on Windows, where CreateProcess cannot run the adapter without an
- * explicit Node executable, so the registered interpreter is named first.
- */
-export declare function hookCommand(adapterPath: string, event: string, harness?: HookInstallableHarness, options?: HookCommandOptions): string;
-/** The leading argv that every Notifai handler must start with. */
-export declare function hookCommandPrefix(adapterPath: string, options?: HookCommandOptions): string;
-/**
- * Says "Notifai installed this" without saying which checkout did.
- *
- * Ownership used to be matched on the absolute script path, so installing from
- * a second checkout did not recognise the first one's handlers as ours. Both
- * stayed, the harness ran both, and one question produced two notifications;
- * uninstalling the second silently left the first running. A marker that every
- * Notifai build writes and no build's path appears in fixes that by making
- * ownership a property of the handler rather than of the machine it was
- * installed from.
- *
- * It is a real (ignored) CLI flag rather than a comment because not every
- * harness runs the command through a shell.
- */
-export declare const OWNER_MARKER = "--owner notifai";
-/**
- * Quote one Windows argv element so CommandLineToArgvW / CreateProcess keep
- * it as a single argument. Always used for the Node and adapter paths, which
- * routinely contain spaces (`Program Files`) and must not use POSIX quotes
- * inside JSON or TOML harness documents.
- */
-export declare function quoteWindowsArg(value: string): string;
-export interface BuildOptions {
-    /** Stable user-level executable installed by the hook adapter module. */
-    adapterPath: string;
-    /** The installed adapter stamps its exact harness into project pointers. */
-    harness?: HookInstallableHarness;
-    platform?: NodeJS.Platform | HookHostPlatform;
-    /** Registered Node named first in Windows hook commands. */
-    nodePath?: string;
-}
-/**
- * Harnesses without asynchronous Question Routing use this short Stop budget.
- * Claude Code and Codex use `QUESTION_STOP_TIMEOUT_SECONDS` instead.
- */
-export declare const NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS = 540;
-export { QUESTION_STOP_TIMEOUT_SECONDS } from './question-timing.js';
-/**
- * Codex's Session Attendant lifetime. Codex kills an async hook at its
- * declared timeout, so the attendant declares the same complete window a
- * question owner does; the next prompt or turn end starts another.
- */
-export declare const CODEX_ATTEND_TIMEOUT_SECONDS: number;
-/** Codex clamps an Interrupt hook to three seconds; declaring it keeps the definition honest. */
-export declare const CODEX_INTERRUPT_TIMEOUT_SECONDS = 3;
-/**
- * Whether this harness's Stop handler runs detached from the turn.
- *
- * The installer and doctor share this predicate so they agree which harnesses
- * run out of band. Owner lifetime is route-neutral and lives in
- * `question-timing.ts`.
- *
- * Codex is detached on every platform because its delivery route is a write to
- * the thread's own durable inbox rather than this hook's stdout: there is no
- * continuation to keep a turn open for, and the queue has no platform
- * dependency to gate on. Claude Code still needs its turn held on Windows,
- * where no inbox socket exists.
- */
-export declare function stopHandlerIsDetached(harness: HookInstallableHarness | undefined, platform?: Parameters<typeof hookHostPlatform>[0]): boolean;
-/**
- * The turn-end handler, whose shape is the whole per-harness difference.
- *
- * Claude Code takes the answer over its own inbox socket and Codex takes it
- * through its thread's durable inbox, so both Stop hooks are `async: true`:
- * they return immediately, the terminal is never held, and the waiter finishes
- * out of band. Only Claude on Windows still blocks and prints a continuation to
- * stdout, because no inbox socket exists there. Every Question Routing owner
- * declares the same complete-window timeout, because the detached waiter must
- * outlive the answer window in every case; what changed for Codex is that a
- * short or missing timeout no longer truncates a held *turn*. Blocking hosts
- * also set `statusMessage` so the held turn is not mistaken for a hang.
- */
-export declare const BLOCKING_STOP_STATUS_MESSAGE = "Notifai: waiting for your answer";
-export declare function buildHookConfig(options: BuildOptions): HookConfig;
-export interface CursorHookHandler {
-    command: string;
-    timeout?: number;
-    loop_limit?: number | null;
-}
-export type CursorHookConfig = Record<string, CursorHookHandler[]>;
-interface CursorSettingsDocument {
-    version?: number;
-    hooks?: CursorHookConfig;
-    [key: string]: unknown;
-}
-/** Cursor's native schema is flat and uses lower-camel lifecycle event names. */
-export declare function buildCursorHookConfig(options: BuildOptions): CursorHookConfig;
-/**
- * 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 legacyProjectHookFiles(harness: HookInstallableHarness, cwd: string): string[];
-/**
- * The account home harness config roots are resolved against.
- *
- * Delegates to the shared process/path `accountHome` so Cursor, OpenCode,
- * Claude, and Codex follow the same Windows USERPROFILE / MSYS HOME rules.
- */
-export declare function harnessAccountHome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string;
-/**
- * Where Codex looks for a project's hooks — the **main** repository, not the
- * working directory.
- *
- * Run from a linked git worktree, Codex reads `<main repo>/.codex/config.toml`
- * (or a leftover `hooks.json`) and never looks at the worktree's own. Proven 2026-08-03 in an isolated
- * `CODEX_HOME`: with cwd set to a worktree, a handler at the main repo root
- * fired and an identical one at the worktree root did not; removing the main
- * one left nothing firing at all. Writing to cwd therefore produces a silent
- * no-op for anyone whose agent runs in a worktree, which is the normal case
- * under tooling like Orca.
- *
- * Claude Code does not share this behaviour — it reads the worktree's own
- * `.claude/settings.local.json` — so this deliberately applies to Codex only.
- */
-export declare function codexProjectRoot(cwd: string): string;
-/**
- * Harness-specific home variables relocate the whole active harness home.
- * This matters under session managers that give each Codex account its own
- * `CODEX_HOME`: writing to the OS account's ~/.codex would configure a
- * different Codex installation than the one running the command.
- */
-export declare function configHome(env: NodeJS.ProcessEnv, variable: string, fallback: string, platform?: NodeJS.Platform | HookHostPlatform): string;
-/**
- * User-global Codex config directory for the *running* Codex installation.
- *
- * `CODEX_HOME` replaces the home; it does not shadow it. `codex doctor` with
- * the variable set reports that directory for every path it resolves and never
- * consults `~/.codex` at all. So a session manager that points Codex at its own
- * home makes `~/.codex` inert for those sessions, and installing there would
- * write hooks the running agent never reads while reporting success.
- *
- * Following the variable is therefore correct even though it means install and
- * doctor resolve different homes when run from different shells. Doctor names
- * the home it inspected for exactly that reason — see `codexHomeNote`.
- */
-export declare function codexGlobalDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string;
-export interface CodexLayerPaths {
-    dir: string;
-    hooksJson: string;
-    configToml: string;
-}
-/** 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. */
-    jsonEvents: string[];
-    tomlEvents: string[];
-    /** 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.
- *
- * `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.
- *
- * A fresh installation uses `hooks.json` unless foreign inline handlers make
- * `config.toml` the layer's established representation. Notifai-owned inline
- * handlers with no foreign inline neighbours are moved to `hooks.json`. Codex
- * keys approval by source path, so that move is a User-owned `/hooks` review,
- * not a silent identity-preserving refresh. `[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;
-/**
- * Serialize one Notifai transaction across both representations in a Codex
- * layer, then inspect that layer only after acquiring the shared anchor.
- */
-export declare function withCodexLayerTransaction<T>(paths: CodexLayerPaths, action: (inspection: CodexLayerInspection) => T): T;
-/** 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[];
-/**
- * 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
- * handler, and already prints its own "prefer a single representation" warning
- * at startup. Foreign handlers in the other file are the user's — often written
- * by another tool that manages that file — and repeating Codex's warning as a
- * Notifai failure demanded an edit to configuration Notifai does not own, for a
- * condition where every handler still fires exactly once.
- *
- * What is ours to diagnose is Notifai in both files. Then one event really does
- * send two Notification Requests per turn, and the copy outside the write
- * target keeps firing an older definition after the next install refreshes only
- * 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(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
-/**
- * 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
- * exactly once — but Codex also prints "prefer one representation per layer"
- * at startup, and a user who sees that warning deserves to know which file is
- * 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(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string[];
-/**
- * What `CODEX_HOME` is doing to this shell, when it is doing anything.
- *
- * Codex replaces its whole home when the variable is set, so hooks installed
- * from a shell without it are simply absent here, and its trust store is keyed
- * by absolute file path — a config copied between homes arrives untrusted.
- * Both facts turn into "Notifai is not wired" reports that look like a bug in
- * the installer, so doctor names the home it actually inspected.
- */
-export declare function codexHomeNote(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): string | null;
-/**
- * Every supported harness this project or machine shows evidence of, in
- * declared order. Project markers come first, then machine installs that the
- * project did not already name.
- *
- * `AGENTS.md` still counts for nothing — see `localHarnessEvidence`.
- */
-export declare function detectedHarnesses(cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): HookInstallableHarness[];
-/**
- * Which *single* harness to wire when a caller still needs exactly one, or
- * null when it is genuinely unclear.
- *
- * Project evidence decides, and machine evidence is consulted only when the
- * project offers none. Several markers are not a failure of detection — they
- * are several harnesses. `detectedHarnesses` is the default for install;
- * this helper stays for uninstall and any caller that cannot take a list.
- */
-export declare function detectHarness(cwd: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): HookInstallableHarness | null;
-export interface SettingsDocument {
-    hooks?: HookConfig;
-    [key: string]: unknown;
-}
-export declare function mergeCursorHooks(existing: CursorSettingsDocument, incoming: CursorHookConfig, scriptPath: string): {
-    document: CursorSettingsDocument;
-    added: string[];
-    replaced: string[];
-    removed: string[];
-};
-export declare function removeCursorHooks(existing: CursorSettingsDocument, scriptPath: string): {
-    document: CursorSettingsDocument;
-    added: string[];
-    replaced: string[];
-    removed: string[];
-};
-export interface MergeResult {
-    document: SettingsDocument;
-    added: string[];
-    replaced: string[];
-    /** Events an older build installed that this one no longer serves. */
-    removed: string[];
-}
-/**
- * Refresh owned handlers in their existing slots. Codex's approval identity
- * includes group and handler indices, so stripping then appending an unchanged
- * handler can revoke its approval and stale an active session's Stop definition.
- * Missing handlers append after existing slots; foreign handlers and matcher
- * metadata stay in place.
- *
- * Retired handlers are considered in every event. Hosts without index-based
- * approval can remove them; strict Codex repair refuses ambiguous removal so
- * an explicit migration can account for native trust and active sessions.
- */
-export declare function mergeHooks(existing: SettingsDocument, incoming: HookConfig, scriptPath: string, options?: {
-    preserveIdentities?: boolean;
-}): MergeResult;
-export declare function removeHooks(existing: SettingsDocument, scriptPath: string): MergeResult;
-/**
- * Writes the settings file the way a tool that does not own it should.
- *
- * Truncating in place lost the user's whole harness configuration if the write
- * failed halfway, and clobbered a concurrent editor's changes; following a
- * symlink wrote through to a target they never named. So: refuse
- * anything that is not a regular file, write a sibling temp file, fsync it, and
- * rename over the original — atomic within a directory on every platform we
- * support.
- */
-export declare function applyPlan(file: string, document: SettingsDocument | CursorSettingsDocument): void;
-/** Validate a proposed document before any file in a multi-file edit changes. */
-export declare function preparePlan(file: string, document: SettingsDocument | CursorSettingsDocument, previous?: string | null): () => void;
-/** Delete an emptied Codex hooks.json and a now-empty layer directory. */
-export declare function cleanupEmptiedCodexLayer(paths: CodexLayerPaths): void;
-export declare function loadSettings(file: string): SettingsDocument;
-export declare function isTomlSettingsPath(file: string): boolean;
-export declare function loadCursorSettings(file: string): CursorSettingsDocument;
-/** One of our handlers as it sits in a settings file, with its position. */
-export interface InstalledHandler {
-    event: string;
-    /** Index of the matcher group within the event, as the harness sees it. */
-    groupIndex: number;
-    /** Index of the handler within its group. */
-    handlerIndex: number;
-    command: string;
-    /** Declared process lifetime, used to detect config/install drift. */
-    timeout?: number;
-    async?: boolean;
-    asyncRewake?: boolean;
-    statusMessage?: string;
-    additionalContextLimit?: number;
-}
-export interface Installation {
-    harness: HookInstallableHarness;
-    file: string;
-    handlers: InstalledHandler[];
-    /** Structural defects that require reinstalling this generated adapter. */
-    problems?: string[];
-}
-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;
-/**
- * Stable identity of the one Codex Stop definition an Agent Session loaded.
- *
- * Codex materializes hook handlers into the session runtime. A later config
- * change can therefore make the file on disk current while an older session
- * keeps executing the definition it loaded at activation. Include Codex's
- * source key as well as the normalized handler identity so moving an otherwise
- * byte-identical definition between project and global layers also requires a
- * fresh session.
- */
-export declare function codexStopDefinitionFingerprint(installations: Installation[]): string | undefined;
-/**
- * Trust defects that make installed Codex handlers look present while Codex
- * skips them. Trust is user-owned; the supported repair is Codex's `/hooks`
- * review UI, never writing the trust store on the user's behalf. Because the
- * persisted shape is not a public Codex contract, this diagnosis can drift;
- * `/hooks` remains the source of truth.
- */
-export declare function codexTrustProblems(installations: Installation[], env?: NodeJS.ProcessEnv): string[];
-/**
- * Trust defects in the handlers Question Routing runs. The Session Attendant
- * is presence, never a routing gate: an attend handler still awaiting
- * approval is reported by doctor and init and never refuses a question.
- */
-export declare function codexRoutingTrustProblems(installations: Installation[], env?: NodeJS.ProcessEnv): string[];
-export declare function notifaiNativePluginEnablementKeys(value: unknown): string[];
-export declare function stripObsoleteNotifaiPluginEnablement(document: SettingsDocument): {
-    document: SettingsDocument;
-    removed: string[];
-};
-/**
- * Remove enabled Notifai plugin tables only after lexical ownership and full
- * semantic preservation are proven. Unsupported dotted/inline definitions
- * fail before mutation, rather than silently leaving a second firing path.
- */
-export declare function spliceOutNotifaiPluginTables(source: string): {
-    next: string;
-    removed: string[];
-};
-export interface ObsoleteNativePluginWiring {
-    harness: 'claude-code' | 'codex';
-    file: string;
-    keys: string[];
-}
-/**
- * Leftover native plugin enablement that would fire beside document hooks.
- *
- * Reads only harness settings files this installer already owns inspecting.
- * It never shells out to a plugin CLI and never writes a plugin.
- */
-export declare function findObsoleteNotifaiPluginWiring(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform | HookHostPlatform): ObsoleteNativePluginWiring[];
-/**
- * Plan native plugin retirement without changing configuration. The caller
- * validates every destination before applying this plan under the layer lock.
- */
-export declare function prepareCodexPluginCleanup(file: string): {
-    source: string | null;
-    removed: string[];
-    apply: () => void;
-};
-/**
- * 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;