/**
 * Ricky CLI command surface.
 *
 * Thin command-layer entry that wraps the interactive CLI entrypoint
 * with argument parsing for help, mode override, and version display.
 *
 * Design invariants:
 * - All side-effecting dependencies are injectable for deterministic tests.
 * - No invented commands — only surfaces what the codebase actually implements.
 * - Local/cloud routing defers to the interactive entrypoint — no silent fallback.
 * - The bin/start script surface is truthful: private package, linked CLI path only.
 */
import type { InteractiveCliDeps, InteractiveCliResult } from '../entrypoint/interactive-cli.js';
import type { CloudIntegrationConnector } from '../entrypoint/interactive-cli.js';
import type { RickyMode } from '../cli/mode-selector.js';
import type { ListRickyWorkflowSchedulesResult, ScheduleRickyWorkflowResult } from '../../../cloud/api/workflow-schedules.js';
import type { ConnectProviderOptions, ConnectProviderResult, StoredAuth } from '@agent-relay/cloud';
import { type ChildProcess } from 'node:child_process';
import { type ConnectTarget, type PowerUserSurface } from '../flows/power-user-parser.js';
import { type SalvageExitContext, type SalvageResult } from '../../../local/auto-salvage/index.js';
export interface ParsedArgs {
    command: 'run' | 'help' | 'version' | 'status' | 'connect' | 'schedule' | 'schedules';
    surface?: PowerUserSurface;
    mode?: RickyMode;
    connectTarget?: ConnectTarget;
    statusTarget?: 'linear';
    cloudTargets?: string[];
    runId?: string;
    spec?: string;
    specFile?: string;
    artifact?: string;
    stdin?: boolean;
    workflowName?: string;
    cronExpression?: string;
    scheduledAt?: string;
    timezone?: string;
    runRequested?: boolean;
    noRun?: boolean;
    /** Set by `--no-auto-salvage` — disables the auto-salvage hook on `--run` exit. */
    noAutoSalvage?: boolean;
    background?: boolean;
    foreground?: boolean;
    startFromStep?: string;
    previousRunId?: string;
    yes?: boolean;
    json?: boolean;
    quiet?: boolean;
    verbose?: boolean;
    autoFix?: number;
    refine?: false | {
        model?: string;
    };
    bestJudgement?: boolean;
    login?: boolean;
    connectMissing?: boolean;
    workforcePersonaWriterCli?: boolean;
    errors?: string[];
}
export interface CliMainResult {
    /** Exit code — 0 for success, 1 for user-facing errors. */
    exitCode: number;
    /** Output lines written to stdout. */
    output: string[];
    /** Interactive CLI result when the run command was executed. */
    interactiveResult?: InteractiveCliResult;
}
export type RelayCloudConnectProvider = (options: ConnectProviderOptions) => Promise<ConnectProviderResult>;
export type RelayCloudAuthenticator = () => Promise<StoredAuth>;
export type RickyScheduleWorkflow = (workflowPath: string, options: {
    name?: string;
    cronExpression?: string;
    scheduledAt?: string;
    timezone?: string;
}) => Promise<ScheduleRickyWorkflowResult>;
export type RickyListWorkflowSchedules = () => Promise<ListRickyWorkflowSchedulesResult>;
export interface CliProgressSpinner {
    text: string;
    start(text?: string): CliProgressSpinner;
    stop(): CliProgressSpinner;
    fail?(text?: string): CliProgressSpinner;
}
export type CliProgressSpinnerFactory = (options: {
    text: string;
    stream: NodeJS.WritableStream;
}) => CliProgressSpinner;
export type DetachedProcessSpawner = (command: string, args: string[], options: {
    cwd: string;
    detached: boolean;
    stdio: 'ignore';
    env: NodeJS.ProcessEnv;
}) => Pick<ChildProcess, 'unref'>;
export interface CliMainDeps extends InteractiveCliDeps {
    /** Override argv for testing — defaults to process.argv.slice(2). */
    argv?: string[];
    /** Override the interactive runner for testing. */
    runInteractive?: (deps: InteractiveCliDeps) => Promise<InteractiveCliResult>;
    /** Package version string — defaults to '0.0.0'. */
    version?: string;
    /** File reader override for testing spec-file handoffs. */
    readFileText?: (path: string) => Promise<string>;
    /** Package.json reader override for deterministic version tests. */
    readPackageJsonText?: (path: string) => string;
    /** Relay Cloud connector override for deterministic connect command tests. */
    connectProvider?: RelayCloudConnectProvider;
    /** Relay Cloud account login override for deterministic connect command tests. */
    ensureCloudAuthenticated?: RelayCloudAuthenticator;
    /** Nango connect-link connector override for deterministic integration command tests. */
    connectCloudIntegrations?: CloudIntegrationConnector;
    /** Cloud API URL override passed through to the Relay Cloud connector. */
    connectApiUrl?: string;
    /** Provider auth timeout override passed through to the Relay Cloud connector. */
    connectTimeoutMs?: number;
    /** Spinner factory override for focused progress tests. */
    createProgressSpinner?: CliProgressSpinnerFactory;
    /**
     * Override the heartbeat cadence (milliseconds) that periodically refreshes
     * the local progress spinner with an elapsed-time suffix while waiting for
     * the next `onProgress` message. Defaults to 5000ms (5s); set to 0 to
     * disable. Also overridable via `RICKY_PROGRESS_HEARTBEAT_MS`.
     */
    localProgressHeartbeatMs?: number;
    /** Clock override for deterministic heartbeat tests; defaults to `Date.now`. */
    now?: () => number;
    /** Detached background process spawner override for deterministic CLI tests. */
    spawnDetachedProcess?: DetachedProcessSpawner;
    /** Cloud workflow scheduling override for deterministic schedule command tests. */
    scheduleWorkflow?: RickyScheduleWorkflow;
    /** Cloud workflow schedule listing override for deterministic schedule command tests. */
    listWorkflowSchedules?: RickyListWorkflowSchedules;
    /**
     * Override the auto-salvage runner for deterministic tests. Default: real
     * git + gh subprocess calls wired through `createDefaultSalvageRuntime`.
     * Returning `null` disables the salvage hook entirely (used by tests that
     * don't care about salvage).
     */
    runAutoSalvage?: (spec: string, exitContext: SalvageExitContext, options: {
        disabled?: boolean;
    }) => Promise<SalvageResult | null>;
}
export declare function parseArgs(argv: string[]): ParsedArgs;
export declare function renderHelp(): string[];
/**
 * Run the Ricky CLI.
 *
 * Parses argv, dispatches to the appropriate handler:
 * - `help`    — prints usage and exits 0
 * - `version` — prints version and exits 0
 * - `run`     — delegates to the interactive CLI entrypoint
 */
export declare function cliMain(deps?: CliMainDeps): Promise<CliMainResult>;
export declare function resolveSignalSalvageSpecFile(argv: readonly string[]): string | undefined;
