Command System

/**
 * Create a new command instance
 * @param cmd Optional parent command for creating subcommands
 * @returns New command instance for chaining
 */
function Cmd(cmd?: Cmd): Cmd;

// Static creation method
Cmd.create(cmd?: Cmd): Cmd;

const COA = require('coa');

// Create root command
const rootCmd = COA.Cmd()
    .name('myapp')
    .title('My Application');

// Create subcommand
const subCmd = rootCmd.cmd()
    .name('build')
    .title('Build the project');

/**
 * Set canonical command identifier
 * @param name Command name used in CLI and API
 * @returns Command instance for chaining
 */
name(name: string): Cmd;

/**
 * Set command description for help text
 * @param title Human-readable command description
 * @returns Command instance for chaining
 */
title(title: string): Cmd;

/**
 * Create or add subcommand
 * @param cmd Optional existing command instance
 * @returns New or existing subcommand instance
 */
cmd(cmd?: Cmd): Cmd;

/**
 * Create new option for this command
 * @returns New option instance
 */
opt(): Opt;

/**
 * Create new argument for this command
 * @returns New argument instance
 */
arg(): Arg;

const cmd = COA.Cmd()
    .name('deploy')
    .title('Deploy application to server')
    .opt()
        .name('env')
        .title('Target environment')
        .short('e')
        .long('env')
        .def('staging')
        .end()
    .arg()
        .name('service')
        .title('Service name to deploy')
        .req()
        .end();

/**
 * Add action function for command execution
 * @param act Function called when command runs
 * @param force Optional flag to replace instead of append actions
 * @returns Command instance for chaining
 */
act(act: ActionFunction, force?: boolean): Cmd;

type ActionFunction = (
    opts: any,    // Parsed options object
    args: any[],  // Parsed arguments array
    res?: any     // Results accumulator from previous actions
) => any;        // Return value or Promise

const cmd = COA.Cmd()
    .name('process')
    .title('Process data files')
    .act(function(opts, args, res) {
        console.log('Processing with options:', opts);
        console.log('Arguments:', args);
        
        // Can return promises for async operations
        return Promise.resolve('Processing complete');
    })
    .act(function(opts, args, res) {
        // Multiple actions are chained
        console.log('Previous result:', res);
        return 'Final result';
    });

/**
 * Parse argv and run command (calls process.exit)
 * @param argv Command line arguments (defaults to process.argv.slice(2))
 * @returns Command instance for chaining
 */
run(argv?: string[]): Cmd;

/**
 * Invoke command programmatically with structured parameters
 * @param cmds Optional subcommand path (string or array)
 * @param opts Optional options object
 * @param args Optional arguments object
 * @returns Promise resolving to command result
 */
invoke(cmds?: string|string[], opts?: any, args?: any): Promise<any>;

/**
 * Execute command for testing (doesn't call process.exit)
 * @param argv Command line arguments array
 * @returns Promise resolving to command result
 */
do(argv?: string[]): Promise<any>;

// CLI execution (for main program)
cmd.run(); // Uses process.argv automatically

// Programmatic execution
const result = await cmd.invoke(['subcommand'], { verbose: true }, { file: 'input.txt' });

// Testing execution
const testResult = await cmd.do(['-v', 'build', 'project.json']);

/**
 * Add -h, --help flags with automatic usage generation
 * @returns Command instance for chaining
 */
helpful(): Cmd;

/**
 * Add shell completion support (must be called on root command)
 * @returns Command instance for chaining
 */
completable(): Cmd;

/**
 * Generate usage text for command
 * @returns Formatted usage string
 */
usage(): string;

const cmd = COA.Cmd()
    .name('myapp')
    .title('My Application')
    .helpful()      // Adds -h, --help
    .completable(); // Adds completion subcommand

// Manual usage generation
console.log(cmd.usage());

/**
 * Allow command extension via external Node.js modules
 * @param pattern Optional pattern for finding extension modules
 * @returns Command instance for chaining
 */
extendable(pattern?: string): Cmd;

/**
 * Apply function in command context
 * @param fn Function to apply
 * @param args Optional arguments for function
 * @returns Command instance for chaining
 */
apply(fn: Function, args?: any[]): Cmd;

/**
 * Set custom completion function
 * @param fn Completion generation function
 * @returns Command instance for chaining
 */
comp(fn: CompletionFunction): Cmd;

type CompletionFunction = (opts: any) => any;

// Enable extension loading
cmd.extendable('myapp-%s');

// Apply external configuration
cmd.apply(require('./config/commands'));

// Custom completion
cmd.comp(function(opts) {
    return ['option1', 'option2', 'option3'];
});

/**
 * API method provides programmatic access to commands
 * Returns function that can be called like command invoke
 */
api(): any;

const cmd = COA.Cmd()
    .name('myapp')
    .cmd()
        .name('build')
        .act(function(opts, args) {
            return 'Built successfully';
        })
        .end();

// Use as API
const api = cmd.api();
const result = await api.build({}, {});
console.log(result); // 'Built successfully'

/**
 * Return rejected promise for error handling
 * @param reason Error reason or message
 * @returns Rejected promise
 */
reject(reason: any): Promise<never>;

/**
 * End current command chain and return parent
 * @returns Parent command instance
 */
end(): Cmd;

const cmd = COA.Cmd()
    .act(function(opts, args) {
        if (!args.length) {
            return this.reject('No arguments provided');
        }
        return 'Success';
    });

// Subcommand creation with end()
const parent = COA.Cmd()
    .name('parent')
    .cmd()           // Create subcommand
        .name('sub')
        .title('Subcommand')
        .end()       // Return to parent
    .helpful();      // Configure parent