/**
 * Virtual filesystem manager.
 *
 * Coordinates multiple virtual file handlers to provide a unified
 * interface for reading, writing, and listing files that may have
 * different physical representations.
 */
import type { KnowledgeManager } from "../../knowledge/knowledge-manager.js";
import type { VirtualFileHandler, VirtualPathInfo, VirtualReadOptions, VirtualWriteOptions, VirtualDeleteOptions } from "./virtual-fs-types.js";
/**
 * Manages virtual file handlers and routes operations to the appropriate handler.
 *
 * Usage:
 * ```typescript
 * const vfs = new VirtualFileSystem();
 * vfs.registerHandler(new ApiFileHandler());
 *
 * // Check if a path is virtual
 * if (vfs.isVirtualPath("apis/MyAPI.ts")) {
 *   const content = await vfs.read("apis/MyAPI.ts", options);
 * }
 * ```
 */
export declare class VirtualFileSystem {
    private handlers;
    private disabledTypes;
    /**
     * Register a handler for a type of virtual file.
     *
     * @param handler - The handler to register
     */
    registerHandler(handler: VirtualFileHandler): void;
    /**
     * Get all registered handlers (including any currently disabled).
     */
    getHandlers(): readonly VirtualFileHandler[];
    private activeHandlers;
    /**
     * Toggle a handler on/off at runtime without unregistering it. When disabled,
     * the handler is skipped by all lookup/read/write operations and reads fall
     * through to the raw disk path. Used to bypass API projection during v2→v3
     * migration so Clark reads the raw YAML sources instead of the generated TS.
     */
    setHandlerEnabled(type: string, enabled: boolean): void;
    isHandlerEnabled(type: string): boolean;
    /**
     * Find the handler for a virtual path.
     *
     * @param virtualPath - The virtual path to look up
     * @returns The matching handler, or undefined if none match
     */
    getHandler(virtualPath: string): VirtualFileHandler | undefined;
    /**
     * Find the handler for a physical path.
     *
     * @param physicalPath - The physical path to look up
     * @returns The matching handler, or undefined if none match
     */
    getHandlerForPhysical(physicalPath: string): VirtualFileHandler | undefined;
    /**
     * Check if a path is a virtual path managed by any handler.
     *
     * @param path - The path to check
     * @returns true if any handler manages this path
     */
    isVirtualPath(path: string): boolean;
    /**
     * Check if a path is a physical path that should be blocked from direct reads.
     *
     * Physical paths are the underlying files that make up virtual files
     * (e.g., apis/MyAPI/api.yaml, apis/MyAPI/step_1.js). These should not
     * be read directly; instead, the virtual path (apis/MyAPI.ts) should be used.
     *
     * @param path - The path to check
     * @returns true if this is a physical path that should be blocked
     */
    isPhysicalPath(path: string): boolean;
    /**
     * Get error message for attempting to read a physical path directly.
     *
     * @param physicalPath - The physical path that was attempted to be read
     * @returns Error message pointing to the virtual path
     */
    getBlockedReadError(physicalPath: string): string;
    /**
     * Parse a virtual path to extract metadata.
     *
     * @param virtualPath - The virtual path to parse
     * @returns Parsed info or undefined if not a virtual path
     */
    parse(virtualPath: string): VirtualPathInfo | undefined;
    /**
     * Convert a physical path to its virtual representation.
     *
     * @param physicalPath - The physical path to convert
     * @returns The virtual path, or the original path if not managed by any handler
     */
    toVirtualPath(physicalPath: string): string;
    /**
     * Convert a list of physical paths to virtual paths, deduplicating as needed.
     *
     * @param physicalPaths - The physical paths to convert
     * @returns Array of virtual paths (deduplicated)
     */
    toVirtualPaths(physicalPaths: string[]): string[];
    /**
     * Read content from a virtual file.
     *
     * @param virtualPath - The virtual path to read
     * @param options - Read options
     * @returns The file content, or undefined if not found or not a virtual path
     */
    read(virtualPath: string, options: VirtualReadOptions): Promise<string | undefined>;
    /**
     * Write content to a virtual file.
     *
     * @param virtualPath - The virtual path to write
     * @param content - The content to write
     * @param options - Write options
     * @throws Error if path is not managed by any handler
     */
    write(virtualPath: string, content: string, options: VirtualWriteOptions): Promise<void>;
    /**
     * Delete a virtual file.
     *
     * @param virtualPath - The virtual path to delete
     * @param options - Delete options
     * @returns List of physical paths that were deleted
     * @throws Error if path is not managed by any handler
     */
    delete(virtualPath: string, options: VirtualDeleteOptions): Promise<string[]>;
}
/**
 * Create a VirtualFileSystem with the default handlers registered.
 *
 * @param options - Optional configuration including feature flags
 */
export declare function createDefaultVirtualFileSystem(options?: {
    useSystemSkills?: boolean;
    knowledgeManager?: KnowledgeManager;
    sdkApiEnabled?: boolean;
    appRootDirPath?: string;
}): VirtualFileSystem;
//# sourceMappingURL=virtual-file-system.d.ts.map