CLI Builder

/**
 * Creates a new CLI builder instance
 * @param brand - Optional brand name for the CLI (used for configuration files)
 * @returns Builder instance for fluent configuration
 */
function build(brand?: string): Builder;

import { build } from "gluegun";

const cli = build("my-cli")
  .src(`${__dirname}/commands`)
  .help()
  .version()
  .create();

interface Builder {
  /**
   * Set the CLI brand name used for configuration file discovery
   * @param value - Brand name (lowercase, numbers, letters, dashes only)
   * @returns Builder instance for chaining
   */
  brand(value: string): Builder;

  /**
   * Exclude core extensions for performance optimization
   * @param excludes - Array of extension names to exclude
   * @returns Builder instance for chaining
   */
  exclude(excludes: string[]): Builder;

  /**
   * Set the source directory for default commands and extensions
   * @param value - Path to source directory
   * @param options - Additional plugin loading options
   * @returns Builder instance for chaining
   */
  src(value: string, options?: GluegunLoadOptions): Builder;

  /**
   * Add a single plugin directory
   * @param value - Plugin directory path
   * @param options - Additional loading options
   * @returns Builder instance for chaining
   */
  plugin(value: string, options?: GluegunLoadOptions): Builder;

  /**
   * Add a directory containing multiple plugins
   * @param value - Directory path with plugin subdirectories
   * @param options - Loading options with optional matching pattern
   * @returns Builder instance for chaining
   */
  plugins(value: string, options?: GluegunLoadOptions & GluegunMultiLoadOptions): Builder;

  /**
   * Add default help command handler
   * @param command - Optional custom help command function or object
   * @returns Builder instance for chaining
   */
  help(command?: any): Builder;

  /**
   * Add default version command handler
   * @param command - Optional custom version command function or object
   * @returns Builder instance for chaining
   */
  version(command?: any): Builder;

  /**
   * Set default command that runs when no other command matches
   * @param command - Optional custom default command function or object
   * @returns Builder instance for chaining
   */
  defaultCommand(command?: any): Builder;

  /**
   * Add an arbitrary command to the CLI
   * @param command - Command definition object
   * @returns Builder instance for chaining
   */
  command(command: GluegunCommand): Builder;

  /**
   * Enable random update checking
   * @param frequency - Percentage frequency of update checks (0-100)
   * @returns Builder instance for chaining
   */
  checkForUpdates(frequency: number): Builder;

  /**
   * Create the configured runtime instance
   * @returns Runtime instance ready for execution
   */
  create(): Runtime;
}

import { build } from "gluegun";

// Basic CLI with help and version
const basicCLI = build("basic")
  .help()
  .version()
  .create();

// Advanced CLI with plugins and custom commands
const advancedCLI = build("advanced")
  .src(`${__dirname}/src`)
  .plugins("node_modules", { matching: "advanced-*" })
  .plugin("./custom-plugin")
  .exclude(["semver", "http"])
  .help()
  .version()
  .defaultCommand()
  .checkForUpdates(10) // 10% chance
  .create();

// Run the CLI
await advancedCLI.run();

interface Runtime {
  /**
   * Execute CLI commands with optional parameters
   * @param rawCommand - Command string or options object
   * @param extraOptions - Additional execution options
   * @returns Promise resolving to toolbox instance
   */
  run(rawCommand?: string | Options, extraOptions?: Options): Promise<GluegunToolbox>;

  /**
   * Load core extensions into the runtime
   * @param exclude - Array of extension names to exclude
   */
  addCoreExtensions(exclude?: string[]): void;

  /**
   * Add a command to the runtime
   * @param command - Command definition
   * @returns Runtime instance for chaining
   */
  addCommand(command: GluegunCommand): Runtime;

  /**
   * Add a toolbox extension to the runtime
   * @param name - Extension name
   * @param setup - Extension setup function
   * @returns Runtime instance for chaining
   */
  addExtension(name: string, setup: any): Runtime;

  /**
   * Set the default plugin directory
   * @param directory - Plugin directory path
   * @param options - Loading options
   * @returns Runtime instance for chaining
   */
  addDefaultPlugin(directory: string, options?: GluegunLoadOptions): Runtime;

  /**
   * Load a plugin from a directory
   * @param directory - Plugin directory path
   * @param options - Loading options
   * @returns Loaded plugin instance or null if failed
   */
  addPlugin(directory: string, options?: GluegunLoadOptions): Plugin | null;

  /**
   * Load multiple plugins from a directory
   * @param directory - Directory containing plugin subdirectories
   * @param options - Loading options with matching pattern
   * @returns Array of loaded plugin instances
   */
  addPlugins(directory: string, options?: GluegunLoadOptions & GluegunMultiLoadOptions): Plugin[];

  /** CLI brand name */
  brand?: string;
  /** Loaded plugins */
  plugins: Plugin[];
  /** Available extensions */
  extensions: Extension[];
  /** Available commands */
  commands: Command[];
  /** Default configuration */
  defaults: Options;
  /** Update check enabled flag */
  checkUpdate: boolean;
}

interface GluegunLoadOptions {
  /** Hide plugin from CLI help listings */
  hidden?: boolean;
  /** Glob patterns for command files (default: ['*.js', '*.ts']) */
  commandFilePattern?: string[];
  /** Glob patterns for extension files (default: ['*.js', '*.ts']) */
  extensionFilePattern?: string[];
  /** Require plugin directory to exist */
  required?: boolean;
  /** Override plugin name */
  name?: string;
  /** Pre-loaded command objects */
  preloadedCommands?: object[];
}

interface GluegunMultiLoadOptions {
  /** Glob pattern to match plugin directories */
  matching?: string;
}

// Load plugins with specific patterns
const cli = build("my-cli")
  .plugins("./plugins", {
    matching: "my-cli-*",
    commandFilePattern: ["commands/*.js"],
    extensionFilePattern: ["extensions/*.js"]
  })
  .create();

// Load hidden plugin
const cli = build("my-cli")
  .plugin("./internal-plugin", { hidden: true })
  .create();