/**
 * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
 *
 * Hooks use globalThis (like the command registry) to guarantee a single shared
 * instance across all module copies — critical when TS plugins are loaded via
 * npm link / peerDependency symlinks.
 *
 * Available hooks:
 *   onStartup        — fired once after all commands & plugins are discovered
 *   onBeforeExecute  — fired before every command execution
 *   onAfterExecute   — fired after every command execution (receives result)
 */
export type HookName = 'onStartup' | 'onBeforeExecute' | 'onAfterExecute';
export interface HookContext {
    /** Command full name in "site/name" format, or "__startup__" for onStartup */
    command: string;
    /** Coerced and validated arguments */
    args: Record<string, unknown>;
    /** Epoch ms when execution started (set by executeCommand) */
    startedAt?: number;
    /** Epoch ms when execution finished (set by executeCommand) */
    finishedAt?: number;
    /** Error thrown by the command, if execution failed */
    error?: unknown;
    /** Plugins can attach arbitrary data here for cross-hook communication */
    [key: string]: unknown;
}
export type HookFn = (ctx: HookContext, result?: unknown) => void | Promise<void>;
declare global {
    var __opencli_hooks__: Map<HookName, HookFn[]> | undefined;
}
/** Register a hook that fires once after all plugins are discovered. */
export declare function onStartup(fn: HookFn): void;
/** Register a hook that fires before every command execution. */
export declare function onBeforeExecute(fn: HookFn): void;
/** Register a hook that fires after every command execution with the result. */
export declare function onAfterExecute(fn: HookFn): void;
/**
 * Trigger all registered handlers for a hook.
 * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
 */
export declare function emitHook(name: HookName, ctx: HookContext, result?: unknown): Promise<void>;
/**
 * Remove all registered hooks. Intended for testing only.
 */
export declare function clearAllHooks(): void;