/**
 * Schema-driven CLI help generator.
 *
 * Generalized from the identical pattern in tx and zzz. Consumers configure
 * once with `create_help` and get back `generate_main_help`,
 * `generate_command_help`, and `get_help_text`.
 *
 * @module
 */
import type { z } from 'zod';
import { type ZodSchemaProperty } from '@fuzdev/fuz_util/zod.js';
/**
 * Command metadata for help generation.
 */
export interface CommandMeta<TCategory extends string = string> {
    schema?: z.ZodType;
    summary: string;
    usage: string;
    category: TCategory;
}
/**
 * Category configuration for help display.
 */
export interface HelpCategory<TCategory extends string = string> {
    key: TCategory;
    title: string;
}
/**
 * Configuration for `create_help`.
 */
export interface HelpOptions<TCategory extends string = string> {
    /** Application name (e.g., `"tx"`, `"zzz"`). */
    name: string;
    /** Application version string. */
    version: string;
    /** Short description for the main help header. */
    description: string;
    /** Command registry keyed by command path (e.g., `"apply"`, `"daemon start"`). */
    commands: Record<string, CommandMeta<TCategory>>;
    /** Category display order for main help. */
    categories: Array<HelpCategory<TCategory>>;
    /** Example commands for main help. */
    examples: Array<string>;
    /** Zod schema for global arguments (shown in all help output). */
    global_args_schema: z.ZodType;
    /** Whether to use ANSI colors in output. Defaults to `true`. */
    use_colors?: boolean;
}
/**
 * Help generator returned by `create_help`.
 */
export interface HelpGenerator {
    /** Generate main help text with all commands grouped by category. */
    generate_main_help: () => string;
    /** Generate help text for a specific command. */
    generate_command_help: (command: string, meta: CommandMeta) => string;
    /** Get help text for a command or main help. */
    get_help_text: (command?: string, subcommand?: string) => string;
}
/**
 * Get maximum length from array.
 *
 * @param items - array of items
 * @param to_string - function to convert item to string for length measurement
 * @returns maximum string length
 */
export declare const to_max_length: <T>(items: Array<T>, to_string: (item: T) => string) => number;
/**
 * Format argument name with short aliases for display.
 *
 * Only single-char aliases are shown (e.g., `-h, --help`).
 * Flags use snake_case (e.g., `--env_file`, `--detect_only`).
 *
 * @param prop - schema property
 * @returns formatted name string
 */
export declare const format_arg_name: (prop: ZodSchemaProperty) => string;
/**
 * Create a help generator configured for an application.
 *
 * @param options - help configuration
 * @returns help generator with `generate_main_help`, `generate_command_help`, and `get_help_text`
 */
export declare const create_help: <TCategory extends string>(options: HelpOptions<TCategory>) => HelpGenerator;
//# sourceMappingURL=help.d.ts.map