import type { Readable, Writable } from "node:stream";
import type { ParseArgsConfig } from "node:util";
import type { LoadResult } from "../oauth/tokenStore";
import type { CommonArgs } from "./commonArgs";
/** Mapping passed to `parseArgs` for verb-specific flags. */
export type VerbOptions = NonNullable<ParseArgsConfig["options"]>;
/** Injectables every CLI verb sees. Dispatcher fills with `process.*`; tests pass synthetic values. */
export interface CommandDeps {
    /** `isTTY` is optional so `Readable.from([])` test fixtures coerce to non-TTY. */
    stdin: Readable & {
        isTTY?: boolean;
    };
    stdout: Writable;
    stderr: Writable;
    /**
     * Pre-loaded result of `KeyringTokenStore.load()` from the
     * dispatcher's keychain read, so a single CLI invocation hits the
     * keychain once instead of N times.
     */
    loadedEntry?: LoadResult;
}
/** Specification of a single CLI verb consumed by the dispatcher. */
export interface CommandSpec {
    /** Verb name, e.g. `"login"`. */
    readonly name: string;
    /** One-liner shown in the top-level `axe-auth --help` listing. */
    readonly summary: string;
    /** Full help text printed for `axe-auth <verb> --help`. */
    readonly helpText: string;
    /** Verb-specific `parseArgs` options; common options are added by the dispatcher. */
    readonly options: VerbOptions;
    /** `true` if this verb cannot run without a usable walnut URL (login). */
    readonly requiresConfig: boolean;
    /**
     * Throw `CLIError` for a known failure with an explicit exit code;
     * any other error becomes exit code 2 with the message on stderr.
     */
    run(args: CommonArgs, deps: CommandDeps): Promise<void>;
}