import { type Writer } from './format.js';
/** Where SIGINT arrives: the process, or a plain emitter in tests. */
type SignalSource = {
    once(event: 'SIGINT', listener: () => void): unknown;
    removeListener(event: 'SIGINT', listener: () => void): unknown;
    listenerCount(event: 'SIGINT'): number;
};
export type ProgressHandle = {
    stop: (finalMessage?: string) => void;
};
/**
 * Live indeterminate progress on stderr while a scan/request is in flight; see
 * shouldShowProgress for when it is on. Ctrl-C clears the line before the process exits.
 */
export declare function startProgress(label: string, options: {
    isEnabled: boolean;
    stderr?: NodeJS.WritableStream & {
        columns?: number;
    };
    /** Soft expected duration used to fill the bar (ms). */
    expectedMs?: number;
    signals?: SignalSource;
    exit?: (code: number) => void;
}): ProgressHandle;
/**
 * Progress shows for text output on a terminal stderr, except in CI, with TERM=dumb or with
 * VIGILBASE_CLI_NO_PROGRESS=1. NO_COLOR does not turn it off: the spinner has no colour.
 */
export declare function shouldShowProgress(mode: 'text' | 'json', env?: NodeJS.ProcessEnv, stderr?: {
    isTTY?: boolean;
}): boolean;
/** Tiny helper so call sites stay readable. */
export declare function withProgress<T>(label: string, mode: 'text' | 'json', work: () => Promise<T>, writer?: Writer): Promise<T>;
export {};