/**
 * Shell completion script generation for bargs CLIs.
 *
 * Provides dynamic shell completion support for bash, zsh, and fish shells. The
 * generated scripts call back to the CLI to get completion candidates.
 *
 * @packageDocumentation
 */
import type { OptionsSchema, PositionalsSchema } from "./types.cjs";
/**
 * Supported shell types for completion script generation.
 *
 * @group Completion
 */
export type Shell = 'bash' | 'fish' | 'zsh';
/**
 * Command entry in internal state.
 */
type CommandEntry = {
    /** Alternative names for this command */
    aliases?: string[];
    /** Command definition with schemas */
    cmd: {
        /** Options schema for this command */
        __optionsSchema: OptionsSchema;
        /** Positionals schema for this command */
        __positionalsSchema: PositionalsSchema;
    };
    /** Command description for help text */
    description?: string;
    /** Discriminator for leaf commands */
    type: 'command';
} | {
    /** Alternative names for this command */
    aliases?: string[];
    /** Nested CLI builder for subcommands */
    builder: unknown;
    /** Command description for help text */
    description?: string;
    /** Discriminator for nested command groups */
    type: 'nested';
};
/**
 * Internal CLI state structure (matches bargs.ts InternalCliState).
 */
interface InternalCliState {
    /** Map of command aliases to canonical command names */
    aliasMap: Map<string, string>;
    /** Map of command names to their entries */
    commands: Map<string, CommandEntry>;
    /** Global parser with options and positionals schemas */
    globalParser?: {
        /** Global options schema */
        __optionsSchema: OptionsSchema;
        /** Global positionals schema */
        __positionalsSchema: PositionalsSchema;
    };
    /** CLI executable name */
    name: string;
}
/**
 * Generate a shell completion script for the given CLI.
 *
 * The generated script calls back to the CLI with `--get-bargs-completions` to
 * get completion candidates dynamically.
 *
 * @example
 *
 * ```typescript
 * // Output script for bash
 * console.log(generateCompletionScript('mytool', 'bash'));
 * // Redirect to shell config: mytool --completion-script bash >> ~/.bashrc
 * ```
 *
 * @function
 * @param cliName - The name of the CLI executable
 * @param shell - The target shell ('bash', 'zsh', or 'fish')
 * @returns The completion script as a string
 * @group Completion
 */
export declare const generateCompletionScript: (cliName: string, shell: Shell) => string;
/**
 * Get completion candidates for the current command line state.
 *
 * Analyzes the provided words to determine context and returns appropriate
 * completion suggestions.
 *
 * @function
 * @param state - Internal CLI state containing commands and options
 * @param shell - The shell requesting completions (affects output format)
 * @param words - The command line words (COMP_WORDS in bash)
 * @returns Array of completion candidates (one per line when output)
 * @group Completion
 */
export declare const getCompletionCandidates: (state: InternalCliState, shell: Shell, words: string[]) => string[];
/**
 * Validate that a shell name is supported.
 *
 * @function
 * @param shell - The shell name to validate
 * @returns The validated shell type
 * @throws Error if the shell is not supported
 * @group Completion
 */
export declare const validateShell: (shell: string) => Shell;
export {};
//# sourceMappingURL=completion.d.ts.map