/**
 * File utility helpers for CLEO data access.
 *
 * File utility helpers for CLEO data access including atomic writes,
 * file locking, and backup rotation.
 *
 * @task T4833
 * @epic T4654
 */
/**
 * Options for `writeJsonFileAtomic`.
 *
 * @task T-LLM-CRED-CENTRALIZATION Phase 2 — security review S-01/S-02
 */
export interface WriteJsonFileAtomicOptions {
    /** JSON indentation passed through to `JSON.stringify`. Defaults to `2`. */
    indent?: number;
    /**
     * Optional file mode for the temp + backup writes.
     *
     * When set, the temp file is created at this mode so the atomic rename
     * never exposes the live file at a looser mode (closes the TOCTOU
     * window between `rename(2)` and a follow-up `chmod`). The rotated
     * backup under `.backups/` is written at the same mode so historical
     * copies of secret data are equally locked down. The parent
     * `.backups/` directory is auto-created at the matching directory mode
     * (see {@link modeToDirMode}).
     *
     * REQUIRED for credential / secret storage. Omit for general data
     * files where 0644 is acceptable.
     */
    mode?: number;
}
/**
 * Write a JSON file atomically with backup rotation.
 *
 * Pattern: write temp -> backup original -> rename temp to target
 *
 * When `opts.mode` is provided, the temp file AND the rotated backup
 * are both created at that mode so there is no instant at which the
 * live file (or any historical copy) exists at a looser mode. This is
 * REQUIRED for secret-bearing files such as `llm-credentials.json`;
 * passing 0o600 closes CWE-276 (incorrect default permissions) and
 * CWE-367 (rename → chmod TOCTOU) together.
 *
 * Back-compat: callers that omit `opts` (or pass a number, for the old
 * `indent` positional form) get the legacy default-umask behavior so no
 * existing usage changes.
 *
 * @param filePath - Target file path.
 * @param data - Data to serialize as JSON.
 * @param optsOrIndent - Options object, or a number for legacy `indent`
 *   positional form.
 *
 * @task T-LLM-CRED-CENTRALIZATION Phase 2 — security review S-01/S-02
 */
export declare function writeJsonFileAtomic<T>(filePath: string, data: T, optsOrIndent?: WriteJsonFileAtomicOptions | number): void;
/**
 * Read a JSON file, returning parsed content or null if not found.
 *
 * @param filePath - Path to the JSON file
 */
export declare function readJsonFile<T = unknown>(filePath: string): T | null;
/**
 * Get the path to a CLEO data file within a project root.
 *
 * @param projectRoot - Root directory of the project
 * @param filename - Filename within .cleo/ directory
 */
export declare function getDataPath(projectRoot: string, filename: string): string;
/**
 * Resolve the project root directory.
 *
 * Delegates to {@link getProjectRoot} which honours `CLEO_ROOT`,
 * `CLEO_PROJECT_ROOT`, `CLEO_DIR`, AsyncLocalStorage worktree scope, and the
 * `.cleo/` ancestor walk. This is the canonical SSoT for project-root lookup.
 */
export declare function resolveProjectRoot(): string;
/**
 * Options for `withLock`.
 *
 * @task T-LLM-CRED-CENTRALIZATION Phase 2 — security review S-01/S-02/S-03
 */
export interface WithLockOptions {
    /**
     * Optional file mode propagated through to the atomic write AND used for
     * the proper-lockfile sentinel empty-file create. The parent directory is
     * created at the matching directory mode (see {@link modeToDirMode}) so a
     * 0600 file is not enumerable through a 0755 parent dir.
     *
     * REQUIRED for credential / secret storage paths.
     */
    mode?: number;
}
/**
 * Read and write a JSON file with exclusive locking.
 *
 * Acquires a cross-process lock, reads current state, applies the
 * transform function, validates, and writes back atomically.
 *
 * When `opts.mode` is provided, every filesystem mutation in this path
 * (parent dir create, sentinel empty file, atomic write, rotated backup)
 * is constrained to the requested mode so secret-bearing data never
 * touches the disk at a looser permission.
 *
 * @param filePath - File to lock and modify.
 * @param transform - Function that receives current data and returns new data.
 * @param opts - Optional mode override for secret-bearing writes.
 * @returns The transformed data.
 *
 * @task T-LLM-CRED-CENTRALIZATION Phase 2 — security review S-01/S-02/S-03
 */
export declare function withLock<T>(filePath: string, transform: (current: T | null) => T, opts?: WithLockOptions): Promise<T>;
/**
 * Acquire a file lock and execute an operation.
 * Unlike withLock, this doesn't read/write the file - caller manages I/O.
 * The return type R is independent of the file content type.
 */
export declare function withFileLock<R>(filePath: string, operation: () => R | Promise<R>): Promise<R>;
/**
 * Acquire locks on multiple files in correct order.
 * Used for operations that need to modify multiple files atomically
 * (e.g., coordinated updates across task data and config).
 *
 * @param filePaths - Files to lock
 * @param operation - Function to execute while locks are held
 */
export declare function withMultiLock<T>(filePaths: string[], operation: () => T | Promise<T>): Promise<T>;
/**
 * Check if a CLEO project directory exists at the given path
 */
export declare function isProjectInitialized(projectRoot: string): boolean;
/**
 * List backup files for a given data file
 */
export declare function listBackups(filePath: string): string[];
//# sourceMappingURL=file-utils.d.ts.map