/**
 * Caffeinate management for macOS
 *
 * Manages a background `caffeinate` process to prevent macOS from sleeping.
 * PID state is stored in a runtime file for reliable stop/status operations.
 */
export interface CaffeinateState {
    pid: number;
    startedAt: string;
    flags: string[];
    duration?: number;
}
/**
 * Ensure the platform is macOS. Throws a descriptive error on other platforms.
 */
export declare function assertMacOS(): void;
/**
 * Check whether the platform is macOS.
 */
export declare function isMacOS(): boolean;
/**
 * Read the stored caffeinate state from the PID file.
 * Returns null if no state exists or the file is invalid.
 */
export declare function readState(): CaffeinateState | null;
/**
 * Write caffeinate state to the PID file.
 */
export declare function writeState(state: CaffeinateState): void;
/**
 * Remove the PID file.
 */
export declare function clearState(): void;
/**
 * Check whether a process with the given PID is still running.
 */
export declare function isProcessRunning(pid: number): boolean;
/**
 * Get the status of the managed caffeinate process.
 * Cleans up stale state if the process is no longer running.
 */
export declare function getStatus(): {
    running: boolean;
    state: CaffeinateState | null;
};
/**
 * Start a background caffeinate process.
 *
 * @param flags - Additional flags to pass to caffeinate (e.g. ['-d', '-i'])
 * @param duration - Optional duration in seconds (passed as -t flag)
 * @returns The state of the started process
 * @throws If already running (idempotent guard) or on non-macOS
 */
export declare function startCaffeinate(flags?: string[], duration?: number): CaffeinateState;
/**
 * Stop the managed caffeinate process.
 *
 * @returns true if a process was stopped, false if nothing was running
 */
export declare function stopCaffeinate(): boolean;
export declare const _internals: {
    RUNTIME_DIR: string;
    PID_FILE: string;
};
