/**
 * @fileoverview PreParse flag correction pipeline — fixes common AI-generated input mistakes.
 *
 * Why this exists: AI agents and LLM-based code generation often produce CLI invocations
 * that don't exactly match the expected flag syntax. Common patterns include:
 *
 * - camelCase flag names (`--userId`) instead of kebab-case (`--user-id`)
 * - snake_case (`--page_size`) instead of kebab-case (`--page-size`)
 * - UPPER_CASE (`--CODE`) instead of lowercase (`--code`)
 * - Sticky values (`--limit100`) where meow parses them as boolean flags
 *
 * Without correction, these inputs silently fail. With correction, the CLI
 * "just works" for AI agents, improving the developer experience significantly.
 *
 * Why corrections go to stderr: corrected input is not what the user explicitly
 * typed. Logging them to stderr (not stdout) ensures they don't corrupt JSON
 * output pipes while still being visible in terminal sessions.
 *
 * Design: two independent handlers, applied in order:
 * 1. `aliasHandler` — normalizes flag names to kebab-case
 * 2. `stickyHandler` — splits glued flag-value tokens
 *
 * Adding a new handler requires only inserting it into the `allCorrections` array;
 * the rest of the pipeline (building the corrected object, logging) is handler-agnostic.
 */
import type { FlagDef } from "../framework/types.js";
/**
 * A single flag name correction applied during PreParse.
 *
 * `handler` identifies which correction rule fired, helping AI agents
 * understand the specific mistake they made and self-correct in future calls.
 */
export interface FlagCorrection {
    /** Original flag name as received from meow (before any corrections). */
    original: string;
    /** Corrected flag name in canonical kebab-case form. */
    corrected: string;
    /** Which handler produced this correction: `"alias"` or `"sticky"`. */
    handler: string;
}
/**
 * Result of running `correctFlags`.
 * Returns a new flags object (input is never mutated) and a list of
 * all corrections applied.
 */
export interface CorrectionResult {
    /** Corrected flags object — safe to pass to `parseFlags()`. */
    flags: Record<string, any>;
    /** All individual corrections applied, in order. */
    corrections: FlagCorrection[];
}
/**
 * Converts camelCase / snake_case / UPPER_CASE to kebab-case.
 *
 * Why multiple conversions in sequence: the order matters.
 * We first collapse underscores (snake_case) before handling camelCase boundaries,
 * so `page_size` → `page-size` (not `page_Size`). UPPER_CASE segments are
 * lowercased last so `API_URL` → `api-url` (not `a-p-i-u-r-l`).
 *
 * @param s - Input flag name.
 * @returns kebab-case equivalent.
 */
export declare function toKebab(s: string): string;
/**
 * Corrects raw meow flags before they reach `parseFlags()`.
 *
 * Why this returns a new object rather than mutating input: mutating the
 * `flags` object passed from meow could interfere with meow's internal state.
 * Returning a new object is safer and makes it clear which flags are
 * user-supplied vs. auto-corrected.
 *
 * @param raw - Raw flags from meow (may contain alias or sticky errors).
 * @param defs - All known flag definitions (used to determine which keys are legitimate).
 * @returns Corrected flags and the list of corrections applied.
 */
export declare function correctFlags(raw: Record<string, any>, defs: FlagDef[]): CorrectionResult;