/**
 * Configuration I/O — load, save, validate, and migrate SKYKOI config files.
 *
 * Handles the full config lifecycle:
 * - Reading JSON5 config from disk with environment variable substitution
 * - Schema validation via Zod with human-readable error messages
 * - Default application and legacy field migration
 * - Atomic writes with backup rotation (5-deep ring)
 * - Shell environment fallback for PATH resolution
 * - Duplicate koi directory detection
 *
 * Config files are stored as JSON5 at `~/.skykoi/config.json` (or CONFIG_PATH override).
 *
 * @module
 */
import JSON5 from "json5";
import fs from "node:fs";
import type { SKYKOIConfig, ConfigFileSnapshot } from "./types.js";
export { CircularIncludeError, ConfigIncludeError } from "./includes.js";
export { MissingEnvVarError } from "./env-substitution.js";
export type ParseConfigJson5Result = {
    ok: true;
    parsed: unknown;
} | {
    ok: false;
    error: string;
};
export declare function resolveConfigSnapshotHash(snapshot: {
    hash?: string;
    raw?: string | null;
}): string | null;
export type ConfigIoDeps = {
    fs?: typeof fs;
    json5?: typeof JSON5;
    env?: NodeJS.ProcessEnv;
    homedir?: () => string;
    configPath?: string;
    logger?: Pick<typeof console, "error" | "warn">;
};
export declare function parseConfigJson5(raw: string, json5?: {
    parse: (value: string) => unknown;
}): ParseConfigJson5Result;
/**
 * Attempt to restore a valid config from backup files when the primary config is corrupt.
 * Tries .bak, .bak.1, .bak.2, etc. in order (most recent first).
 * If a valid backup is found, copies it over the corrupt config and loads it.
 * Returns the loaded config or null if no valid backup exists.
 */
export declare function createConfigIO(overrides?: ConfigIoDeps): {
    configPath: string;
    loadConfig: () => SKYKOIConfig;
    readConfigFileSnapshot: () => Promise<ConfigFileSnapshot>;
    writeConfigFile: (cfg: SKYKOIConfig) => Promise<void>;
};
export declare function loadConfig(): SKYKOIConfig;
export declare function readConfigFileSnapshot(): Promise<ConfigFileSnapshot>;
export declare function writeConfigFile(cfg: SKYKOIConfig): Promise<void>;
/**
 * Create a backup of the current config file before a restart/update operation.
 * This ensures we have a known-good config to restore from if the restart corrupts it.
 */
export declare function backupConfigBeforeRestart(): void;
/**
 * Remove stale `.tmp` files left behind by interrupted config writes.
 * Call once at startup. Only removes files matching our naming convention
 * (`skykoi.json.<pid>.<uuid>.tmp`) that belong to PIDs no longer running.
 */
export declare function cleanupStaleConfigTmpFiles(configPath?: string): Promise<number>;