/**
 * Error Handling Utilities
 * Custom error classes and error formatting utilities.
 *
 * Provides:
 * - PlatformIOError: Base error class.
 * - PlatformIONotInstalledError: Environment configuration error.
 * - BoardNotFoundError: Board resolution error.
 * - ProjectInitError: Initialization failure error.
 * - BuildError: Compilation failure error.
 * - UploadError: Upload execution error.
 * - LibraryError: Dependency resolution error.
 * - CommandTimeoutError: Process timeout error.
 * - formatPlatformIOError: Standardizes error messages.
 * - parseStderrErrors: Extracts error codes from output.
 * - isPlatformIONotFoundError: Validates environment issues.
 */
/**
 * Base error class for PlatformIO-related errors
 */
export declare class PlatformIOError extends Error {
    readonly code?: string | undefined;
    readonly context?: Record<string, unknown> | undefined;
    constructor(message: string, code?: string | undefined, context?: Record<string, unknown> | undefined);
}
/**
 * Error thrown when PlatformIO CLI is not installed or not found in the system PATH.
 */
export declare class PlatformIONotInstalledError extends PlatformIOError {
    constructor(message?: string);
}
/**
 * Error thrown when a board ID is invalid or cannot be resolved in the PlatformIO registry.
 */
export declare class BoardNotFoundError extends PlatformIOError {
    constructor(boardId: string);
}
/**
 * Error thrown when the `project init` command fails to scaffold a new codebase.
 */
export declare class ProjectInitError extends PlatformIOError {
    constructor(message: string, context?: Record<string, unknown>);
}
/**
 * Error thrown when the `run` command fails during the compilation phase.
 */
export declare class BuildError extends PlatformIOError {
    constructor(message: string, context?: Record<string, unknown>);
}
/**
 * Error thrown when the firmware or filesystem upload operation fails to reach the device.
 */
export declare class UploadError extends PlatformIOError {
    constructor(message: string, context?: Record<string, unknown>);
}
/**
 * Error thrown during library registry interactions (install, search, update).
 */
export declare class LibraryError extends PlatformIOError {
    constructor(message: string, context?: Record<string, unknown>);
}
/**
 * Error thrown when a child process execution exceeds the defined timeout limit.
 */
export declare class CommandTimeoutError extends PlatformIOError {
    constructor(command: string, timeout: number);
}
/**
 * Formats a PlatformIO error into a user-friendly message with troubleshooting hints.
 *
 * @param error - The raw error caught from execution.
 * @returns Formatted and localized troubleshooting message.
 */
export declare function formatPlatformIOError(error: unknown): string;
/**
 * Extracts relevant error information from PlatformIO CLI stderr output.
 *
 * @param stderr - Target output string buffer to search.
 * @returns Array of identified critical error messages.
 */
export declare function parseStderrErrors(stderr: string): string[];
/**
 * A single structured build error with its source location, raw text, and a
 * categorical tag the UI can format on. Mirrors what gcc/clang/PIO already
 * emit; we just lift the structure out of the log so agents don't have to
 * scan ~600 lines of stdout to find it.
 */
export interface StructuredBuildError {
    /** Categorical tag — drives the matching `nextStep` hint. */
    category: "missing_header" | "undefined_reference" | "syntax" | "missing_library" | "missing_platformio_ini" | "missing_environment" | "permission" | "toolchain" | "unknown";
    /** One-line human-readable summary, suitable as a UI bullet point. */
    message: string;
    /** Source file relative to project, if extractable. */
    file?: string;
    /** Source line number, if extractable. */
    line?: number;
    /** Verbatim log line that triggered detection — useful for debugging the parser itself. */
    raw: string;
}
/**
 * Extracts structured errors from a build log. Walks the log once,
 * applying ordered pattern matchers; the first match wins per line so we
 * don't double-classify (e.g. a gcc "fatal error: X.h: No such file" both
 * has `fatal` and `error:` keywords but is really one missing-header event).
 *
 * Designed to be cheap on success (early return on empty log) and forgiving
 * on weird log content (always returns a — possibly empty — array, never
 * throws).
 *
 * @param log - Combined stdout+stderr from `pio run` or similar.
 */
export declare function parseStructuredBuildErrors(log: string): StructuredBuildError[];
/**
 * Translates structured build errors into actionable next-step instructions
 * the agent can act on without re-reading the log. EmbedBench traces showed
 * agents repeatedly re-issuing identical edits after build failures because
 * the unstructured log buried the "what should I do" signal. Returning
 * `nextSteps` alongside errors gives the model a concrete plan in its first
 * tokens of context.
 *
 * The returned array is always present (possibly empty) so callers can rely
 * on a stable shape.
 *
 * @param errors - Structured errors from {@link parseStructuredBuildErrors}.
 * @param success - Whether the build succeeded. On success we still emit
 *   forward-looking hints ("Run upload_firmware to flash the device").
 */
export declare function deriveNextSteps(errors: StructuredBuildError[], success: boolean): string[];
/**
 * Checks if an error indicates PlatformIO is not installed.
 *
 * @param error - Caught exception object block.
 * @returns True if error originates from missing command interpreter.
 */
export declare function isPlatformIONotFoundError(error: unknown): boolean;
//# sourceMappingURL=errors.d.ts.map