CLI Management

/**
 * Create a CLI instance
 * @param name - Optional program name for help/version messages. Defaults to basename of argv[1]
 * @returns CAC instance
 */
function cac(name?: string): CAC;

import { cac } from "cac";

// Basic CLI creation
const cli = cac();

// Named CLI for better help messages
const cli = cac("my-app");

class CAC extends EventEmitter {
  /** Program name displayed in help and version messages */
  readonly name: string;
  
  /** Array of registered commands */
  readonly commands: Command[];
  
  /** Global command instance for global options */
  readonly globalCommand: GlobalCommand;
  
  /** Currently matched command after parsing */
  readonly matchedCommand?: Command;
  
  /** Name of the matched command */
  readonly matchedCommandName?: string;
  
  /** Raw CLI arguments passed to parse() */
  readonly rawArgs: string[];
  
  /** Parsed CLI arguments (non-option arguments) */
  readonly args: ReadonlyArray<string>;
  
  /** Parsed CLI options as key-value pairs */
  readonly options: { [k: string]: any };
  
  /** Whether to show help on exit */
  readonly showHelpOnExit?: boolean;
  
  /** Whether to show version on exit */
  readonly showVersionOnExit?: boolean;
  
  /**
   * CAC constructor
   * @param name - Program name for help and version messages
   */
  constructor(name?: string);
}

/**
 * Set global usage text displayed in help
 * @param text - Usage text string
 * @returns CLI instance for chaining
 */
usage(text: string): CAC;

/**
 * Add a global example displayed in help
 * @param example - Example string or function returning example
 * @returns CLI instance for chaining
 */
example(example: CommandExample): CAC;

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

cli.usage("my-app [options] <command>");
cli.example("my-app build --minify src/index.js");
cli.example((name) => `${name} serve --port 3000`);

/**
 * Parse command line arguments
 * @param argv - Arguments array (defaults to processArgs which is process.argv)
 * @param options - Parse options
 * @returns Object with parsed args and options
 */
parse(argv?: string[], options?: ParseOptions): ParsedArgv;

/**
 * Execute the action for the matched command
 * @returns Result from command action (can be Promise)
 */
runMatchedCommand(): any;

interface ParseOptions {
  /** Whether to run the matched command action (default: true) */
  run?: boolean;
}

interface ParsedArgv {
  args: ReadonlyArray<string>;
  options: { [k: string]: any };
}

// Basic parsing (runs command automatically)
const result = cli.parse();

// Parse without running (for error handling)
try {
  cli.parse(process.argv, { run: false });
  await cli.runMatchedCommand();
} catch (error) {
  console.error(error.message);
  process.exit(1);
}

/**
 * Output help message for matched command or global help
 */
outputHelp(): void;

/**
 * Output version information
 */
outputVersion(): void;

/**
 * Clear matched command state
 */
unsetMatchedCommand(): void;

/**
 * Events emitted during command processing:
 * - 'command:${commandName}' - When specific command matches
 * - 'command:!' - When default command matches  
 * - 'command:*' - When no command matches (unknown command)
 */
on(event: string, listener: (...args: any[]) => void): CAC;

cli.on("command:build", (command) => {
  console.log("Build command matched");
});

cli.on("command:!", (command) => {
  console.log("Default command executed");
});

cli.on("command:*", () => {
  console.error("Unknown command");
  process.exit(1);
});

class CACError extends Error {
  constructor(message: string);
}