/**
 * Platform Utilities - Cross-platform OS operations
 *
 * Abstracts platform-specific operations for macOS, Linux, and Windows
 * Enhanced for process lifecycle management with async API, logger injection,
 * and system notifications
 */
import { Logger } from './logger.js';
export type Platform = 'darwin' | 'linux' | 'win32';
/**
 * Gets the current platform
 */
export declare function getCurrentPlatform(): Platform;
/**
 * Checks if a process exists (cross-platform)
 * SECURITY: Uses process.kill(pid, 0) for POSIX, validated PID for Windows
 *
 * @param pid - Process ID to check
 * @returns true if process exists
 */
export declare function checkProcessExists(pid: number): boolean;
/**
 * Gets file modification time in seconds since epoch (cross-platform)
 * SECURITY: Uses Node.js fs.statSync instead of shell commands
 *
 * @param filePath - Path to file
 * @returns Modification time in seconds since epoch
 */
export declare function getFileMtime(filePath: string): number;
/**
 * Kills a process (cross-platform)
 * SECURITY: Uses process.kill for POSIX, execFileSync for Windows
 *
 * @param pid - Process ID to kill
 * @param signal - Signal to send (default: SIGTERM)
 */
export declare function killProcess(pid: number, signal?: string): void;
/**
 * Acquires a file lock using atomic directory creation (cross-platform)
 *
 * @param lockPath - Path to lock directory
 * @returns true if lock acquired
 */
export declare function acquireFileLock(lockPath: string): boolean;
export interface PlatformUtilsOptions {
    logger?: Logger;
}
/**
 * Enhanced cross-platform utility functions with async API and logger injection
 */
export declare class PlatformUtils {
    private platform;
    private logger;
    constructor(options?: PlatformUtilsOptions);
    /**
     * Get current platform
     */
    getPlatform(): Platform;
    /**
     * Check if current platform is Windows
     */
    isWindows(): boolean;
    /**
     * Check if current platform is POSIX (macOS or Linux)
     */
    isPosix(): boolean;
    /**
     * Check if a process exists by PID (async)
     *
     * - macOS/Linux: kill -0 $pid (signal 0 = existence check)
     * - Windows: tasklist /FI "PID eq $pid"
     *
     * @param pid Process ID to check
     * @returns true if process exists, false otherwise
     */
    checkProcessExistsAsync(pid: number): Promise<boolean>;
    /**
     * Get file modification time (async, uses fs.stat for cross-platform)
     *
     * @param path File path
     * @returns Modification time in seconds since epoch
     */
    getFileMtimeAsync(path: string): Promise<number>;
    /**
     * Acquire file lock using atomic mkdir (async)
     *
     * @param lockPath Path to lock directory
     * @param timeoutMs Maximum time to wait for lock (default: 5000ms)
     * @returns true if lock acquired, false if timeout
     */
    acquireFileLockAsync(lockPath: string, timeoutMs?: number): Promise<boolean>;
    /**
     * Release file lock (async)
     *
     * @param lockPath Path to lock directory
     */
    releaseFileLockAsync(lockPath: string): Promise<void>;
    /**
     * Kill process with signal (async)
     *
     * @param pid Process ID to kill
     * @param signal Signal to send (default: SIGTERM)
     */
    killProcessAsync(pid: number, signal?: NodeJS.Signals): Promise<void>;
    /**
     * Kill process with graceful fallback (SIGTERM → SIGKILL)
     *
     * @param pid Process ID to kill
     * @param gracePeriodMs Time to wait after SIGTERM before SIGKILL (default: 2000ms)
     */
    killProcessGracefully(pid: number, gracePeriodMs?: number): Promise<void>;
    /**
     * Send system notification
     *
     * - macOS: osascript (AppleScript)
     * - Linux: notify-send (if available)
     * - Windows: PowerShell toast notification
     *
     * Fails gracefully if notification system is unavailable
     *
     * IMPORTANT: Notifications MUST be explicit! Always:
     * 1. Start title with "SpecWeave:" to identify source
     * 2. Use explicit message describing what happened
     * 3. Include "No action needed" for informational notifications
     *
     * @param title Notification title (should start with "SpecWeave:")
     * @param body Notification body text (should be explicit about what happened)
     * @param sound Optional sound name for macOS (default: "Pop" for neutral notifications)
     */
    sendNotification(title: string, body: string, sound?: string): Promise<void>;
    /**
     * Escapes string for AppleScript to prevent command injection
     * Security: Handles backslashes first, then quotes, then control chars
     */
    private escapeForAppleScript;
    /**
     * macOS notification using osascript (NON-BLOCKING)
     *
     * CRITICAL: Uses exec() without await to prevent blocking the main thread!
     * Notifications should NEVER block Claude Code execution.
     *
     * @param title Notification title (should start with "SpecWeave:")
     * @param body Notification body (should be explicit about what happened)
     * @param sound Optional sound name (default: "Pop" for neutral notifications)
     */
    private sendNotificationMacOS;
    /**
     * Escapes string for shell (notify-send on Linux) to prevent command injection
     * Security: Comprehensive escaping for shell metacharacters
     */
    private escapeForShell;
    /**
     * Linux notification using notify-send (NON-BLOCKING)
     *
     * CRITICAL: Fire-and-forget pattern to prevent blocking Claude Code!
     * Notifications should NEVER block execution.
     */
    private sendNotificationLinux;
    /**
     * Escapes string for PowerShell to prevent command injection
     * Security: Comprehensive escaping for PowerShell special chars
     */
    private escapeForPowerShell;
    /**
     * Windows notification using PowerShell toast (NON-BLOCKING)
     *
     * CRITICAL: Fire-and-forget pattern to prevent blocking Claude Code!
     * Notifications should NEVER block execution.
     */
    private sendNotificationWindows;
}
export declare const platformUtils: PlatformUtils;
//# sourceMappingURL=platform-utils.d.ts.map