/**
 * Error handling utilities for MCP document CRUD operations.
 * Provides consistent error types with codes, suggestions, and JSON serialization.
 */
import type { JsonError } from '../cli/json-output.js';
/**
 * Error codes for document operations.
 * Includes filesystem error codes (ENOENT, EACCES, etc.) for better error handling.
 */
export type ErrorCode = 'NOT_FOUND' | 'ENOENT' | 'ALREADY_EXISTS' | 'EEXIST' | 'PERMISSION_DENIED' | 'EACCES' | 'VALIDATION_ERROR' | 'RESTRICTED_PATH' | 'INTERNAL_ERROR' | 'EISDIR' | 'ENOTDIR' | 'ENOSPC';
/**
 * MCP-compatible error shape for JSON responses.
 */
export interface MCPError {
    code: ErrorCode;
    message: string;
    path?: string;
    suggestion?: string;
}
/**
 * Custom error class for document operations.
 * Extends Error with code, path, suggestion, and JSON serialization.
 */
export declare class DocumentError extends Error {
    readonly code: ErrorCode;
    readonly path?: string;
    readonly suggestion?: string;
    constructor(code: ErrorCode, message: string, path?: string, suggestion?: string);
    /**
     * Convert to MCP-compatible JSON shape.
     */
    toJSON(): MCPError;
}
/**
 * Factory: File not found error.
 *
 * @param path - Path to the file that was not found
 * @param suggestion - Optional custom suggestion
 * @returns DocumentError with NOT_FOUND code
 * @example
 * throw notFound('research/missing.md');
 * // DocumentError: File not found: research/missing.md
 */
export declare function notFound(path: string, suggestion?: string): DocumentError;
/**
 * Factory: Directory not found error.
 *
 * @param path - Path to the directory that was not found
 * @returns DocumentError with ENOENT code
 */
export declare function directoryNotFound(path: string): DocumentError;
/**
 * Factory: Cannot read directory as file error.
 *
 * @param path - Path that is a directory, not a file
 * @returns DocumentError with EISDIR code
 */
export declare function isDirectoryError(path: string): DocumentError;
/**
 * Factory: Not a directory error.
 *
 * @param path - Path that points to a file, not a directory
 * @returns DocumentError with ENOTDIR code
 */
export declare function notDirectoryError(path: string): DocumentError;
/**
 * Factory: File already exists error.
 *
 * @param path - Path to the file that already exists
 * @returns DocumentError with ALREADY_EXISTS code
 * @example
 * throw alreadyExists('addendums/001-existing.md');
 * // DocumentError: File already exists: addendums/001-existing.md
 */
export declare function alreadyExists(path: string): DocumentError;
/**
 * Factory: Permission denied error.
 *
 * @param path - Path to the file
 * @param reason - Reason for the permission denial
 * @param operation - Operation that was denied (read, write, delete, etc.)
 * @returns DocumentError with EACCES code
 * @example
 * throw permissionDenied('config.json', 'File is read-only', 'write');
 * // DocumentError: Permission denied: config.json. The file exists but cannot be written due to filesystem permissions.
 */
export declare function permissionDenied(path: string, reason?: string, operation?: string): DocumentError;
/**
 * Factory: Restricted path error.
 *
 * @param path - Path that is restricted
 * @returns DocumentError with RESTRICTED_PATH code
 * @example
 * throw restrictedPath('.git/config');
 * // DocumentError: Cannot access restricted path: .git/config
 */
export declare function restrictedPath(path: string): DocumentError;
/**
 * Factory: Validation error.
 *
 * @param field - Name of the field that failed validation
 * @param message - Description of the validation failure
 * @returns DocumentError with VALIDATION_ERROR code
 * @example
 * throw validationError('path', 'must be relative to repo root');
 * // DocumentError: Validation failed for 'path': must be relative to repo root
 */
export declare function validationError(field: string, message: string): DocumentError;
/**
 * Factory: No space left on device error.
 *
 * @param path - Path where write failed
 * @returns DocumentError with ENOSPC code
 */
export declare function noSpaceError(path: string): DocumentError;
/**
 * Error thrown when recursion depth limit is exceeded.
 * Used by RLM sub-call processing.
 */
export declare class DepthLimitError extends Error {
    readonly maxDepth: number;
    readonly currentDepth: number;
    constructor(maxDepth: number, currentDepth: number);
}
/**
 * Options for constructing a LimpsError.
 */
export interface LimpsErrorOptions {
    /** Error code for categorization */
    code?: string;
    /** Suggestions to help the user fix the issue */
    suggestions?: string[];
    /** Original error that caused this one */
    cause?: Error;
}
/**
 * Custom error class for CLI operations.
 * Extends Error with code, suggestions, and JSON serialization for --json output.
 */
export declare class LimpsError extends Error {
    readonly code: string;
    readonly suggestions: string[];
    constructor(message: string, options?: LimpsErrorOptions);
    /**
     * Convert to JSON envelope error format.
     */
    toJson(): JsonError;
}
/**
 * Factory: Task not found error with suggestions.
 *
 * @param taskId - The task ID that was not found
 * @param availableAgents - List of available agent identifiers for suggestions
 * @returns LimpsError with TASK_NOT_FOUND code and did-you-mean suggestions
 *
 * @example
 * throw taskNotFoundError('0001#999', ['0001#000', '0001#001', '0001#002']);
 */
export declare function taskNotFoundError(taskId: string, availableAgents: string[]): LimpsError;
/**
 * Factory: Plan not found error with suggestions.
 *
 * @param planId - The plan ID that was not found
 * @param availablePlans - List of available plan identifiers for suggestions
 * @returns LimpsError with PLAN_NOT_FOUND code and did-you-mean suggestions
 *
 * @example
 * throw planNotFoundError('99', ['0001-network-panel', '0002-auth-system']);
 */
export declare function planNotFoundError(planId: string, availablePlans: string[]): LimpsError;
//# sourceMappingURL=errors.d.ts.map