Base Command Framework

/**
 * Abstract base command class for all egg-bin commands
 * Provides common functionality including process forking and requirement handling
 */
abstract class BaseCommand extends Command {
  /** Whether to show full command script only, default false */
  dryRun: boolean;
  
  /** Array of modules to require, supports multiple values */
  require: string[];
  
  /** Injected command context from Artus CLI */
  ctx: CommandContext;
  
  /** Injected utilities from Artus CLI */
  utils: Utils;
  
  /** Application base directory getter */
  protected get base(): string;
  
  /**
   * Run method with default help redirection implementation
   * Individual commands override this with their specific logic
   */
  run(): Promise<void>;
  
  /**
   * Formats require modules from command options and package.json
   * Combines --require options with pkg.egg.require configuration
   * @returns Promise resolving to array of module paths to require
   */
  protected formatRequires(): Promise<string[]>;
  
  /**
   * Forks a Node.js process with graceful shutdown handling
   * Includes dry-run support and comprehensive error handling
   * @param modulePath - Path to the module to execute
   * @param args - Arguments to pass to the forked process
   * @param options - Fork options, merged with defaults
   * @returns Promise that resolves when process exits successfully
   */
  protected forkNode(
    modulePath: string, 
    args: string[], 
    options?: ForkOptions
  ): Promise<void>;
}

/**
 * Process management and graceful shutdown system
 * Handles child process lifecycle and signal propagation
 */
interface ProcessManagement {
  /** Set of active child processes */
  childs: Set<ChildProcess>;
  
  /** Hook status for signal handlers */
  hadHook: boolean;
  
  /** Signal handling for graceful shutdown */
  signals: ['SIGINT', 'SIGQUIT', 'SIGTERM'];
  
  /**
   * Registers child process for graceful shutdown
   * @param proc - Child process to track
   */
  gracefull(proc: ChildProcess): void;
  
  /** Process exit handler that kills all children */
  exitHandler(code: number): void;
}

/**
 * Node.js process forking configuration
 * Extends Node.js ForkOptions with egg-bin specific defaults
 */
interface EnhancedForkOptions extends ForkOptions {
  /** Process stdio configuration, default 'inherit' */
  stdio: 'inherit';
  
  /** Environment variables, inherits from command context */
  env: Record<string, any>;
  
  /** Working directory, defaults to base directory */
  cwd: string;
  
  /** Execution arguments for Node.js */
  execArgv: string[];
}

/**
 * Fork-specific error class with exit code information
 * Provides detailed error context for process failures
 */
class ForkError extends Error {
  /** Process exit code, null if killed by signal */
  code: number | null;
  
  /**
   * Creates a fork error with exit code context
   * @param message - Error message describing the failure
   * @param code - Process exit code
   */
  constructor(message: string, code: number | null);
}

/**
 * Module requirement management system
 * Handles --require options and package.json egg.require configuration
 */
interface RequirementManagement {
  /** Command-line require options */
  cliRequires: string[];
  
  /** Package.json egg.require configuration */
  pkgRequires: string | string[];
  
  /** Combined requirements array */
  allRequires: string[];
  
  /**
   * Formats and combines all requirement sources
   * @returns Promise resolving to array of module paths
   */
  formatRequires(): Promise<string[]>;
}

# Single require module
egg-bin dev --require ./setup.js

# Multiple require modules  
egg-bin test --require ./setup.js --require ./mocks.js

# Package.json configuration
{
  "egg": {
    "require": ["./app/extend/helper.js", "./test/setup.js"]
  }
}

/**
 * Dry run execution mode
 * Shows command that would be executed without running it
 */
interface DryRunSupport {
  /** Dry run flag */
  dryRun: boolean;
  
  /** Command preview format */
  previewFormat: string;  // '$ {execPath} {modulePath} {args}'
  
  /**
   * Displays command without execution
   * @param execPath - Node.js executable path
   * @param modulePath - Module to execute
   * @param args - Command arguments
   */
  showCommand(execPath: string, modulePath: string, args: string[]): void;
}

/**
 * Artus CLI framework integration
 * Provides access to command context, utilities, and framework features
 */
interface ContextIntegration {
  /** Command execution context */
  ctx: CommandContext;
  
  /** Artus utilities */
  utils: Utils;
  
  /** Command arguments and options */
  args: Record<string, any>;
  
  /** Environment variables */
  env: Record<string, any>;
  
  /** Current working directory */
  cwd: string;
  
  /** Package.json egg configuration */
  pkgEgg: Record<string, any>;
}

/**
 * Debug logging integration
 * Uses Node.js debuglog for conditional logging
 */
interface DebugIntegration {
  /** Debug logger instance */
  debug: debug.Debugger;  // debuglog('egg-bin:base')
  
  /** Debug categories */
  categories: [
    'egg-bin:base',
    'egg-bin:dev', 
    'egg-bin:test',
    'egg-bin:middleware:*'
  ];
  
  /** Enable debugging via NODE_DEBUG environment */
  enableDebugging: 'NODE_DEBUG=egg-bin:*';
}

/**
 * Command execution flow
 * Standardized lifecycle for all egg-bin commands
 */
interface ExecutionFlow {
  /** Pre-execution setup */
  setup: [
    'Parse command arguments',
    'Load package.json configuration', 
    'Format requirements',
    'Setup environment variables'
  ];
  
  /** Main execution */
  execution: [
    'Validate configuration',
    'Prepare arguments',
    'Fork child process',
    'Monitor process'
  ];
  
  /** Post-execution cleanup */
  cleanup: [
    'Handle process exit',
    'Clean up resources',
    'Report results'
  ];
}

/**
 * Command registration and discovery
 * Uses Artus CLI decorators for automatic command registration
 */
interface CommandRegistration {
  /** DefineCommand decorator configuration */
  commandConfig: {
    command: string;     // Command name and arguments
    description: string; // Help description
    alias?: string[];    // Command aliases
  };
  
  /** Option decorator configuration */
  optionConfig: {
    description: string;  // Option description
    alias?: string | string[];  // Option aliases
    type?: string;       // Option type
    default?: any;       // Default value
    array?: boolean;     // Array support
  };
}