Help System

/**
 * Enable help display on -h/--help flags
 * @param callback - Optional callback to customize help sections
 * @returns CLI instance for chaining
 */
help(callback?: HelpCallback): CAC;

type HelpCallback = (sections: HelpSection[]) => void | HelpSection[];

interface HelpSection {
  title?: string;
  body: string;
}

// Basic help enablement
const cli = cac("my-app");
cli.help();

// Custom help processing
cli.help((sections) => {
  // Add custom section
  sections.push({
    title: "Examples",
    body: "  my-app build --minify\n  my-app serve --port 8080"
  });
  
  // Modify existing sections
  sections.forEach(section => {
    if (section.title === "Commands") {
      section.body = section.body.replace(/build/, "compile");
    }
  });
  
  return sections;
});

/**
 * Set version and enable version display
 * @param version - Version string to display
 * @param customFlags - Custom flags for version (default: '-v, --version')
 * @returns CLI instance for chaining
 */
version(version: string, customFlags?: string): CAC;

// Basic version setup
cli.version("1.2.3");

// Custom version flags
cli.version("2.0.0", "-V, --version");

// Version from package.json
const pkg = require("./package.json");
cli.version(pkg.version);

/**
 * Manually output help message
 * Outputs help for matched command or global help
 */
outputHelp(): void;

/**
 * Manually output version information
 */
outputVersion(): void;

// Manual help display
if (someCondition) {
  cli.outputHelp();
  process.exit(0);
}

// Manual version display
if (options.showVersion) {
  cli.outputVersion();
  process.exit(0);
}

interface HelpSection {
  /** Section title (optional for unnamed sections) */
  title?: string;
  /** Section content body */
  body: string;
}

/**
 * Help callback receives array of sections and can:
 * - Modify existing sections
 * - Add new sections
 * - Remove sections by returning filtered array
 * - Return void to modify sections in-place
 */
type HelpCallback = (sections: HelpSection[]) => void | HelpSection[];

cli.help((sections) => {
  // Add banner at the beginning
  sections.unshift({
    body: "🚀 My Awesome CLI Tool"
  });
  
  // Add custom section
  sections.push({
    title: "Environment Variables",
    body: "  DEBUG=1    Enable debug output\n  NODE_ENV   Set environment"
  });
  
  // Modify existing sections
  const usageSection = sections.find(s => s.title === "Usage");
  if (usageSection) {
    usageSection.body = usageSection.body.replace("$", "🎯");
  }
  
  // Remove unwanted sections
  return sections.filter(s => s.title !== "Unwanted Section");
});

/**
 * Command-level help methods
 */
interface Command {
  /**
   * Set custom usage text for command help
   */
  usage(text: string): Command;
  
  /**
   * Add example for command help
   */
  example(example: CommandExample): Command;
  
  /**
   * Output help for this specific command
   */
  outputHelp(): void;
}

type CommandExample = ((bin: string) => string) | string;

cli
  .command("build <entry>", "Build your application")
  .usage("build <entry> [options]")
  .example("build src/index.js --minify")
  .example((name) => `${name} build src/app.ts --target es2020`)
  .option("--minify", "Minify output")
  .action((entry, options) => {
    // Command implementation
  });

// Accessing command help
const buildCommand = cli.commands.find(cmd => cmd.name === "build");
buildCommand?.outputHelp();

/**
 * Global help configuration methods
 */
interface CAC {
  /**
   * Set global usage text
   */
  usage(text: string): CAC;
  
  /**
   * Add global example
   */
  example(example: CommandExample): CAC;
}

cli
  .usage("my-app <command> [options]")
  .example("my-app build --production")
  .example("my-app serve --port 3000")
  .help();

/**
 * Default help sections (in order):
 * 1. Program name and version (no title)
 * 2. Usage - How to use the CLI
 * 3. Commands - Available commands (if any)
 * 4. Command help info - How to get command-specific help
 * 5. Options - Available options
 * 6. Examples - Usage examples (if any)
 */

// Example help output structure:
/*
my-app/1.0.0

Usage:
  $ my-app <command> [options]

Commands:
  build <entry>    Build your application
  serve [port]     Start development server

For more info, run any command with the `--help` flag:
  $ my-app build --help
  $ my-app serve --help

Options:
  --verbose        Enable verbose output
  -h, --help       Display this message
  -v, --version    Display version number

Examples:
  my-app build src/index.js --minify
  my-app serve --port 8080
*/

/**
 * Help integration behavior:
 * - Global help shows all commands and global options
 * - Command help shows command-specific options plus global options
 * - Help flags are automatically added when help() is called
 * - Help takes precedence over command execution
 */

const cli = cac("my-app");

// Global options
cli.option("--verbose", "Verbose output");
cli.option("--config <file>", "Config file");

// Commands
cli.command("build <entry>", "Build app")
   .option("--minify", "Minify output");

cli.help();

// Command line behaviors:
// my-app --help          -> Shows global help with all commands
// my-app build --help    -> Shows build command help with its options + global options
// my-app unknown --help  -> Shows global help (unknown command)

/**
 * Version integration:
 * - Version is displayed as "program-name/version platform-info"
 * - Version flags are automatically added when version() is called
 * - Version takes precedence over command execution
 * - Commands can have their own version
 */

cli.version("2.1.0");

// Command line: my-app --version
// Output: my-app/2.1.0 darwin-x64 node-v18.17.0

// Command-specific version
cli
  .command("build", "Build command")
  .version("1.0.0");

// Command line: my-app build --version  
// Output: my-app/1.0.0 darwin-x64 node-v18.17.0

/**
 * Platform info format: {platform}-{arch} node-{version}
 * Examples:
 * - darwin-x64 node-v18.17.0
 * - linux-x64 node-v16.14.2
 * - win32-x64 node-v20.5.0
 */

/**
 * Error handling:
 * - Help is shown automatically for unknown commands (with command:* event)
 * - Parse errors don't prevent help display
 * - Help callbacks that throw errors are handled gracefully
 */

// Show help on unknown commands
cli.on("command:*", () => {
  console.error("Unknown command");
  cli.outputHelp();
  process.exit(1);
});

// Safe help callback
cli.help((sections) => {
  try {
    // Risky help customization
    return sections.map(transformSection);
  } catch (error) {
    console.warn("Help customization failed:", error.message);
    return sections; // Fallback to default sections
  }
});