import type { Command } from 'commander';
import type { StrategyContainer } from './strategy.types';
/**
 * Supported CLI option types for type-safe configuration
 */
export type CliOptionType = 'string' | 'boolean' | 'string[]' | 'number';
/**
 * Configuration for a single CLI option
 */
export interface CliConfigOption {
    /** Commander.js flags string (e.g. '--template <name>', '-v, --verbose') */
    flags: string;
    /** Human-readable description for help text */
    description?: string;
    /** Type hint for future TypeScript inference */
    type?: CliOptionType;
    /** Default value (avoid premature type narrowing with unknown) */
    defaultValue?: unknown;
}
/**
 * Map of option names to their configuration
 */
export type CliConfigOptions = Record<string, CliConfigOption>;
/**
 * Example command usage for help text
 */
export interface CliConfigCommandExample {
    /** Example command string */
    command: string;
    /** Optional description of what the example does */
    description?: string;
}
/**
 * Configuration for a single CLI command
 */
export interface CliConfigCommand {
    /** Command description for help text */
    description?: string;
    /** Example usage for help text */
    example?: CliConfigCommandExample;
    /** Command-specific options */
    options?: CliConfigOptions;
    /** Additional help text appended after options */
    helper?: string;
    /** Nested subcommands (supports unlimited depth) */
    commands?: Record<string, CliConfigCommand>;
    /** Optional alias for the command */
    alias?: string;
}
/**
 * Root configuration tree defining all CLI commands
 */
export type CliConfigTree = Record<string, CliConfigCommand>;
/**
 * Action handler function for leaf commands
 *
 * @param options - Command options parsed by Commander.js
 * @param cmd - Commander.js command instance
 * @param strategies - Optional strategy container for customizing command behavior
 */
export type CliActionLeaf = (options: unknown, cmd: Command, strategies?: StrategyContainer) => void | Promise<void>;
/**
 * Branch node containing child actions
 */
export interface CliActionBranch {
    [key: string]: CliActionNode;
}
/**
 * Union type for action tree nodes with explicit type discrimination
 */
export type CliActionNode = {
    type: 'leaf';
    handler: CliActionLeaf;
} | {
    type: 'branch';
    children: CliActionBranch;
};
/**
 * Root of the action tree (always a branch)
 */
export type CliActionRoot = CliActionBranch;
/**
 * Metadata for CLI Core configuration
 */
export interface CliCoreMeta {
    /** Tool name (e.g. 'runtime') */
    toolName: string;
    /** Display title for help text */
    title: string;
    /** Tool description for help text */
    description: string;
    /** Fallback version if package.json not available */
    fallbackVersion: string;
}
/**
 * Resolve action handler from action tree using command path
 *
 * @param root - Root action tree
 * @param path - Array of command path segments (e.g. ['seo', 'init'])
 * @returns Action handler if found, undefined otherwise
 */
export declare function resolveAction(root: CliActionRoot, path: string[]): CliActionLeaf | undefined;
