/**
 * shell-rc.ts — Idempotent shell-rc file append + timestamped backup.
 *
 * Phase C1 of olam-operator-onboarding-parity (plan
 * ~/.claude/plans/olam-operator-onboarding-parity.md).
 *
 * Phase C's `olam setup` wizard offers to add
 *   eval "$(olam completion zsh)"
 * to the operator's `~/.zshrc` / `~/.bashrc`. This module is the safety
 * layer that:
 *
 *   1. Grep-checks a marker substring before writing — re-running the
 *      wizard is a no-op (no duplicate eval lines, no n-times appended).
 *   2. Backs the file up to `<rcPath>.olam-bak.<ISO-timestamp>` before
 *      ANY mutation — recoverable if the operator decides they didn't
 *      want the line.
 *   3. Writes atomically via tmp-file + rename — `kill -9` mid-write
 *      can't leave a half-written rc file.
 *
 * Decision 6 (plan): mirrors adb's `phase_mise_activation` pattern; the
 * idempotency + backup pair is the operator-UX floor.
 *
 * Risk T4 mitigation (per plan + design doc): the grep-for-marker check
 * uses `String.includes` not a per-line scan — a marker can match across
 * whitespace if needed. The backup runs unconditionally before the
 * append; corrupted rc states are recoverable via `mv <backup> <rcPath>`.
 */
export type AppendStatus = 'appended' | 'already-present' | 'no-rc-file';
export interface AppendResult {
    readonly status: AppendStatus;
    /** Path to the timestamped backup file. `null` when `status !== 'appended'`. */
    readonly backupPath: string | null;
}
export interface AppendOptions {
    /** Absolute path to the operator's shell rc (e.g. `/Users/me/.zshrc`). */
    readonly rcPath: string;
    /**
     * Substring searched for in the rc to detect "already present."
     * Convention: a short stable token (e.g. `olam completion`) — distinct
     * enough to avoid collisions with unrelated mentions, short enough that
     * the operator can edit the exact line shape without breaking
     * idempotency.
     */
    readonly marker: string;
    /**
     * The exact line to append. The function adds a trailing newline if
     * not already present + ensures the previous line of the rc file ends
     * with a newline (so the appended line isn't concatenated onto the
     * previous line on rcs that don't end with `\n`).
     */
    readonly contentLine: string;
    /**
     * Optional clock override for deterministic test timestamps. Defaults
     * to `() => new Date()`.
     */
    readonly clock?: () => Date;
}
/**
 * Append `contentLine` to `rcPath` exactly once.
 *
 *   - rcPath doesn't exist           → returns `{status: 'no-rc-file', backupPath: null}`
 *   - rcPath content already includes the marker substring
 *                                    → returns `{status: 'already-present', backupPath: null}`
 *   - otherwise: backup + append
 *                                    → returns `{status: 'appended', backupPath: <ts-path>}`
 *
 * The write is atomic: content is staged to `<rcPath>.olam-tmp.<pid>`
 * and then `renameSync`'d to `rcPath`. POSIX rename is atomic within a
 * filesystem; a `kill -9` mid-call leaves either the backup-only state
 * (no rc change) or the renamed-final state (atomic apply), never a
 * half-written rc.
 *
 * The backup path uses a filesystem-safe ISO timestamp with `:` + `.`
 * replaced by `-` (avoids colons in filenames on Windows for cross-
 * platform consumers; not strictly required on macOS / Linux but
 * cosmetically nicer).
 */
export declare function appendIdempotent(opts: AppendOptions): AppendResult;
/**
 * Resolve the operator's shell rc path based on `$SHELL`.
 *
 *   /bin/zsh, /usr/bin/zsh, /opt/homebrew/bin/zsh → ~/.zshrc
 *   /bin/bash, /usr/bin/bash                     → ~/.bashrc
 *   anything else                                → null (caller must surface)
 *
 * The caller decides what to do on null — typically Phase C surfaces a
 * remedy message naming the supported shells.
 */
export declare function resolveShellRc(home: string, shellEnv: string | undefined): string | null;
//# sourceMappingURL=shell-rc.d.ts.map