@moostjs/event-cli/dist/index.d.ts

@moostjs/event-cli

import { WooksCli, TWooksCliOptions } from '@wooksjs/event-cli';
export { cliKind } from '@wooksjs/event-cli';
import * as moost from 'moost';
import { TFunction, TMoostAdapter, Moost, TMoostAdapterOptions } from 'moost';
export { Controller, Description, Intercept, Optional, Param, TInterceptorPriority, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor } from 'moost';

/**
 * ## Define CLI Command
 * ### @MethodDecorator
 *
 * Command path segments may be separated by / or space.
 *
 * For example the folowing path are interpreted the same:
 * - "command test use:dev :name"
 * - "command/test/use:dev/:name"
 *
 * Where name will become an argument
 *
 * @param path - command path
 * @returns
 */
declare function Cli(path?: string): MethodDecorator;
/**
 * ## Define CLI Command Alias
 * ### @MethodDecorator
 *
 * Use it to define alias for @Cli('...') command
 *
 * @param path - command alias path
 * @returns
 */
declare function CliAlias(alias: string): MethodDecorator;
/**
 * ## Define CLI Example
 * ### @MethodDecorator
 *
 * Use it to define example for Cli Help display
 *
 * @param path - command alias path
 * @returns
 */
declare function CliExample(cmd: string, description?: string): MethodDecorator;

/**
 * ## Define CLI Option
 * ### @ParameterDecorator
 * Use together with @Description('...') to document cli option
 *
 * ```ts
 * │   @Cli('command')
 * │   command(
 * │      @Description('Test option...')
 * │      @CliOption('test', 't')
 * │      test: boolean,
 * │   ) {
 * │       return `test=${ test }`
 * │   }
 * ```
 *
 * @param keys list of keys (short and long alternatives)
 * @returns
 */
declare function CliOption(...keys: string[]): ParameterDecorator;
/**
 * ## Define Global CLI Option
 * ### @ClassDecorator
 * The option described here will appear in every command instructions
 * @param option keys and description of CLI option
 * @returns
 */
declare function CliGlobalOption(option: {
    keys: string[];
    description?: string;
    value?: string;
}): ClassDecorator;

/** Handler metadata for CLI events, carrying the command path. */
interface TCliHandlerMeta {
    path: string;
}
/** Configuration options for the MoostCli adapter. */
interface TMoostCliOpts {
    /**
     * WooksCli options or instance
     */
    wooksCli?: WooksCli | TWooksCliOptions;
    /**
     * more internal logs are printed when true
     */
    debug?: boolean;
    /**
     * Array of cli options applicable to every cli command
     */
    globalCliOptions?: {
        keys: string[];
        description?: string;
        type?: TFunction;
    }[];
}
/**
 * ## Moost Cli Adapter
 *
 * Moost Adapter for CLI events
 *
 * ```ts
 * │  // Quick example
 * │  import { MoostCli, Cli, CliOption, cliHelpInterceptor } from '@moostjs/event-cli'
 * │  import { Moost, Param } from 'moost'
 * │
 * │  class MyApp extends Moost {
 * │      @Cli('command/:arg')
 * │      command(
 * │         @Param('arg')
 * │         arg: string,
 * │         @CliOption('test', 't')
 * │         test: boolean,
 * │      ) {
 * │          return `command run with flag arg=${ arg }, test=${ test }`
 * │      }
 * │  }
 * │
 * │  const app = new MyApp()
 * │  app.applyGlobalInterceptors(cliHelpInterceptor())
 * │
 * │  const cli = new MoostCli()
 * │  app.adapter(cli)
 * │  app.init()
 * ```
 */
declare class MoostCli implements TMoostAdapter<TCliHandlerMeta> {
    protected opts?: TMoostCliOpts | undefined;
    readonly name = "cli";
    protected cliApp: WooksCli;
    protected optionTypes: Record<string, TFunction[]>;
    constructor(opts?: TMoostCliOpts | undefined);
    onNotFound(): Promise<unknown>;
    protected moost?: Moost;
    onInit(moost: Moost): void;
    bindHandler<T extends object = object>(opts: TMoostAdapterOptions<TCliHandlerMeta, T>): void;
}

/**
 * ### Interceptor Factory for CliHelpRenderer
 *
 * By default intercepts cli calls with flag --help
 * and prints help.
 *
 * ```js
 * new Moost().applyGlobalInterceptors(cliHelpInterceptor({ colors: true }))
 * ```
 * @param opts {} { helpOptions: ['help', 'h'], colors: true } cli options to invoke help renderer
 * @returns TInterceptorDef
 */
declare const cliHelpInterceptor: (opts?: {
    /**
     * CLI Options that invoke help
     * ```js
     * helpOptions: ['help', 'h']
     * ```
     */
    helpOptions?: string[];
    /**
     * Enable colored help
     */
    colors?: boolean;
    /**
     * Enable lookup for a command
     */
    lookupLevel?: number;
}) => moost.TInterceptorDef;
/**
 * ## @Decorator
 * ### Interceptor Factory for CliHelpRenderer
 *
 * By default intercepts cli calls with flag --help
 * and prints help.
 *
 * ```ts
 * // default configuration
 * • @CliHelpInterceptor({ helpOptions: 'help', colors: true })
 *
 * // additional option -h to invoke help renderer
 * • @CliHelpInterceptor({ helpOptions: ['help', 'h'], colors: true })
 *
 * // redefine cli option to invoke help renderer
 * • @CliHelpInterceptor({ helpOptions: ['usage'] })
 * ```
 *
 * @param opts {} { helpOptions: ['help', 'h'], colors: true } cli options to invoke help renderer
 * @returns Decorator
 */
declare const CliHelpInterceptor: (...opts: Parameters<typeof cliHelpInterceptor>) => ClassDecorator & MethodDecorator;

interface THelpOptions {
    name?: string;
    title?: string;
    maxWidth?: number;
    maxLeft?: number;
    mark?: string;
    colors?: boolean;
    lookupLevel?: number;
}
/**
 * Quick CLI App factory class.
 *
 * Use this class to quickly build a CLI application with controllers, help options,
 * and global CLI options. It extends the Moost class and wraps the initialization of MoostCli.
 *
 * @example
 * ```typescript
 * import { CliApp } from '@wooksjs/event-cli'
 * import { Commands } from './commands.controller.ts'
 * new CliApp()
 *  .controllers(Commands)
 *  .useHelp({ name: 'myCli' })
 *  .useOptions([{ keys: ['help'], description: 'Display instructions for the command.' }])
 *  .start()
 * ```
 */
declare class CliApp extends Moost {
    protected _helpOpts?: THelpOptions;
    protected _globalOpts?: TMoostCliOpts['globalCliOptions'];
    /**
     * Registers one or more CLI controllers.
     *
     * (Shortcut for `registerControllers` method.)
     *
     * @param {...(object|Function|[string, object|Function])} controllers - List of controllers.
     *   Each controller can be an object, a class, or a tuple with a name and the controller.
     * @returns {this} The CliApp instance for method chaining.
     */
    controllers(...controllers: (object | Function | [string, object | Function])[]): this;
    /**
     * Configures the CLI help options.
     *
     * This method sets the help options for the CLI. It ensures that colored output is enabled
     * (unless explicitly disabled) and that the lookup level defaults to 3 if not provided.
     *
     * @param {THelpOptions} helpOpts - Help options configuration.
     * @param {boolean} helpOpts.colors - Enable colored output.
     * @param {number} helpOpts.lookupLevel - Level for help lookup.
     * @returns {this} The CliApp instance for method chaining.
     */
    useHelp(helpOpts: THelpOptions): this;
    /**
     * Sets the global CLI options.
     *
     * @param {TMoostCliOpts['globalCliOptions']} globalOpts - Global options for the CLI.
     * @returns {this} The CliApp instance for method chaining.
     */
    useOptions(globalOpts: TMoostCliOpts['globalCliOptions']): this;
    /**
     * Starts the CLI application.
     *
     * This method creates a MoostCli instance using the configured help and global options,
     * attaches it via the adapter, applies the CLI help interceptor (if help options are set),
     * and then initializes the application.
     *
     * @returns {any} The result of the initialization process.
     */
    start(): Promise<void>;
}

export { Cli, CliAlias, CliApp, CliExample, CliGlobalOption, CliHelpInterceptor, CliOption, MoostCli, cliHelpInterceptor };
export type { TCliHandlerMeta, TMoostCliOpts };