/**
 * Folder Filesystem Client
 *
 * Filesystem layer for the folder sync provider. Reads, writes, and lists
 * markdown files with YAML frontmatter in a local directory tree.
 *
 * Follows the same API client pattern as github-api.ts — a focused,
 * dependency-light module that handles I/O for a single provider.
 *
 * Uses the `yaml` package for frontmatter parsing/serialization.
 */
/**
 * YAML frontmatter fields recognized by the folder sync provider.
 * Additional fields are preserved as-is during round-trips.
 */
export interface FolderFrontmatter {
    /** Stoneforge element ID linked to this file */
    'stoneforge-id'?: string;
    /** Document category */
    category?: string;
    /** Tags for classification */
    tags?: string[];
    /** ISO 8601 timestamp of last sync */
    'synced-at'?: string;
    /** Additional arbitrary frontmatter fields (preserved on round-trip) */
    [key: string]: unknown;
}
/**
 * Result of reading a markdown file with frontmatter
 */
export interface FolderFileReadResult {
    /** Markdown body content (without frontmatter) */
    readonly content: string;
    /** Parsed YAML frontmatter (empty object if none) */
    readonly frontmatter: FolderFrontmatter;
    /** File modification time as Unix timestamp (milliseconds) */
    readonly mtime: number;
}
/**
 * Entry returned when listing files in a folder
 */
export interface FolderFileEntry {
    /** Path relative to the base directory (forward slashes) */
    readonly path: string;
    /** File modification time as Unix timestamp (milliseconds) */
    readonly mtime: number;
}
/**
 * Options for listing files
 */
export interface ListFilesOptions {
    /**
     * Only return files modified after this Unix timestamp (milliseconds).
     * Compares against the file's mtime.
     */
    since?: number;
}
/**
 * Typed error for folder filesystem failures.
 */
export declare class FolderFsError extends Error {
    /** The operation that failed */
    readonly operation: 'read' | 'write' | 'list';
    /** The file path involved (if applicable) */
    readonly filePath: string | null;
    /** The underlying system error code (e.g., 'ENOENT', 'EACCES') */
    readonly code: string | null;
    constructor(message: string, operation: 'read' | 'write' | 'list', filePath?: string | null, code?: string | null, cause?: Error);
    /**
     * Whether this error is due to a missing file or directory
     */
    get isNotFound(): boolean;
    /**
     * Whether this error is due to a permission issue
     */
    get isPermissionError(): boolean;
}
/**
 * Type guard for FolderFsError
 */
export declare function isFolderFsError(error: unknown): error is FolderFsError;
/**
 * Parses YAML frontmatter from a markdown string.
 *
 * Expects the standard `---` delimited frontmatter block at the start of the file.
 * Returns the body content and parsed frontmatter separately.
 *
 * @param raw - Raw file content (may or may not have frontmatter)
 * @returns Parsed frontmatter and body content
 */
export declare function parseFrontmatter(raw: string): {
    content: string;
    frontmatter: FolderFrontmatter;
};
/**
 * Serializes frontmatter and content into a markdown string with YAML front matter.
 *
 * @param content - Markdown body content
 * @param frontmatter - Frontmatter key-value pairs
 * @returns Complete file content with frontmatter block
 */
export declare function serializeFrontmatter(content: string, frontmatter: FolderFrontmatter): string;
/**
 * Reads a markdown file with YAML frontmatter from a folder.
 *
 * @param basePath - Absolute path to the base directory
 * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
 * @returns Parsed file content, frontmatter, and modification time
 * @throws {FolderFsError} If the file cannot be read
 */
export declare function readFile(basePath: string, relativePath: string): Promise<FolderFileReadResult>;
/**
 * Writes a markdown file with YAML frontmatter to a folder.
 *
 * Writes atomically by first writing to a temporary file in the same directory,
 * then renaming. This prevents partial writes from corrupting files.
 *
 * @param basePath - Absolute path to the base directory
 * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
 * @param content - Markdown body content
 * @param frontmatter - YAML frontmatter key-value pairs
 * @throws {FolderFsError} If the file cannot be written
 */
export declare function writeFile(basePath: string, relativePath: string, content: string, frontmatter: FolderFrontmatter): Promise<void>;
/**
 * Recursively lists all `.md` files in a directory tree.
 *
 * Excludes:
 * - Dotfiles (files starting with `.`)
 * - Files inside dot-directories (directories starting with `.`)
 *
 * @param basePath - Absolute path to the base directory
 * @param options - Optional filtering (e.g., `since` timestamp)
 * @returns Array of file entries with relative paths and modification times
 * @throws {FolderFsError} If the directory cannot be read
 */
export declare function listFiles(basePath: string, options?: ListFilesOptions): Promise<FolderFileEntry[]>;
/**
 * Checks whether a file exists at the given relative path within a base directory.
 *
 * @param basePath - Absolute path to the base directory
 * @param relativePath - Path relative to basePath (e.g., 'notes/meeting.md')
 * @returns True if the file exists, false otherwise
 */
export declare function fileExists(basePath: string, relativePath: string): Promise<boolean>;
//# sourceMappingURL=folder-fs.d.ts.map