/**
 * Single source of truth for every path the wizard reads or writes.
 *
 * Two storage roots:
 *
 *   1. Per-user cache root — `~/.amplitude/wizard/`
 *      Houses logs, checkpoints, benchmarks, plans, agent state, update-check
 *      cache. Per-project files live under `runs/<sha256(installDir)>/` so two
 *      parallel wizard instances in different directories can't collide on a
 *      shared log file.
 *
 *      Override with `AMPLITUDE_WIZARD_CACHE_DIR` env var (used by tests and
 *      by users who want the cache somewhere else).
 *
 *   2. Per-project metadata dir — `<installDir>/.amplitude/`
 *      Houses artifacts the user is meant to see and may want to commit or
 *      keep locally: `events.json` (approved event plan),
 *      `project-binding.json` (wizard org/project/source binding), and
 *      `dashboard.json` (dashboard URL — often gitignored as machine-local).
 *
 * Per-user OAuth session (access/refresh tokens) lives in the cache root as
 * `oauth-session.json` (mode `0o600`). Legacy `~/.ampli.json` is still read
 * once for migration and kept in sync on write until fully retired.
 *
 * Project binding is also written to `<installDir>/ampli.json` during
 * transition so older tooling that still looks there continues to work.
 *
 * Unchanged paths:
 *   - `<installDir>/.env.local` — API key fallback
 *
 * Recently moved into the per-user cache root:
 *   - `~/.amplitude/wizard/credentials.json` — Amplitude project API keys,
 *     keyed by hashed install dir. Replaces the macOS Keychain / Linux
 *     `secret-tool` storage that triggered an OS unlock prompt on every
 *     launch (the wizard's project API key is a public ingestion key
 *     embedded in client SDK bundles, so file-on-disk at `0o600` matches
 *     its actual sensitivity — same precedent as the OAuth session file).
 */
/** Env var that overrides the cache root. Primarily for tests. */
export declare const CACHE_ROOT_OVERRIDE_ENV = "AMPLITUDE_WIZARD_CACHE_DIR";
/**
 * Per-user cache root. Defaults to `~/.amplitude/wizard/`. Honors
 * `AMPLITUDE_WIZARD_CACHE_DIR` for test isolation and power users.
 */
export declare function getCacheRoot(): string;
/**
 * Stable 12-char hex identifier for an install directory. Matches the
 * convention previously inlined in `session-checkpoint.ts` so existing
 * checkpoints remain addressable after migration.
 *
 * Normalization (so symlink/trailing-slash/case variants of the same
 * project hash to the same directory):
 *   1. Resolve symlinks via `realpathSync`. Falls back to the raw input
 *      if the path doesn't exist yet (ENOENT) or we can't read it
 *      (EACCES) — those are best-effort, not blockers.
 *   2. Strip trailing path separators so `/foo/bar` and `/foo/bar/`
 *      hash identically.
 */
export declare function projectHash(installDir: string): string;
/** Per-project run dir: `<cacheRoot>/runs/<hash>/`. */
export declare function getRunDir(installDir: string): string;
/** Human-readable log file. */
export declare function getLogFile(installDir: string): string;
/** Structured (NDJSON) log mirror. */
export declare function getStructuredLogFile(installDir: string): string;
/** Benchmark middleware output. */
export declare function getBenchmarkFile(installDir: string): string;
/** Crash-safe session checkpoint. */
export declare function getCheckpointFile(installDir: string): string;
/**
 * Build a dated installation-error log path. Each `npm install` failure gets
 * its own file under the project's run dir so the support bundle picks them
 * up without polluting the user's project root.
 */
export declare function getInstallationErrorLogFile(installDir: string): string;
/**
 * Per-project apply lockfile. Carries the pid + start timestamp of an
 * in-flight `wizard apply` so a second concurrent invocation can detect
 * it and refuse cleanly. Lives under the per-project run dir so two
 * applies in DIFFERENT projects don't collide. The skill rule alone
 * ("never spawn a second apply") isn't enforceable on the agent side —
 * this binary-side guard catches it regardless of which orchestrator
 * is driving the wizard.
 */
export declare function getApplyLockFile(installDir: string): string;
/** Plans dir (`<cacheRoot>/plans/`). One JSON file per plan ID. */
export declare function getPlansDir(): string;
/** Resolve a plan file path from its ID. */
export declare function getPlanFile(planId: string): string;
/**
 * Per-attempt agent recovery snapshot. Scoped by both `attemptId` AND the
 * owning process's pid so a crashed-prior-run snapshot can't be silently
 * picked up by a fresh process that happens to reuse the same attempt id.
 *
 * The pid suffix is the load-bearing piece: PreCompact persists state for
 * the current run, and the post-compaction UserPromptSubmit hook reads it
 * back inside the SAME process. A different process should never hydrate
 * from another process's snapshot, even if attempt ids collide.
 */
export declare function getStateFile(attemptId: string, pid?: number): string;
/** Per-user npm registry latest-version cache. */
export declare function getUpdateCheckFile(): string;
/**
 * Per-user credentials file holding Amplitude project API keys, keyed by
 * hashed install dir. Always written at mode `0o600`. Replaces the previous
 * macOS Keychain / Linux `secret-tool` storage (which prompted on every read).
 */
export declare function getCredentialsFile(): string;
/**
 * Per-user OAuth session file (tokens + wizard `User-*` entries).
 * Always written at mode `0o600`.
 */
export declare function getOAuthSettingsFile(): string;
/**
 * Legacy per-user OAuth file. Read for one-shot migration; still updated on
 * write so older workflows that expect this path keep working during transition.
 */
export declare function getLegacyAmpliHomeOAuthPath(): string;
/**
 * Path for a downloaded skill bundle (zip). Lives under `os.tmpdir()` because
 * it's a transient download immediately extracted into `<installDir>/.claude/`.
 * `os.tmpdir()` is used (not literal `/tmp/`) so the wizard works on Windows.
 */
export declare function skillDownloadPath(skillId: string): string;
/** Per-project metadata dir: `<installDir>/.amplitude/`. */
export declare function getProjectMetaDir(installDir: string): string;
/** Approved event plan written by `confirm_event_plan`. Persists across runs. */
export declare function getEventsFile(installDir: string): string;
/** Dashboard URL JSON written by the agent after dashboard creation. */
export declare function getDashboardFile(installDir: string): string;
/**
 * Canonical wizard project binding (org, project, source, zone, app id, etc.).
 * Legacy `ampli.json` in the project root is still read/written during transition.
 */
export declare function getProjectBindingFile(installDir: string): string;
/**
 * Pick the freshest existing file from a list of candidate paths, comparing
 * by mtime. Used to prefer the canonical project-meta path over a legacy
 * fallback when both exist. Returns `null` if none of the paths point at a
 * regular file.
 *
 * Intentionally lives in `storage-paths.ts` (zero non-stdlib deps) so the
 * intro / outro screens can depend on it without dragging in the heavier
 * `agent-interface.ts` dep graph for what is fundamentally a 5-line stat
 * loop.
 */
export declare function pickFreshestExisting(paths: readonly string[]): string | null;
/**
 * Best-effort recursive mkdir. The caller should not depend on the return
 * value; failures are silent (most consumers race the directory and the
 * subsequent file write surfaces a more useful error). Cache directories
 * are created with `0o700` so the cache root and per-run dirs are owner-only.
 */
export declare function ensureDir(dir: string, mode?: number): void;
/**
 * Pre-refactor paths. Kept here so the startup migration shim has a single
 * source of truth for "where the old layout used to put things." Drop after
 * one release.
 *
 * NB: `log` and `logl` are deliberately hardcoded to `/tmp/...` even though
 * `tmpdir()` returns `/var/folders/...` on macOS. The OLD logger always
 * wrote to the literal `/tmp/amplitude-wizard.log` (see git blame on
 * `src/lib/observability/logger.ts` before this refactor); macOS resolves
 * `/tmp` as a symlink to `/private/tmp` transparently for both reads and
 * writes, so the migration finds whatever the old logger wrote.
 */
export declare const LEGACY_PATHS: {
    /** Hardcoded global log (collided across parallel runs). */
    readonly log: "/tmp/amplitude-wizard.log";
    readonly logl: "/tmp/amplitude-wizard.logl";
    /**
     * Global benchmark file (was clobbered across projects). Hardcoded
     * to literal `/tmp/` to match the old `middleware/config.ts` default
     * (`benchmarkPath: '/tmp/amplitude-wizard-benchmark.json'`). On macOS
     * `tmpdir()` is `/var/folders/...`, so deriving from it would have
     * silently missed the legacy file during migration.
     */
    readonly benchmark: "/tmp/amplitude-wizard-benchmark.json";
    /** Per-project checkpoint, tmpdir-scoped. */
    readonly checkpoint: (hash: string) => string;
    /** Per-attempt agent state, tmpdir-scoped. */
    readonly state: (attemptId: string) => string;
    /** Plans dir, tmpdir-scoped. */
    readonly plansDir: () => string;
    /** Update-check cache, tmpdir-scoped. */
    readonly updateCheck: () => string;
    /** Per-project events file, dotfile in install dir. */
    readonly events: (installDir: string) => string;
    /** Per-project dashboard file, dotfile in install dir. */
    readonly dashboard: (installDir: string) => string;
};
