@raidiant/notifai 0.5.0 → 1.0.0

package/dist/install-hooks.js

@@ -1,12 +1,12 @@
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync, } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
-import { parse as parseToml } from 'smol-toml';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { atomicWriteFileSync } from './atomic-file.js';
 import { hookAdapterPath } from './hook-adapter.js';
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js';
-import { HARNESSES, HOOK_TIMING } from './harnesses.js';
+import { HARNESSES } from './harnesses.js';
 export { HARNESSES } from './harnesses.js';
 /**
  * The three joints the OpenCode plugin hooks into, as (harness event, the
@@ -51,26 +51,52 @@ export const OWNER_MARKER = '--owner notifai';
 function quote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
-/** Generated blocking adapters grant the owner budget one fixed minute of host headroom. */
-const HOOK_CEILING_SECONDS = HOOK_TIMING.totalSeconds + HOOK_TIMING.hostHeadroomSeconds;
 /**
- * Stable process budget for a blocking turn-end adapter.
+ * Claude Code's Stop handler returns instantly and the same process lives on
+ * out of band as the escalation waiter, so this `timeout` bounds a background
+ * process rather than the user's turn.
  *
- * Codex trusts the exact serialized hook definition. Deriving this timeout
- * from mutable question preferences meant changing `ask_grace_seconds`
- * silently invalidated Stop trust while the other two handlers kept running.
- * The runtime already fits grace and reply waiting inside the harness ceiling;
- * the installed identity therefore stays at that ceiling across preferences.
+ * It is always declared, and declared far above the longest wait a waiter can
+ * take. Claude's default is 600 s and the kill is **silent** — the backgrounded
+ * process simply vanishes, no error is reported anywhere, and the answer the
+ * user already gave is never delivered. Sitting anywhere near that boundary
+ * turns a slow reply into a lost one, so this does not: an explicit value
+ * raises the ceiling (verified against a 660 s wait under an hour-long
+ * declaration), and an hour is several times the waiter's own ceiling.
  */
-export function blockingHookTimeoutSeconds() {
-    return HOOK_CEILING_SECONDS;
+export const CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS = 3600;
+/**
+ * The declared process budget for a host that holds its turn while the waiter
+ * runs: the waiter's own ceiling plus a minute of host headroom, as one plain
+ * number rather than a budget carved into reserves.
+ *
+ * Codex is deliberately absent from this. It owns its Stop timeout today, and
+ * declaring one would change the serialized definition Codex hashes into
+ * `trusted_hash` — which silently stops every Notifai handler from running
+ * until the user re-approves them in `/hooks`.
+ */
+export const BLOCKING_STOP_TIMEOUT_SECONDS = 540;
+/**
+ * The turn-end handler, whose shape is the whole per-harness difference.
+ *
+ * Claude Code takes the answer over its own inbox socket, so its Stop hook is
+ * `async: true`: it returns immediately, the terminal is never held, and the
+ * waiter finishes out of band. Every other host still delivers by printing a
+ * continuation to this process's stdout, so its Stop hook blocks and needs a
+ * declared ceiling above the wait — except Codex, which owns that number
+ * itself and whose definition must stay byte-stable for its trust store.
+ */
+function stopHandler(adapterPath, harness) {
+    const command = hookCommand(adapterPath, 'stop', harness);
+    if (harness === 'claude-code') {
+        return { type: 'command', command, timeout: CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, async: true };
+    }
+    if (harness === 'codex')
+        return { type: 'command', command };
+    return { type: 'command', command, timeout: BLOCKING_STOP_TIMEOUT_SECONDS };
 }
 export function buildHookConfig(options) {
     const { adapterPath } = options;
-    const hostOwnsStopTimeout = options.harness === 'codex';
-    // Runtime preferences fit inside this fixed process budget without becoming
-    // part of the serialized definition Codex asks the user to trust.
-    const blockingTimeout = blockingHookTimeoutSeconds();
     return {
         UserPromptSubmit: [
             {
@@ -85,17 +111,7 @@ export function buildHookConfig(options) {
                 ],
             },
         ],
-        Stop: [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand(adapterPath, 'stop', options.harness),
-                        ...(hostOwnsStopTimeout ? {} : { timeout: blockingTimeout }),
-                    },
-                ],
-            },
-        ],
+        Stop: [{ hooks: [stopHandler(adapterPath, options.harness)] }],
         SessionEnd: [
             {
                 hooks: [
@@ -113,7 +129,6 @@ export function buildHookConfig(options) {
 }
 /** Cursor's native schema is flat and uses lower-camel lifecycle event names. */
 export function buildCursorHookConfig(options) {
-    const blockingTimeout = blockingHookTimeoutSeconds();
     return {
         beforeSubmitPrompt: [
             {
@@ -124,7 +139,7 @@ export function buildCursorHookConfig(options) {
         stop: [
             {
                 command: hookCommand(options.adapterPath, 'stop', 'cursor'),
-                timeout: blockingTimeout,
+                timeout: BLOCKING_STOP_TIMEOUT_SECONDS,
                 // A continuation may register a real follow-up question. Match the
                 // session-state cap so those chains are useful but never unbounded.
                 loop_limit: 3,
@@ -160,9 +175,7 @@ export function settingsFile(harness, global, cwd, env = process.env) {
                 ? path.join(configHome(env, 'CLAUDE_CONFIG_DIR', '.claude'), 'settings.json')
                 : path.join(cwd, '.claude', 'settings.local.json');
         case 'codex':
-            return global
-                ? path.join(configHome(env, 'CODEX_HOME', '.codex'), 'hooks.json')
-                : path.join(codexProjectRoot(cwd), '.codex', 'hooks.json');
+            return inspectCodexLayer(codexLayerPaths(global, cwd, env)).writeTarget;
         default:
             return assertNeverHarness(harness);
     }
@@ -264,6 +277,133 @@ export function configHome(env, variable, fallback) {
     const override = env[variable];
     return override !== undefined && override !== '' ? override : path.join(os.homedir(), fallback);
 }
+/** The two files Codex will look at for one config layer. */
+export function codexLayerPaths(global, cwd, env = process.env) {
+    const dir = global
+        ? configHome(env, 'CODEX_HOME', '.codex')
+        : path.join(codexProjectRoot(cwd), '.codex');
+    return {
+        dir,
+        hooksJson: path.join(dir, 'hooks.json'),
+        configToml: path.join(dir, 'config.toml'),
+    };
+}
+/**
+ * Which representation this Codex layer already uses.
+ *
+ * Codex loads `hooks.json` and inline `[hooks]` side by side, runs every
+ * matching handler, and warns when both exist. `[hooks.state]` is the trust
+ * store, not a hook definition, so it does not count as a representation.
+ */
+export function inspectCodexLayer(paths) {
+    const jsonDocument = tryLoadSettings(paths.hooksJson);
+    const tomlDocument = tryLoadSettings(paths.configToml);
+    const jsonEvents = hookEventNames(jsonDocument?.hooks);
+    const tomlEvents = hookEventNames(tomlDocument?.hooks);
+    const jsonForeign = documentHasForeignHandlers(jsonDocument);
+    const tomlForeign = documentHasForeignHandlers(tomlDocument);
+    const jsonOurs = documentHasOurHandlers(jsonDocument);
+    const tomlOurs = documentHasOurHandlers(tomlDocument);
+    const dual = jsonEvents.length > 0 && tomlEvents.length > 0;
+    let writeTarget = paths.hooksJson;
+    if (tomlEvents.length > 0 && jsonEvents.length === 0)
+        writeTarget = paths.configToml;
+    else if (jsonEvents.length > 0 && tomlEvents.length === 0)
+        writeTarget = paths.hooksJson;
+    else if (dual) {
+        if (tomlForeign && !jsonForeign)
+            writeTarget = paths.configToml;
+        else if (jsonForeign && !tomlForeign)
+            writeTarget = paths.hooksJson;
+        else if (!jsonForeign && !tomlForeign)
+            writeTarget = paths.hooksJson;
+        else if (tomlOurs && !jsonOurs)
+            writeTarget = paths.configToml;
+        else if (jsonOurs && !tomlOurs)
+            writeTarget = paths.hooksJson;
+        else
+            writeTarget = paths.hooksJson;
+    }
+    return {
+        paths,
+        jsonEvents,
+        tomlEvents,
+        writeTarget,
+        dual,
+        overlappingEvents: jsonEvents.filter((event) => tomlEvents.includes(event)),
+        canCollapse: dual && !(jsonForeign && tomlForeign),
+    };
+}
+/** Every file in this layer Codex might already be reading hooks from. */
+export function hookDefinitionFiles(harness, global, cwd, env = process.env) {
+    if (harness !== 'codex')
+        return [settingsFile(harness, global, cwd, env)];
+    const paths = codexLayerPaths(global, cwd, env);
+    return [paths.hooksJson, paths.configToml];
+}
+/**
+ * Drop the unused representation after writing the one this layer already had.
+ *
+ * Only safe when the discarded file has no one else's handlers. `hooks.json`
+ * is deleted once it has no events left so Codex stops warning; `config.toml`
+ * is never deleted.
+ */
+export function collapseUnusedCodexRepresentation(keepFile, scriptPath, paths) {
+    const other = keepFile === paths.hooksJson ? paths.configToml : paths.hooksJson;
+    if (!existsSync(other))
+        return null;
+    const document = tryLoadSettings(other);
+    if (document === null || documentHasForeignHandlers(document))
+        return null;
+    const stripped = removeHooks(document, scriptPath);
+    if (other === paths.hooksJson && hookEventNames(stripped.document.hooks).length === 0) {
+        rmSync(other);
+        return other;
+    }
+    applyPlan(other, stripped.document);
+    return other;
+}
+export function codexRepresentationProblems(cwd, env = process.env) {
+    return [false, true].flatMap((global) => {
+        const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env));
+        if (!layer.dual)
+            return [];
+        const overlap = layer.overlappingEvents.length > 0
+            ? ` Matching handlers from both files all run — this layer's ${layer.overlappingEvents.join(', ')} handlers will both fire.`
+            : ' Matching handlers from both files all run.';
+        const collapse = layer.canCollapse
+            ? ` Run \`notifai hooks install --harness codex${global ? ' --global' : ''}\` to collapse onto ${path.basename(layer.writeTarget)}.`
+            : ' Both files have other hooks, so Notifai cannot collapse them.';
+        return [
+            `loading hooks from both ${layer.paths.hooksJson} and ${layer.paths.configToml}; prefer a single representation for this layer.${overlap}${collapse}`,
+        ];
+    });
+}
+function tryLoadSettings(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return loadSettings(file);
+    }
+    catch {
+        return null;
+    }
+}
+function hookEventNames(hooks) {
+    return Object.entries(hooks ?? {})
+        .filter(([, value]) => Array.isArray(value))
+        .map(([event]) => event);
+}
+function documentHasForeignHandlers(document) {
+    if (document === null)
+        return false;
+    return locateAllHandlers(document).some((handler) => !isNotifaiCommand(handler.command));
+}
+function documentHasOurHandlers(document) {
+    if (document === null)
+        return false;
+    return locateHandlers(document).length > 0;
+}
 /** Best-effort detection so `hooks install` usually needs no flags. */
 /**
  * Harnesses this *project* shows evidence of, in the working directory only.
@@ -292,8 +432,8 @@ function localHarnessEvidence(cwd) {
     return found;
 }
 /** Harnesses installed anywhere on this machine — a much weaker signal. */
-function globalHarnessEvidence() {
-    const home = os.homedir();
+function globalHarnessEvidence(env = process.env) {
+    const home = env['HOME'] !== undefined && env['HOME'] !== '' ? env['HOME'] : os.homedir();
     const found = [];
     if (existsSync(path.join(home, '.claude')))
         found.push('claude-code');
@@ -306,27 +446,30 @@ function globalHarnessEvidence() {
     return found;
 }
 /**
- * Which harness to wire in this directory, or null when it is genuinely
- * unclear.
+ * 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.
  *
- * Project evidence decides, and machine evidence is consulted only when the
- * project offers none. The two were previously OR-ed together per harness,
- * which meant a developer with several agent tools installed could never get
- * a detection at all: every `~/.<tool>` directory contributed a candidate, the
- * "exactly one" test never passed, and the answer was null in every repository
- * on the machine. Verified on a machine carrying all four — `notifai init
- * --hooks` failed in five separate projects, each of which plainly used Claude
- * Code.
+ * `AGENTS.md` still counts for nothing — see `localHarnessEvidence`.
+ */
+export function detectedHarnesses(cwd, env = process.env) {
+    const seen = new Set([...localHarnessEvidence(cwd), ...globalHarnessEvidence(env)]);
+    return HARNESSES.filter((harness) => seen.has(harness));
+}
+/**
+ * Which *single* harness to wire when a caller still needs exactly one, or
+ * null when it is genuinely unclear.
  *
- * Having a tool installed says nothing about which one *this* project is
- * worked in. Ambiguity within the project is still ambiguity, and returns
- * null so the caller can ask rather than guess.
+ * 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 function detectHarness(cwd) {
+export function detectHarness(cwd, env = process.env) {
     const local = localHarnessEvidence(cwd);
     if (local.length > 0)
         return local.length === 1 ? local[0] : null;
-    const global = globalHarnessEvidence();
+    const global = globalHarnessEvidence(env);
     return global.length === 1 ? global[0] : null;
 }
 function readCursorSettings(file) {
@@ -446,6 +589,12 @@ export function mergeHooks(existing, incoming, scriptPath) {
     const replaced = [];
     const removed = [];
     for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
+        if (!Array.isArray(groups)) {
+            // Codex keeps `[hooks.state]` beside event tables. It is not a matcher list.
+            ;
+            hooks[event] = groups;
+            continue;
+        }
         const { groups: foreign, removed: hadOurs } = withoutOurs(groups, scriptPath);
         if (hadOurs) {
             if (event in incoming)
@@ -467,6 +616,11 @@ export function removeHooks(existing, scriptPath) {
     const hooks = {};
     const replaced = [];
     for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
+        if (!Array.isArray(groups)) {
+            ;
+            hooks[event] = groups;
+            continue;
+        }
         const { groups: foreign, removed } = withoutOurs(groups, scriptPath);
         if (removed)
             replaced.push(event);
@@ -486,12 +640,30 @@ export function removeHooks(existing, scriptPath) {
  * support.
  */
 export function applyPlan(file, document) {
-    atomicWriteFileSync(file, `${JSON.stringify(document, null, 2)}\n`, {
+    const body = isTomlSettingsPath(file)
+        ? `${stringifyToml(document)}\n`
+        : `${JSON.stringify(document, null, 2)}\n`;
+    atomicWriteFileSync(file, body, {
         requireCurrentUserOwner: true,
     });
 }
 export function loadSettings(file) {
-    return readSettings(file);
+    return isTomlSettingsPath(file) ? readTomlSettings(file) : readSettings(file);
+}
+function isTomlSettingsPath(file) {
+    return file.endsWith('.toml');
+}
+function readTomlSettings(file) {
+    if (!existsSync(file))
+        return {};
+    const source = readOwnedRegularFile(file);
+    try {
+        const parsed = parseToml(source);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        throw new Error(`Could not parse ${file}; fix or move it before installing hooks.`);
+    }
 }
 export function loadCursorSettings(file) {
     return readCursorSettings(file);
@@ -600,85 +772,84 @@ export function codexTrustProblems(installations, env = process.env) {
 function isNotifaiCommand(command) {
     return / hook (user-prompt-submit|stop|session-end)\b/.test(command);
 }
-function isNotifaiHandler(handler) {
-    return isNotifaiCommand(handler.command);
-}
 /** Every place either harness would read a Notifai handler from. */
 export function findInstallations(cwd, env = process.env, adapterHome) {
     const found = [];
     for (const harness of HARNESSES) {
         for (const global of [false, true]) {
-            const file = settingsFile(harness, global, cwd, env);
-            if (!existsSync(file))
-                continue;
-            // OpenCode's adapter is a plugin module, not a settings document, so it
-            // is reported as one installation covering all three events rather than
-            // parsed for handlers.
-            if (harness === 'opencode') {
-                let source;
-                try {
-                    source = readOwnedRegularFile(file);
-                }
-                catch {
+            const files = hookDefinitionFiles(harness, global, cwd, env);
+            for (const file of files) {
+                if (!existsSync(file))
+                    continue;
+                // OpenCode's adapter is a plugin module, not a settings document, so it
+                // is reported as one installation covering all three events rather than
+                // parsed for handlers.
+                if (harness === 'opencode') {
+                    let source;
+                    try {
+                        source = readOwnedRegularFile(file);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const target = opencodePluginTarget(source);
+                    if (target === null)
+                        continue;
+                    const problems = [
+                        ...(!target.current
+                            ? ['obsolete OpenCode event wiring; rerun `notifai hooks install --harness opencode`']
+                            : []),
+                        ...(target.adapter !== hookAdapterPath(adapterHome)
+                            ? [
+                                'OpenCode still names a mutable CLI or runtime path; rerun `notifai hooks install --harness opencode`',
+                            ]
+                            : []),
+                    ];
+                    found.push({
+                        harness,
+                        file,
+                        global,
+                        ...(problems.length > 0 ? { problems } : {}),
+                        // Reported as the command line the plugin will actually run, not as
+                        // the plugin's own path: every check downstream asks which build a
+                        // handler invokes, and for a module that answer lives inside it.
+                        handlers: OPENCODE_EVENTS.map(([event, hookEvent]) => ({
+                            event,
+                            groupIndex: 0,
+                            handlerIndex: 0,
+                            command: hookCommand(target.adapter, hookEvent, 'opencode'),
+                            ...(target.timeoutSeconds === undefined ? {} : { timeout: target.timeoutSeconds }),
+                        })),
+                    });
                     continue;
                 }
-                const target = opencodePluginTarget(source);
-                if (target === null)
+                if (harness === 'cursor') {
+                    let document;
+                    try {
+                        document = readCursorSettings(file);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const handlers = locateCursorHandlers(document);
+                    if (handlers.length > 0) {
+                        const problems = harnessMarkerProblems(harness, handlers, adapterHome);
+                        found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) });
+                    }
                     continue;
-                const problems = [
-                    ...(!target.current
-                        ? ['obsolete OpenCode event wiring; rerun `notifai hooks install --harness opencode`']
-                        : []),
-                    ...(target.adapter !== hookAdapterPath(adapterHome)
-                        ? [
-                            'OpenCode still names a mutable CLI or runtime path; rerun `notifai hooks install --harness opencode`',
-                        ]
-                        : []),
-                ];
-                found.push({
-                    harness,
-                    file,
-                    global,
-                    ...(problems.length > 0 ? { problems } : {}),
-                    // Reported as the command line the plugin will actually run, not as
-                    // the plugin's own path: every check downstream asks which build a
-                    // handler invokes, and for a module that answer lives inside it.
-                    handlers: OPENCODE_EVENTS.map(([event, hookEvent]) => ({
-                        event,
-                        groupIndex: 0,
-                        handlerIndex: 0,
-                        command: hookCommand(target.adapter, hookEvent, 'opencode'),
-                        ...(target.timeoutSeconds === undefined ? {} : { timeout: target.timeoutSeconds }),
-                    })),
-                });
-                continue;
-            }
-            if (harness === 'cursor') {
+                }
                 let document;
                 try {
-                    document = readCursorSettings(file);
+                    document = loadSettings(file);
                 }
                 catch {
                     continue;
                 }
-                const handlers = locateCursorHandlers(document);
+                const handlers = locateHandlers(document);
                 if (handlers.length > 0) {
                     const problems = harnessMarkerProblems(harness, handlers, adapterHome);
                     found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) });
                 }
-                continue;
-            }
-            let document;
-            try {
-                document = readSettings(file);
-            }
-            catch {
-                continue;
-            }
-            const handlers = locateHandlers(document);
-            if (handlers.length > 0) {
-                const problems = harnessMarkerProblems(harness, handlers, adapterHome);
-                found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) });
             }
         }
     }
@@ -712,27 +883,32 @@ function locateCursorHandlers(document) {
     }
     return handlers;
 }
-function locateHandlers(document) {
+function locateAllHandlers(document) {
     const handlers = [];
     for (const [event, groups] of Object.entries(document.hooks ?? {})) {
+        if (!Array.isArray(groups))
+            continue;
         groups.forEach((group, groupIndex) => {
             group.hooks?.forEach((handler, handlerIndex) => {
-                if (isNotifaiHandler(handler)) {
-                    handlers.push({
-                        event,
-                        groupIndex,
-                        handlerIndex,
-                        command: handler.command,
-                        ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
-                        ...(handler.async === undefined ? {} : { async: handler.async }),
-                        ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
-                    });
-                }
+                if (typeof handler?.command !== 'string')
+                    return;
+                handlers.push({
+                    event,
+                    groupIndex,
+                    handlerIndex,
+                    command: handler.command,
+                    ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
+                    ...(handler.async === undefined ? {} : { async: handler.async }),
+                    ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
+                });
             });
         });
     }
     return handlers;
 }
+function locateHandlers(document) {
+    return locateAllHandlers(document).filter((handler) => isNotifaiCommand(handler.command));
+}
 /** The hook event a handler's command actually invokes, e.g. `stop`. */
 export function handlerEvent(command) {
     return / hook ([a-z-]+)/.exec(command)?.[1] ?? null;