/**
 * Filesystem location resolution for the application.
 *
 * This module collapses what would otherwise be a scattered pile of free
 * `getProfileDir()` / `getSettingsPath()` / `getSessionsDir()` path helpers into
 * a single {@link Locator} class. Every location the app touches — the per-user
 * profile directory, the global and per-project settings files, the sessions and
 * logs directories, the credential store — is computed by one method, all
 * deriving from two roots (the user's home and the current working directory)
 * and the {@link BRAND} naming constants.
 *
 * The constructor takes optional overrides for `home`, `cwd`, and `env`, so a
 * test (or an embedder) can sandbox the locator entirely: point `home` at a
 * temp directory, hand it a synthetic `env`, and every resolved path lands
 * inside the sandbox with no global state involved. With no overrides it falls
 * back to {@link os.homedir}, {@link process.cwd}, and {@link process.env}.
 *
 * The path-returning methods are *pure* — they only join strings and never touch
 * disk. The handful of `ensure*` helpers (backed by `fs/promises`) are the only
 * members that perform I/O, and they exist purely so callers don't have to
 * `mkdir -p` a directory before writing into it.
 *
 * Environment override:
 *   - `INDUSAGI_HOME` (i.e. `<envPrefix>HOME`) — when set and non-empty, it
 *     supersedes the OS home directory as the root of the profile. This lets a
 *     user relocate all per-user state without touching `$HOME` itself.
 */
import { type Brand } from "./brand";
/**
 * Optional roots and environment a {@link Locator} resolves against. Anything
 * omitted falls back to the live process: `home` → `os.homedir()`, `cwd` →
 * `process.cwd()`, `env` → `process.env`.
 */
export interface LocatorOverrides {
    /** Root for per-user state. Defaults to the OS home directory. */
    readonly home?: string;
    /** The working directory project paths resolve against. Defaults to `process.cwd()`. */
    readonly cwd?: string;
    /** The environment table consulted for overrides. Defaults to `process.env`. */
    readonly env?: NodeJS.ProcessEnv;
}
/**
 * Resolves every filesystem location the application uses from a small set of
 * roots plus the {@link BRAND} naming constants.
 *
 * Construct one per process (or one per sandbox in tests). All path methods are
 * pure and cheap; the `ensure*` methods are the only ones that touch disk.
 */
export declare class Locator {
    private readonly home;
    private readonly cwd;
    private readonly env;
    private readonly brand;
    /**
     * @param overrides Optional `home`/`cwd`/`env` to sandbox resolution. Each
     *   field independently falls back to the live process when omitted.
     * @param brand The naming source of truth. Defaults to the canonical
     *   {@link BRAND}; injectable so an alternate identity can be resolved against
     *   without mutating the global.
     */
    constructor(overrides?: LocatorOverrides, brand?: Brand);
    /**
     * Determine the home root, in precedence order:
     *   1. an explicit `home` override passed to the constructor;
     *   2. the `<envPrefix>HOME` environment variable, if present and non-empty;
     *   3. the OS home directory from {@link os.homedir}.
     */
    private resolveHome;
    /** Read an env var through the bound table, treating empty as absent. */
    private readEnv;
    /**
     * The per-user profile directory — the dot-directory under the home root that
     * holds all per-user state (e.g. `~/.indusagi`). Every home-rooted path below
     * is computed relative to this.
     */
    profileDir(): string;
    /** The global settings file inside the profile (e.g. `~/.indusagi/settings.json`). */
    settingsPath(): string;
    /**
     * The per-project settings file for a given working directory.
     *
     * Resolves `cwd` against the locator's own working directory (so a relative
     * argument is interpreted sensibly), then places the project settings file
     * inside that project's dot-directory — e.g. `<project>/.indusagi/settings.json`.
     *
     * @param cwd The project root to resolve against. Defaults to the locator's
     *   bound working directory.
     */
    projectSettingsPath(cwd?: string): string;
    /** Directory holding persisted conversation sessions (e.g. `~/.indusagi/sessions`). */
    sessionsDir(): string;
    /** The credential/auth store file inside the profile (e.g. `~/.indusagi/auth.json`). */
    authStorePath(): string;
    /** Directory holding diagnostic and crash logs (e.g. `~/.indusagi/logs`). */
    logsDir(): string;
    /**
     * Ensure the profile directory exists, creating it (and any missing parents)
     * if absent. Returns the directory path for convenient chaining.
     */
    ensureProfileDir(): Promise<string>;
    /**
     * Ensure the sessions directory exists, creating it if absent. Returns the
     * directory path.
     */
    ensureSessionsDir(): Promise<string>;
    /**
     * Ensure the logs directory exists, creating it if absent. Returns the
     * directory path.
     */
    ensureLogsDir(): Promise<string>;
    /**
     * Ensure the parent directory of a file path exists, then return the original
     * file path. Use before writing a file (settings, auth store) so the write
     * never fails on a missing directory.
     */
    ensureParentOf(filePath: string): Promise<string>;
    /**
     * Create a directory (and any missing parents) idempotently, returning its
     * path. The shared primitive behind every `ensure*` method above.
     */
    ensureDir(dir: string): Promise<string>;
}
