/**
 * The generic, table-driven invocation parser.
 *
 * {@link tokenizeInvocation} turns a raw `argv` slice (the words after the
 * program name) into a structured {@link Invocation}: a bag of recognised flag
 * values, the leftover positionals, a derived free-text `prompt`, and the single
 * {@link RunnerMode} the launcher should dispatch to.
 *
 * The parser is fully driven by the {@link FLAG_SPECS} table in `flags.ts` — it
 * contains no per-flag branches. It understands the conventions a Unix CLI user
 * expects:
 *
 *   - long flags `--name`, with the value either glued on as `--name=value` or
 *     taken from the following token (`--name value`);
 *   - short flags `-x`, likewise `-x=value`, `-x value`, or glued `-xvalue` for
 *     value-taking shorts;
 *   - clustered short booleans, so `-ip` is `-i -p`, and a value-taking short may
 *     end a cluster (`-ipm gpt` ⇒ `-i -p -m gpt`);
 *   - a bare `--` terminator, after which every remaining token is a positional
 *     even if it looks like a flag;
 *   - repeatable flags (e.g. `--mcp`) that accumulate into an array.
 *
 * It is pure: it reads only the `argv` array passed in and never touches
 * `process`, the environment, the filesystem, or a TTY. Whether the session is
 * actually interactive is *not* probed here — the caller passes that fact in via
 * {@link TokenizeOptions.attended} so the function stays deterministic and
 * testable.
 *
 * On a malformed invocation (unknown flag, missing required value, unparseable
 * number) it throws an {@link InvocationError}; the launcher catches it at the
 * edge and reports it.
 */
import { FLAG_SPECS } from "./flags";
import type { FlagValue } from "./flags";
/**
 * The runner the launcher should hand off to, derived from the parsed flags:
 *   - `help`    — usage was requested (`--help`);
 *   - `version` — the version was requested (`--version`);
 *   - `wire`    — the JSON line protocol over stdio (`--json`);
 *   - `print`   — a single-shot answer to stdout (a prompt plus `--print`);
 *   - `repl`    — the interactive loop (the default when unattended decisions
 *                 don't force one of the above).
 */
export type RunnerMode = "print" | "wire" | "repl" | "help" | "version";
/**
 * The structured result of parsing an `argv` slice.
 */
export interface Invocation {
    /**
     * Recognised flag values, keyed by each spec's canonical `name`. Booleans are
     * present as `true`/`false`, strings/numbers as their parsed value, repeatable
     * flags as a (possibly empty) `string[]`, and defaulted flags as their seed.
     */
    readonly flags: Record<string, FlagValue>;
    /** Every non-flag token, in order, with the `--` terminator removed. */
    readonly positionals: readonly string[];
    /**
     * The positionals joined into a single free-text prompt, or `undefined` when
     * there were none. This is the message the user typed for one-shot/print runs.
     */
    readonly prompt?: string;
    /** The single runner the launcher should dispatch to. */
    readonly mode: RunnerMode;
}
/** Knobs the caller supplies that the pure parser cannot discover itself. */
export interface TokenizeOptions {
    /**
     * Whether the process is attended by an interactive terminal (a TTY on
     * stdin/stdout). The caller probes this and passes it in so the parser stays
     * free of `process` access. Defaults to `false` (treat as unattended), which
     * biases an ambiguous, prompt-less invocation toward a non-interactive run.
     */
    readonly attended?: boolean;
}
/** Thrown when an `argv` slice cannot be parsed into a valid invocation. */
export declare class InvocationError extends Error {
    constructor(message: string);
}
/**
 * Parse a raw `argv` slice into a structured {@link Invocation}.
 *
 * `argv` must already exclude the runtime and script names — pass
 * `process.argv.slice(2)` from the launcher. The function performs a single
 * left-to-right scan, classifying each token as a long flag, a short
 * flag/cluster, the `--` terminator, or a positional.
 */
export declare function tokenizeInvocation(argv: readonly string[], options?: TokenizeOptions): Invocation;
/** Re-export the spec table so callers can render help from one import site. */
export { FLAG_SPECS };
