/**
 * Step-by-step progress reporting for `hikoutei setup`.
 *
 * The setup flow creates several remote Google Cloud resources and waits on
 * asynchronous IAM/ACL propagation, so a run can take minutes with no stdout
 * activity. This module renders that progress to stderr as two bars:
 *
 * - an OVERALL bar that advances one segment per completed setup phase
 *   (never a guessed percentage or an ETA — only finished work moves it);
 *   and
 * - a DETAIL bar for the bounded retry polls inside the key-settlement and
 *   service-account access-verification phases (how many of the eight
 *   propagation checks have run, and during a known wait how far through
 *   that wait the clock is) plus a fixed `working…` label for
 *   unknown-duration steps.
 *
 * The flow reports progress through a discriminated
 * {@link SetupProgressEvent} union: `resumed` (once, with the phases a
 * checkpoint guarantees), `phase_started` / `phase_completed` at phase
 * boundaries, `operation_started` / `operation_completed` around the
 * notable remote/local steps (fixed safe labels; the bounded propagation
 * checks additionally carry 1-based attempt info), `retry_wait_started`
 * before each bounded sleep, and `phase_failed` (a stable
 * {@link SetupErrorCode} only) emitted by the CLI controller when a run
 * ends in error — the flow itself returns a stable error result and never
 * knows it is the final attempt (the interactive login retry can still
 * rescue an auth preflight failure).
 *
 * Two renderers share one validating state machine:
 * - an interactive (TTY, color-capable) renderer that redraws a fixed
 *   four-line block in place with ANSI and animates a known wait through
 *   an `unref`-ed interval timer; and
 * - an append-only renderer for CI / non-TTY / `NO_COLOR` that prints a
 *   static line per phase start / phase completion / bounded-check attempt
 *   / retry wait / failure and NEVER uses control sequences, a clock tick,
 *   or a line for ordinary operation events (no log spam). The final
 *   bounded attempt (8/8) has no following wait line, so it must print its
 *   own attempt line or it would be invisible before success/failure.
 *
 * Security contract: progress events and rendered text carry ONLY fixed
 * labels, attempt/delay numbers, and stable error codes. Project ids,
 * service-account emails, owner emails, paths, access tokens, private keys,
 * key ids, raw gcloud output, and raw provider payloads are NEVER placed in
 * an event or written by a renderer. A throwing renderer callback is
 * swallowed by {@link safeProgressSink}, and the controller swallows its
 * own write/scheduler failures, so progress can never change the setup
 * result, the mutation order, or the process exit code. This module is
 * internal CLI machinery only; it is not part of the application-facing
 * API.
 */
import { type SetupErrorCode } from "./errors.js";
/** The ten setup phases in execution order. */
export declare const SETUP_PROGRESS_PHASES: readonly ["cloud_auth", "drive_access", "project", "apis", "service_account", "service_account_key", "spreadsheet", "share", "sa_access", "output"];
/** One setup phase. */
export type SetupProgressPhase = (typeof SETUP_PROGRESS_PHASES)[number] | typeof POOL_EXPANSION_PHASE;
/**
 * Credential-pool expansion phase for `--sa-count` runs with N > 1.
 *
 * Deliberately OUTSIDE {@link SETUP_PROGRESS_PHASES}: the fixed ten-phase
 * list (and its denominator) is the byte-identical N=1 contract, so the
 * pool phase never counts toward the overall bar. It is emitted only when
 * the pool is active (after the output phase of the primary flow), and the
 * tracker accepts it without advancing the completed count.
 */
export declare const POOL_EXPANSION_PHASE: "pool_expansion";
/** Total number of setup phases (drives the overall bar denominator). */
export declare const SETUP_PROGRESS_PHASE_COUNT: 10;
/** Fixed, safe human labels for each phase (never secrets). */
export declare const SETUP_PROGRESS_LABELS: Readonly<Record<SetupProgressPhase, string>>;
/** Short labels for the compact "done" line. */
export declare const SETUP_PROGRESS_SHORT_LABELS: Readonly<Record<SetupProgressPhase, string>>;
/** The bounded retry polls that carry a nested detail bar. */
export type SetupRetryKind = "key_settlement" | "sa_access";
/**
 * Fixed, safe operation labels for the notable setup steps.
 *
 * The flow emits `operation_started` / `operation_completed` around the
 * unknown-duration calls (gcloud spawns, API calls) so the detail bar can
 * show a fixed `working… <label>` instead of a guessed percentage. Labels
 * are constant text and never carry identifiers, paths, or secrets.
 */
export declare const SETUP_PROGRESS_OPERATIONS: {
    readonly GCLOUD_PRESENCE: "checking gcloud CLI";
    readonly ACTIVE_ACCOUNT: "checking active gcloud account";
    readonly DRIVE_SCOPE: "verifying Drive access";
    readonly PROJECT_VERIFY: "verifying project";
    readonly PROJECT_CREATE: "creating project";
    readonly PROJECT_SELECT: "selecting default project";
    readonly API_ENABLE: "enabling Sheets and Drive APIs";
    readonly SA_LIST: "listing service accounts";
    readonly SA_CREATE: "creating service account";
    readonly KEY_LIST: "listing service-account keys";
    readonly SHEET_CREATE: "creating spreadsheet";
    readonly SHEET_RECONCILE: "reconciling spreadsheet";
    readonly SHARE: "sharing spreadsheet with service account";
    readonly ENV_WRITE: "writing .env";
    readonly CHECKPOINT_PERSIST: "persisting checkpoint";
};
/** One generic operation label. */
export type SetupProgressOperation = (typeof SETUP_PROGRESS_OPERATIONS)[keyof typeof SETUP_PROGRESS_OPERATIONS];
/**
 * Fixed, safe operation labels for the bounded propagation checks.
 *
 * Operation events carrying these labels also carry a
 * {@link BoundedCheckInfo} with the 1-based attempt within the bounded
 * window, so the tracker can keep the detail bar on the propagation check
 * while it runs.
 */
export declare const SETUP_PROGRESS_BOUNDED_OPERATIONS: {
    readonly KEY_SETTLE: "key settlement check";
    readonly SA_ACCESS: "access check";
};
/** One bounded-check operation label. */
export type SetupBoundedOperation = (typeof SETUP_PROGRESS_BOUNDED_OPERATIONS)[keyof typeof SETUP_PROGRESS_BOUNDED_OPERATIONS];
/** 1-based attempt info of one propagation check within its bounded window. */
export interface BoundedCheckInfo {
    /** 1-based index of the check/attempt that is running (1..maxAttempts). */
    readonly attempt: number;
    /** Total checks/attempts in the bounded window (8 for both polls). */
    readonly maxAttempts: number;
}
/** How a completed phase finished. */
export type SetupProgressSource = "run" | "checkpoint";
/**
 * Discriminated progress event emitted by the setup flow and the CLI
 * controller.
 *
 * The flow emits `resumed` (once, with the phases a checkpoint
 * guarantees), `phase_started` / `phase_completed` at phase boundaries,
 * `operation_started` / `operation_completed` around notable steps
 * (bounded propagation checks carry {@link BoundedCheckInfo}), and
 * `retry_wait_started` before each bounded retry sleep. `phase_failed` is
 * emitted by the CLI controller when a run ends in error (the flow itself
 * returns a stable error result and never knows it is the final attempt —
 * the interactive login retry can still rescue an auth preflight failure).
 */
export type SetupProgressEvent = {
    readonly type: "resumed";
    readonly completedFromCheckpoint: readonly SetupProgressPhase[];
} | {
    readonly type: "phase_started";
    readonly phase: SetupProgressPhase;
} | {
    readonly type: "phase_completed";
    readonly phase: SetupProgressPhase;
    readonly source: SetupProgressSource;
} | {
    readonly type: "operation_started" | "operation_completed";
    readonly phase: SetupProgressPhase;
    readonly operation: SetupProgressOperation;
} | {
    readonly type: "operation_started" | "operation_completed";
    readonly phase: SetupProgressPhase;
    readonly operation: SetupBoundedOperation;
    readonly check: BoundedCheckInfo;
} | {
    readonly type: "retry_wait_started";
    readonly phase: SetupProgressPhase;
    readonly kind: SetupRetryKind;
    /** 1-based index of the propagation check that just ran. */
    readonly attempt: number;
    readonly maxAttempts: number;
    /** Milliseconds the flow will sleep before the next check. */
    readonly delayMs: number;
} | {
    readonly type: "phase_failed";
    readonly phase: SetupProgressPhase;
    readonly code: SetupErrorCode;
};
/** Sink that receives every progress event. */
export interface SetupProgressSink {
    report(event: SetupProgressEvent): void;
}
/** A sink that drops every event; used when progress is disabled. */
export declare const NOOP_PROGRESS_SINK: SetupProgressSink;
/**
 * Wraps a sink so a throwing callback (or an absent sink) can never affect
 * the setup run. Returns {@link NOOP_PROGRESS_SINK} for `undefined` so flow
 * call sites can call `progress.report(...)` unconditionally.
 */
export declare function safeProgressSink(sink: SetupProgressSink | undefined): SetupProgressSink;
/** Output sink the renderers write to (stderr in production). */
export interface ProgressOutput {
    readonly write: (text: string) => void;
}
/**
 * Renders a `[████…░░░…]` bar for a 0..1 fill ratio.
 *
 * The fill is clamped to [0, 1] so a clock tick past the end of a known wait
 * never overflows the bar.
 */
export declare function renderProgressBar(fill: number): string;
/**
 * Whole-percent of completed phases over the total.
 *
 * The input is clamped to the ten logical phases (defense in depth: the
 * tracker count is already clamped, but an out-of-range caller value must
 * never be able to render 110% or a negative percent).
 */
export declare function overallPercent(completed: number): number;
/**
 * Fixed size of every bounded propagation window.
 *
 * Both polls (key settlement and SA-access verification) run exactly eight
 * checks (`1/8`..`8/8`); the tracker rejects any attempt/maxAttempts pair
 * that claims a different window size, so impossible values can never
 * reach the detail bar or a rendered line.
 */
export declare const BOUNDED_CHECK_MAX_ATTEMPTS = 8;
/**
 * Validating progress state machine shared by both renderers.
 *
 * The tracker validates every event and REJECTS (ignores, never throws)
 * invalid ones: phase order (a phase may only start when every earlier
 * phase is complete and no other phase is in progress), duplicate phase
 * completion (a completed phase never increments the count again),
 * operation start/complete pairing (an operation may only complete the
 * exact operation that is active, with matching check attempt info),
 * retry kind/phase consistency, attempt bounds, and checkpoint phase
 * lists (a `resumed` list must be a prefix of the resumable phases).
 * Invalid events are silently dropped so a benign reporting quirk can
 * never silence progress for the rest of a run and can never throw.
 * {@link SetupProgressTracker.resetTransient} clears the in-progress
 * state (current phase, active operation, retry, failure) before the
 * interactive login retry so a re-run can re-emit phase events from
 * scratch; completed phases and the resume flag are kept.
 * {@link SetupProgressTracker.markFailed} records a failure for a phase
 * that is no longer in progress (the controller's `fail()` fallback after
 * a suspend cleared the current phase).
 */
export declare class SetupProgressTracker {
    private readonly completed;
    private current;
    private operation;
    private retry;
    private failed;
    private resumed;
    /**
     * Pool-expansion completion, tracked OUTSIDE `completed` so the
     * conditional pool phase never advances the overall ten-phase count.
     */
    private poolDone;
    /**
     * Number of completed phases (any source), clamped to the ten logical
     * phases. Duplicate completions are rejected, so the count can never
     * exceed the total; the clamp is defense in depth.
     */
    get completedCount(): number;
    /** True once a valid `resumed` event was processed. */
    get isResumed(): boolean;
    /** The currently in-progress phase, if any. */
    get currentPhase(): SetupProgressPhase | undefined;
    /** The active operation (generic step or bounded check), if any. */
    get activeOperation(): SetupProgressTracker["operation"];
    /** The active retry (bounded check/wait context), if any. */
    get activeRetry(): SetupProgressTracker["retry"];
    /** The failed phase/code on a `phase_failed` event, if any. */
    get failure(): SetupProgressTracker["failed"];
    /** True when the phase was completed (by run or checkpoint). */
    isComplete(phase: SetupProgressPhase): boolean;
    /**
     * Resets the in-progress state so a retried run can re-emit phase events
     * from scratch.
     *
     * Called by the renderer's `suspend()` before the inherited `gcloud auth
     * login` handoff: the first attempt may have died mid-phase (for example
     * during `drive_access`), and the retry re-runs the whole flow from
     * `cloud_auth`. Completed phases and the resume flag are kept — the
     * retry re-completes the same phases, and duplicate completion is
     * rejected so the overall count never grows past the real work.
     */
    resetTransient(): void;
    /**
     * Records a failure for a phase that is no longer in progress.
     *
     * The controller uses this as the `fail()` fallback after `suspend()`
     * cleared the current phase for the inherited login handoff — and for
     * the deterministic next-pending phase when a run-level error has no
     * current phase: the final failure frame must still name a phase.
     * Validation matches the `phase_failed` event (known phase, stable
     * code) minus the current-phase requirement; the transient
     * operation/retry state is already clear after the suspend.
     */
    markFailed(phase: SetupProgressPhase, code: SetupErrorCode): boolean;
    /** True when every phase before `phase` (in execution order) is complete. */
    private allEarlierCompleted;
    /** True when `phase` may start: no current phase, not completed, ordered. */
    private isValidNextPhase;
    /** True when the resumed list is a valid prefix of the resumable phases. */
    private isValidCheckpointList;
    /**
     * Processes one event, updating internal state.
     *
     * Never throws: invalid events are rejected (ignored) and `false` is
     * returned so the renderer can skip drawing for them.
     */
    apply(event: SetupProgressEvent): boolean;
}
/**
 * Events produced by the bounded key-settlement and SA-access verify
 * checks inside `keyProvision` / `saVerify`.
 *
 * These modules stay decoupled from the progress UI; `setupFlow` wires
 * their reporter through {@link boundedCheckReporter} to the progress
 * sink. `check_started` / `check_completed` bracket one propagation check
 * (1-based attempt within the bounded window); `wait_started` precedes a
 * scheduled sleep with the delay before the NEXT check and carries the
 * index of the check that just ran.
 */
export type BoundedCheckReporterEvent = {
    readonly type: "check_started";
    readonly attempt: number;
    readonly maxAttempts: number;
} | {
    readonly type: "check_completed";
    readonly attempt: number;
    readonly maxAttempts: number;
} | {
    readonly type: "wait_started";
    readonly attempt: number;
    readonly maxAttempts: number;
    readonly delayMs: number;
};
/** Reporter for the bounded propagation checks of one phase/kind. */
export interface BoundedCheckReporter {
    (event: BoundedCheckReporterEvent): void;
}
/**
 * Builds a {@link BoundedCheckReporter} that forwards to a progress sink as
 * operation events (with check attempt info) and `retry_wait_started`
 * events for the given phase and kind. Returns a no-op when the sink is
 * the {@link NOOP_PROGRESS_SINK}, so key provisioning and SA verification
 * stay cheap when progress is disabled.
 */
export declare function boundedCheckReporter(sink: SetupProgressSink, phase: SetupProgressPhase, kind: SetupRetryKind): BoundedCheckReporter;
/**
 * True when the environment marks an automation session.
 *
 * Mirrors the de-facto CI convention: a NON-EMPTY `CI` value (GitHub
 * Actions, GitLab CI, CircleCI, Travis, ...) marks automation, while an
 * empty override keeps interactive behavior (the same empty-override rule
 * as NO_COLOR). Production `main()` passes this into the CLI context so a
 * CI pseudo-TTY can never prompt for the interactive login handoff or
 * spawn the browser login.
 */
export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
/** True when ANSI color/control output should be used (TTY, not NO_COLOR, not CI). */
export declare function shouldUseInteractiveProgress(isTty: boolean, env?: NodeJS.ProcessEnv): boolean;
/** Controller surface the CLI orchestration drives in addition to events. */
export interface SetupProgressController extends SetupProgressSink {
    /**
     * Clears the in-place block, stops the animation timer, resets the
     * in-progress tracker state (before the inherited gcloud login handoff),
     * and remembers the in-progress phase so a later `fail()` can render a
     * stable failure frame when the handoff is cancelled or fails.
     */
    suspend(): void;
    /**
     * Ends a login-handoff suspension after a successful login: clears the
     * remembered suspended phase so a retry failure is labeled against the
     * retry's own tracker state (never the pre-login phase) and lets the
     * retry redraw. Never starts or stops timers itself — the retry's own
     * events restart any animation — so nothing runs during the inherited
     * login subprocess.
     */
    resume(): void;
    /** Marks the phase the run died in failed with a stable code, renders, and cleans up. */
    fail(code: SetupErrorCode): void;
    /** Renders the final state and releases any animation timer. */
    finish(): void;
}
/** Options for {@link createSetupProgressRenderer}. */
export interface SetupProgressRendererOptions {
    readonly output: ProgressOutput;
    /** True when the output stream is an interactive terminal. */
    readonly isTty: boolean;
    /** Override the interactive decision (e.g. force static in tests). */
    readonly interactive?: boolean;
    /** Wall-clock used for the known-wait animation; defaults to `Date.now`. */
    readonly now?: () => number;
    /** Scheduler used for the animation interval; defaults to `setInterval`. */
    readonly setInterval?: (handler: () => void, ms: number) => NodeJS.Timeout;
    /** Clears the animation interval; defaults to `clearInterval`. */
    readonly clearInterval?: (handle: NodeJS.Timeout) => void;
}
/**
 * Creates the production progress controller.
 *
 * In interactive mode it owns a single animation timer for the known-wait
 * detail bar; the timer is cleared on every subsequent event, on
 * {@link SetupProgressController.suspend} (before the inherited gcloud
 * login), and on {@link SetupProgressController.finish}. The timer is
 * `unref`-ed so it can never be what keeps the process alive (the setup
 * sleep itself holds the run open). In append-only mode no timer is used
 * and ordinary operation events update state without printing a line.
 * All controller methods swallow their own write/scheduler failures so
 * progress can never change the setup result or the exit code.
 */
export declare function createSetupProgressRenderer(options: SetupProgressRendererOptions): SetupProgressController;
//# sourceMappingURL=setupProgress.d.ts.map