Command System

/**
 * Command definition interface
 * @template TContext - Toolbox context type (defaults to GluegunToolbox)
 */
interface GluegunCommand<TContext = GluegunToolbox> {
  /** Command name used for invocation */
  name?: string;
  /** Human-readable description for help text */
  description?: string;
  /** Main command execution function */
  run: (toolbox: TContext) => void | Promise<void>;
  /** Hide command from help listings */
  hidden?: boolean;
  /** Command path array for nested commands */
  commandPath?: string[];
  /** Alternative command names */
  alias?: string | string[];
  /** Allow dashed execution (e.g., --version, -v) */
  dashed?: boolean;
  /** Source file path */
  file?: string;
  /** Parent plugin reference */
  plugin?: Plugin;
}

// Basic command
export = {
  name: "hello",
  description: "Say hello to the world",
  run: async (toolbox) => {
    const { print } = toolbox;
    print.success("Hello, world!");
  }
};

// Command with alias
export = {
  name: "generate",
  alias: ["g", "gen"],
  description: "Generate files from templates",
  run: async (toolbox) => {
    const { parameters, template, print } = toolbox;
    const type = parameters.first;
    
    if (!type) {
      print.error("Please specify what to generate");
      return;
    }
    
    await template.generate({
      template: `${type}.ejs`,
      target: `${type}.js`,
      props: { name: parameters.second }
    });
  }
};

// Dashed command (accessible via --info or -i)
export = {
  name: "info",
  alias: "i",
  dashed: true,
  description: "Show CLI information",
  run: async (toolbox) => {
    const { meta, print } = toolbox;
    print.info(`Version: ${meta.version()}`);
  }
};

interface GluegunToolbox {
  /** Configuration object merged from various sources */
  config: Options;
  /** Result from command execution */
  result?: any;
  /** Parsed command line parameters */
  parameters: GluegunParameters;
  /** Current plugin reference */
  plugin?: Plugin;
  /** Current command reference */
  command?: Command;
  /** Current plugin name */
  pluginName?: string;
  /** Current command name */
  commandName?: string;
  /** Runtime instance */
  runtime?: Runtime;
  
  // Toolbox extensions
  /** Filesystem operations */
  filesystem: GluegunFilesystem;
  /** HTTP client utilities */
  http: GluegunHttp;
  /** CLI metadata and information */
  meta: GluegunMeta;
  /** File patching and modification */
  patching: GluegunPatching;
  /** Print and output utilities */
  print: GluegunPrint;
  /** Interactive prompts */
  prompt: GluegunPrompt;
  /** Semantic versioning utilities */
  semver: GluegunSemver;
  /** String manipulation functions */
  strings: GluegunStrings;
  /** System command execution */
  system: GluegunSystem;
  /** Template generation */
  template: GluegunTemplate;
  /** File generation utilities */
  generate: any;
  /** Package manager integration */
  packageManager: GluegunPackageManager;
}

/** Backwards compatibility alias */
type GluegunRunContext = GluegunToolbox;

interface GluegunParameters {
  /** Command arguments as array */
  array?: string[];
  /** Optional parameters from CLI flags and options */
  options: Options;
  /** First command argument */
  first?: string;
  /** Second command argument */
  second?: string;
  /** Third command argument */
  third?: string;
  /** Everything after command name as single string */
  string?: string;
  /** Raw command object with named parameters */
  raw?: any;
  /** Original process.argv */
  argv?: any;
  /** Current plugin name */
  plugin?: string;
  /** Current command name */
  command?: string;
}

// Command: my-cli generate component UserCard --typescript --export
export = {
  name: "generate",
  run: async (toolbox) => {
    const { parameters, print } = toolbox;
    
    // Access arguments
    const type = parameters.first;        // "component"
    const name = parameters.second;       // "UserCard"
    const third = parameters.third;       // undefined
    const allArgs = parameters.array;     // ["component", "UserCard"]
    
    // Access options/flags
    const useTS = parameters.options.typescript;  // true
    const shouldExport = parameters.options.export; // true
    
    // Access raw string
    const rawCommand = parameters.string; // "component UserCard --typescript --export"
    
    print.info(`Generating ${type}: ${name}`);
    if (useTS) print.info("Using TypeScript");
  }
};

class Command {
  /**
   * Create a command instance
   * @param props - Command properties
   */
  constructor(props?: GluegunCommand);

  /**
   * Get normalized aliases array
   */
  get aliases(): string[];

  /**
   * Check if command has any aliases
   * @returns True if command has aliases
   */
  hasAlias(): boolean;

  /**
   * Check if alias matches this command
   * @param alias - Single alias string or array of aliases
   * @returns True if alias matches
   */
  matchesAlias(alias: string | string[]): boolean;
}

class Plugin {
  /** Plugin name */
  name?: string;
  /** Plugin description */
  description?: string;
  /** Default configuration */
  defaults: Options;
  /** Plugin directory path */
  directory?: string;
  /** Hide plugin from CLI */
  hidden: boolean;
  /** Plugin commands */
  commands: Command[];
  /** Plugin extensions */
  extensions: Extension[];
}

class Extension {
  /** Extension name */
  name?: string;
  /** Extension description */
  description?: string;
  /** Source file path */
  file?: string;
  /** Setup function to initialize extension */
  setup?: (toolbox: EmptyToolbox) => void | Promise<void>;
}

my-plugin/
├── commands/
│   ├── create.js      # Command: my-cli create
│   └── deploy.js      # Command: my-cli deploy
├── extensions/
│   └── database.js    # Adds toolbox.database
└── package.json

// extensions/database.js
module.exports = (toolbox) => {
  const { filesystem } = toolbox;
  
  toolbox.database = {
    connect: async (url) => {
      // Database connection logic
    },
    migrate: async () => {
      // Migration logic
    }
  };
};

interface Options {
  /** Flexible key-value configuration object */
  [key: string]: any;
}