import { OpencliSpecJson } from '@xyd-js/opencli';

type Shell = 'zsh' | 'fish';
/** A flag/option, normalized for completion generation. */
interface CompletionOption {
    /** Flag spellings, e.g. `['-h', '--help']`. */
    flags: string[];
    /** Whether the flag consumes a value (`--port <n>`) vs. a switch. */
    takesValue: boolean;
    description?: string;
}
/** A command node (the CLI root or a subcommand) the generators walk. */
interface CompletionNode {
    name: string;
    description?: string;
    options: CompletionOption[];
    /** Subcommands keyed by name. */
    commands: Record<string, CompletionNode>;
}

/** Generate a fish completion script from an OpenCLI document. */
declare function fish(spec: OpencliSpecJson): string;

/** Generate a zsh completion script (`#compdef`) from an OpenCLI document. */
declare function zsh(spec: OpencliSpecJson): string;

/**
 * Adapt an OpenCLI document into the command tree the shell generators walk.
 * Root-level `recursive` options (a CLI's global flags) are made available on
 * every command, so they complete in any subcommand context too.
 */
declare function opencliToTree(spec: OpencliSpecJson): CompletionNode;

/** Generate a completion script for the given shell from an OpenCLI document. */
declare function completion(spec: OpencliSpecJson, shell: Shell): string;

export { type CompletionNode, type CompletionOption, type Shell, completion, fish, opencliToTree, zsh };