Command Management

/**
 * Registers a new command in the vorpal API
 * @param name - Command name with optional arguments <required> or [optional]
 * @param desc - Optional command description
 * @param opts - Optional options object with noHelp, mode, catch properties
 * @returns Command instance for further configuration
 */
function command(name: string, desc?: string, opts?: CommandOptions): Command;

interface CommandOptions {
  noHelp?: boolean;
  mode?: boolean;
  catch?: boolean;
}

const vorpal = require('vorpal')();

// Simple command
vorpal
  .command('hello', 'Says hello')
  .action(function(args, callback) {
    this.log('Hello World!');
    callback();
  });

// Command with required argument
vorpal
  .command('greet <name>', 'Greets a person')
  .action(function(args, callback) {
    this.log(`Hello, ${args.name}!`);
    callback();
  });

// Command with optional argument
vorpal
  .command('say [message]', 'Says a message')
  .action(function(args, callback) {
    this.log(args.message || 'Nothing to say');
    callback();
  });

/**
 * Registers a new 'mode' command (interactive mode)
 * @param name - Mode command name
 * @param desc - Optional mode description
 * @param opts - Optional mode options
 * @returns Command instance for mode configuration
 */
function mode(name: string, desc?: string, opts?: object): Command;

const vorpal = require('vorpal')();

vorpal
  .mode('config', 'Enters configuration mode')
  .delimiter('config:')
  .init(function(args, callback) {
    this.log('Entering configuration mode...');
    callback();
  })
  .action(function(command, callback) {
    // Handle commands within this mode
    if (command === 'set param value') {
      this.log('Parameter set!');
    }
    callback();
  });

/**
 * Registers a 'catch' command executed when no command matches
 * @param name - Catch command pattern
 * @param desc - Optional catch description
 * @param opts - Optional catch options
 * @returns Command instance for catch configuration
 */
function catch(name: string, desc?: string, opts?: object): Command;

const vorpal = require('vorpal')();

vorpal
  .catch('[words...]', 'Handles unmatched commands')
  .action(function(args, callback) {
    this.log(`Command not found: ${args.words.join(' ')}`);
    this.log('Type "help" for available commands');
    callback();
  });

/**
 * Alias to the catch command
 * @param name - Default command pattern
 * @param desc - Optional default description
 * @param opts - Optional default options
 * @returns Command instance for default configuration
 */
function default(name: string, desc?: string, opts?: object): Command;

/**
 * Returns the instance of given command
 * @param name - Command name to find
 * @returns Command instance or undefined if not found
 */
function find(name: string): Command | undefined;

const vorpal = require('vorpal')();

vorpal.command('test', 'Test command');

const testCommand = vorpal.find('test');
if (testCommand) {
  // Modify the existing command
  testCommand.description('Updated test command');
}

/**
 * Defines description for given command
 * @param str - Description string (optional for getter)
 * @returns Description string (getter) or Command instance (setter)
 */
function description(str?: string): string | Command;

/**
 * Registers an option for given command
 * @param flags - Option flags (e.g., '-v, --verbose')
 * @param description - Option description
 * @param autocomplete - Optional autocomplete configuration
 * @returns Command instance for chaining
 */
function option(flags: string, description: string, autocomplete?: any): Command;

vorpal
  .command('deploy <environment>')
  .option('-f, --force', 'Force deployment without confirmation')
  .option('-v, --verbose', 'Show detailed deployment logs')
  .action(function(args, callback) {
    if (args.options.force) {
      this.log('Forcing deployment...');
    }
    if (args.options.verbose) {
      this.log('Verbose mode enabled');
    }
    callback();
  });

/**
 * Defines an alias for a given command
 * @param aliases - Single alias string or array of aliases
 * @returns Command instance for chaining
 */
function alias(...aliases: string[] | string[][]): Command;

vorpal
  .command('list', 'Lists items')
  .alias('ls', 'dir')
  .action(function(args, callback) {
    this.log('Listing items...');
    callback();
  });

/**
 * Returns the commands arguments as string
 * @param desc - Arguments description
 * @returns Command instance for chaining
 */
function arguments(desc: string): Command;

/**
 * Returns the command usage string for help
 * @param str - Usage string (optional for getter)
 * @returns Usage string (getter) or Command instance (setter)
 */
function usage(str?: string): string | Command;

/**
 * Defines an action for a given command
 * @param fn - Action function receiving args and callback
 * @returns Command instance for chaining
 */
function action(fn: (args: CommandArgs, callback: function) => void): Command;

interface CommandArgs {
  [key: string]: any;
  options: { [key: string]: any };
}

/**
 * Defines a function to validate arguments before action
 * @param fn - Validation function returning true/false or error message
 * @returns Command instance for chaining
 */
function validate(fn: (args: CommandArgs) => boolean | string): Command;

/**
 * Defines a function to be called when command is canceled
 * @param fn - Cancellation handler function
 * @returns Command instance for chaining
 */
function cancel(fn: () => void): Command;

/**
 * Defines a method to be called when command set has completed
 * @param fn - Completion handler function
 * @returns Command instance for chaining
 */
function done(fn: () => void): Command;

/**
 * Adds a command to be executed after command completion
 * @param fn - Post-command handler function
 * @returns Command instance for chaining
 */
function after(fn: () => void): Command;

/**
 * Edits the raw command string before execution
 * @param fn - Parser function that modifies command string
 * @returns Command instance for chaining
 */
function parse(fn: (command: string, args: CommandArgs) => string): Command;

/**
 * Defines an init action for a mode command
 * @param fn - Initialization function for mode entry
 * @returns Command instance for chaining
 */
function init(fn: (args: CommandArgs, callback: function) => void): Command;

/**
 * Defines a prompt delimiter for a mode once entered
 * @param delimiter - Delimiter string for mode prompt
 * @returns Command instance for chaining
 */
function delimiter(delimiter: string): Command;

/**
 * Defines tabbed auto-completion for the given command
 * @param obj - Autocomplete configuration object
 * @returns Command instance for chaining
 */
function autocomplete(obj: AutocompleteConfig): Command;

interface AutocompleteConfig {
  [key: string]: string[] | function;
}

vorpal
  .command('connect <server>')
  .autocomplete({
    server: ['production', 'staging', 'development', 'local']
  })
  .action(function(args, callback) {
    this.log(`Connecting to ${args.server}...`);
    callback();
  });

/**
 * Sets args for static typing of options using minimist
 * @param types - Type configuration object
 * @returns Command instance for chaining
 */
function types(types: TypesConfig): Command;

interface TypesConfig {
  string?: string[];
  boolean?: string[];
  number?: string[];
}

/**
 * Doesn't show command in the help menu
 * @returns Command instance for chaining
 */
function hidden(): Command;

/**
 * Allows undeclared options to be passed in with the command
 * @param allow - Whether to allow unknown options (default true)
 * @returns Command instance for chaining
 */
function allowUnknownOptions(allow?: boolean): Command;

/**
 * Adds a custom handling for the --help flag
 * @param fn - Custom help function (optional)
 * @returns Command instance for chaining
 */
function help(fn?: (cmd: Command) => string): Command;

/**
 * Let's you compose other functions to extend the command
 * @param fn - Extension function
 * @returns Result of extension function
 */
function use(fn: (command: Command) => any): any;

/**
 * Removes self from Vorpal instance
 * @returns Command instance
 */
function remove(): Command;

/**
 * Returns the help info for given command
 * @returns Help information string
 */
function helpInformation(): string;

/**
 * Returns the help string for the command's options
 * @returns Options help string
 */
function optionHelp(): string;

const vorpal = require('vorpal')();

vorpal
  .command('deploy <environment> [version]', 'Deploy application to environment')
  .alias('d')
  .option('-f, --force', 'Force deployment without confirmation')
  .option('-v, --verbose', 'Show detailed deployment logs')
  .option('-t, --timeout <seconds>', 'Deployment timeout in seconds')
  .types({
    string: ['environment', 'version'],
    number: ['timeout'],
    boolean: ['force', 'verbose']
  })
  .autocomplete({
    environment: ['production', 'staging', 'development']
  })
  .validate(function(args) {
    if (!['production', 'staging', 'development'].includes(args.environment)) {
      return 'Environment must be production, staging, or development';
    }
    return true;
  })
  .action(function(args, callback) {
    const env = args.environment;
    const version = args.version || 'latest';
    const force = args.options.force;
    const verbose = args.options.verbose;
    const timeout = args.options.timeout || 300;
    
    if (verbose) {
      this.log(`Deploying version ${version} to ${env}...`);
      this.log(`Timeout: ${timeout} seconds`);
      this.log(`Force mode: ${force ? 'enabled' : 'disabled'}`);
    }
    
    // Deploy logic here
    this.log(`Successfully deployed to ${env}!`);
    callback();
  });