Help and Output

/**
 * Configure help option
 * @param opt - Help option name or false to disable
 * @param msg - Help option description
 * @returns YargsInstance for chaining
 */
help(opt?: string | false, msg?: string): YargsInstance;

/**
 * Alias for help()
 */
addHelpOpt(opt?: string | false, msg?: string): YargsInstance;

/**
 * Display help text
 * @param level - Output level ('error', 'log') or custom function
 * @returns YargsInstance for chaining
 */
showHelp(level?: 'error' | 'log' | ((message: string) => void)): YargsInstance;

/**
 * Get help text as a Promise
 * @returns Promise resolving to help text string
 */
getHelp(): Promise<string>;

// Default help option (--help, -h)
yargs()
  .option('port', { describe: 'Server port' })
  .help()
  .parse();

// Custom help option
yargs()
  .option('verbose', { describe: 'Verbose output' })
  .help('info', 'Show application info')
  .parse();

// Disable help
yargs()
  .option('quiet', { describe: 'Quiet mode' })
  .help(false)
  .parse();

// Show help programmatically
const yarg = yargs()
  .option('port', { describe: 'Server port' });

yarg.showHelp(); // Outputs to console
yarg.showHelp('error'); // Outputs to stderr
yarg.showHelp(console.error); // Custom output function

// Get help as string
yarg.getHelp().then(helpText => {
  console.log('Help text:', helpText);
});

/**
 * Configure version option
 * @param opt - Version option name or false to disable
 * @param msg - Version option description
 * @param ver - Version string
 * @returns YargsInstance for chaining
 */
version(opt?: string | false, msg?: string, ver?: string): YargsInstance;

/**
 * Display version information
 * @param level - Output level ('error', 'log') or custom function
 * @returns YargsInstance for chaining
 */
showVersion(level?: 'error' | 'log' | ((message: string) => void)): YargsInstance;

// Auto-detect version from package.json
yargs()
  .version()
  .parse();

// Custom version string
yargs()
  .version('1.2.3')
  .parse();

// Custom version option and message
yargs()
  .version('ver', 'Show application version', '2.0.0')
  .parse();

// Disable version
yargs()
  .version(false)
  .parse();

// Show version programmatically
yargs()
  .version('1.0.0')
  .showVersion(); // Outputs version

/**
 * Set usage message or define default command
 * @param msg - Usage message template
 * @param description - Command description (if defining command)
 * @param builder - Command builder
 * @param handler - Command handler
 * @returns YargsInstance for chaining
 */
usage(msg: string | null, description?: string | boolean, builder?: CommandBuilderDefinition | CommandBuilder, handler?: CommandHandlerCallback): YargsInstance;

/**
 * Add usage examples
 * @param cmd - Example command or array of [command, description] pairs
 * @param description - Example description
 * @returns YargsInstance for chaining
 */
example(cmd: string | [string, string?][], description?: string): YargsInstance;

/**
 * Set epilogue text (shown after help)
 * @param msg - Epilogue message
 * @returns YargsInstance for chaining
 */
epilogue(msg: string): YargsInstance;

/**
 * Alias for epilogue()
 */
epilog(msg: string): YargsInstance;

// Custom usage message
yargs()
  .usage('Usage: $0 [options]')
  .option('port', { describe: 'Server port' })
  .parse();

// Usage with placeholders
yargs()
  .usage('Usage: $0 <command> [options]')
  .command('start', 'Start the service')
  .parse();

// Single example
yargs()
  .example('$0 --port 3000', 'Start server on port 3000')
  .parse();

// Multiple examples
yargs()
  .example([
    ['$0 start --port 3000', 'Start server on port 3000'],
    ['$0 stop', 'Stop the server'],
    ['$0 restart --timeout 30', 'Restart with 30s timeout']
  ])
  .parse();

// Epilogue
yargs()
  .option('verbose', { describe: 'Verbose output' })
  .epilogue('For more information, visit https://example.com/docs')
  .parse();

// Usage as default command
yargs()
  .usage('$0 [name]', 'Greet someone', (yargs) => {
    return yargs.positional('name', {
      describe: 'Name to greet',
      default: 'World'
    });
  }, (argv) => {
    console.log(`Hello, ${argv.name}!`);
  })
  .parse();

/**
 * Configure show-hidden option
 * @param opt - Show-hidden option name or false to disable
 * @param msg - Show-hidden option description
 * @returns YargsInstance for chaining
 */
showHidden(opt?: string | false, msg?: string): YargsInstance;

/**
 * Alias for showHidden()
 */
addShowHiddenOpt(opt?: string | false, msg?: string): YargsInstance;

yargs()
  .option('verbose', { describe: 'Verbose output' })
  .option('debug', { describe: 'Debug mode', hidden: true })
  .showHidden() // Adds --show-hidden option
  .parse();

// Custom show-hidden option
yargs()
  .option('secret', { describe: 'Secret option', hidden: true })
  .showHidden('reveal', 'Show hidden options')
  .parse();

/**
 * Show help when validation fails
 * @param enabled - Whether to show help on failure, or custom message
 * @param message - Custom failure message
 * @returns YargsInstance for chaining
 */
showHelpOnFail(enabled?: string | boolean, message?: string): YargsInstance;

// Show help on any failure
yargs()
  .option('required', { demandOption: true })
  .showHelpOnFail(true)
  .parse();

// Custom failure message
yargs()
  .demandCommand(1)
  .showHelpOnFail(false, 'Specify a command to get started')
  .parse();

// Custom message with help
yargs()
  .option('config', { demandOption: true })
  .showHelpOnFail('Try --help for available options')
  .parse();

/**
 * Group options under headings in help
 * @param opts - Option name(s) to group
 * @param groupName - Group heading name
 * @returns YargsInstance for chaining
 */
group(opts: string | string[], groupName: string): YargsInstance;

/**
 * Get current option groups
 * @returns Object mapping group names to option arrays
 */
getGroups(): Dictionary<string[]>;

yargs()
  .option('host', { describe: 'Server host' })
  .option('port', { describe: 'Server port' })
  .option('verbose', { describe: 'Verbose output' })
  .option('quiet', { describe: 'Quiet mode' })
  .group(['host', 'port'], 'Server Options:')
  .group(['verbose', 'quiet'], 'Output Options:')
  .parse();

// Get current groups
const groups = yargs().getGroups();
console.log('Option groups:', groups);

/**
 * Set custom failure handler
 * @param f - Failure handler function or false to disable
 * @returns YargsInstance for chaining
 */
fail(f: ((message: string, error: Error, yargs: YargsInstance) => void) | boolean): YargsInstance;

// Custom failure handler
yargs()
  .option('config', { demandOption: true })
  .fail((msg, err, yargs) => {
    console.error('Configuration Error:', msg);
    console.error('Use --help for usage information');
    process.exit(1);
  })
  .parse();

// Disable default failure handling
yargs()
  .demandCommand(1)
  .fail(false)
  .parse();

/**
 * Set or get current locale
 * @param locale - Locale string (e.g., 'en', 'es', 'fr')
 * @returns YargsInstance for chaining or current locale
 */
locale(locale?: string): YargsInstance | string;

/**
 * Control automatic locale detection
 * @param detect - Whether to detect locale from environment
 * @returns YargsInstance for chaining
 */
detectLocale(detect: boolean): YargsInstance;

/**
 * Update locale strings
 * @param obj - Object mapping string keys to translated values
 * @returns YargsInstance for chaining
 */
updateStrings(obj: Dictionary<string>): YargsInstance;

/**
 * Alias for updateStrings()
 */
updateLocale(obj: Dictionary<string>): YargsInstance;

/**
 * Get current locale detection setting
 * @returns Whether locale detection is enabled
 */
getDetectLocale(): boolean;

// Set locale
yargs()
  .locale('es')
  .help()
  .parse();

// Get current locale
const currentLocale = yargs().locale();
console.log('Current locale:', currentLocale);

// Disable auto-detection
yargs()
  .detectLocale(false)
  .locale('en')
  .parse();

// Custom strings
yargs()
  .updateStrings({
    'Commands:': 'Comandos:',
    'Options:': 'Opciones:',
    'Show help': 'Mostrar ayuda'
  })
  .help()
  .parse();

/**
 * Help display level options
 */
type HelpLevel = 'error' | 'log' | ((message: string) => void);

/**
 * Failure handler function
 */
type FailureFunction = (message: string, error: Error, yargs: YargsInstance) => void;

/**
 * Dictionary type for string mappings
 */
type Dictionary<T = any> = { [key: string]: T };

/**
 * Usage configuration options
 */
interface UsageConfiguration {
  /** Should types be hidden when usage is displayed */
  'hide-types'?: boolean;
}