/**
 * The declarative flag-spec table.
 *
 * This module is the single source of truth for the shell app's command-line
 * vocabulary. Rather than scatter the knowledge of "what flags exist, what they
 * mean, and how to read their values" across a hand-written argument loop, every
 * flag is described once, as data, in {@link FLAG_SPECS}. The generic parser in
 * `parse.ts` reads this table; the help renderer derives its text from it; and a
 * new flag is added by appending one row here, never by editing parser branches.
 *
 * A {@link FlagSpec} pins down four things about a flag:
 *   - its canonical long name and any aliases (short or long) the user may type;
 *   - its {@link FlagKind} — whether it carries no value (`boolean`), a free
 *     string, or a number;
 *   - a one-line description used to generate `--help`;
 *   - an optional default that seeds the parsed result when the flag is absent;
 *   - an optional `repeatable` marker for flags that may appear many times and
 *     accumulate (e.g. `--mcp`), collected into a string array by the parser.
 *
 * Nothing here touches `process`, the filesystem, or the network — it is plain
 * data plus a couple of pure lookup helpers, so it is trivially testable and
 * shareable between the parser and any tooling that wants to reason about flags.
 */
/** The three value shapes a flag can carry. */
export type FlagKind = "boolean" | "string" | "number";
/**
 * The parsed value a flag contributes to an {@link Invocation}. Booleans land as
 * `true`/`false`, strings as themselves, numbers as parsed numerics, and
 * repeatable flags accumulate into a `string[]`.
 */
export type FlagValue = boolean | string | number | string[];
/**
 * One row of the flag table: the complete, declarative description of a single
 * command-line flag.
 */
export interface FlagSpec {
    /**
     * The canonical long name, written *without* leading dashes (e.g. `"model"`).
     * This is the key the flag's value is filed under in the parsed result.
     */
    readonly name: string;
    /**
     * Every other spelling the user may type, each *with* its leading dashes
     * (e.g. `["-m"]` or `["--rpc", "--wire"]`). Both short (`-x`) and long
     * (`--xyz`) aliases are permitted. The canonical `--<name>` spelling is always
     * accepted and need not be listed here.
     */
    readonly aliases?: readonly string[];
    /** Whether the flag carries no value, a string, or a number. */
    readonly kind: FlagKind;
    /** A one-line summary used when rendering `--help`. */
    readonly description: string;
    /**
     * The value to seed the parsed result with when the flag is never supplied.
     * Omit for flags that should simply be absent when unused.
     */
    readonly default?: FlagValue;
    /**
     * When `true`, the flag may be given more than once; each occurrence is pushed
     * onto a `string[]` rather than overwriting the previous value. Only
     * meaningful for `string`-kind flags.
     */
    readonly repeatable?: boolean;
}
/**
 * The canonical flag table.
 *
 * Order matters only for help rendering (flags are shown top-to-bottom in this
 * order); parsing is driven by name/alias lookup, not position. Every spelling
 * across this table is unique — the lookup helpers below assume that.
 */
export declare const FLAG_SPECS: readonly FlagSpec[];
/**
 * Resolve a complete token (e.g. `"--model"`, `"-m"`, `"--rpc"`) to its spec, or
 * `undefined` if no flag claims that spelling.
 */
export declare function findFlagBySpelling(spelling: string): FlagSpec | undefined;
/**
 * Resolve a single clustered short letter (e.g. `"v"` from `-iv`) to its spec,
 * by matching against the `-x` form. Returns `undefined` if no flag uses that
 * short letter.
 */
export declare function findShortFlag(letter: string): FlagSpec | undefined;
/**
 * The seed result, holding the `default` of every spec that declares one. The
 * parser starts from a copy of this so absent-but-defaulted flags are present in
 * the output and repeatable flags begin as empty arrays.
 */
export declare function defaultFlags(): Record<string, FlagValue>;
