@wooksjs/event-cli 0.2.23 → 0.3.1

package/README.md

@@ -13,7 +13,7 @@ As a part of `wooks` event processing framework, `@wooksjs/event-cli` implements
 
 -   access flags (- or --)
 
-## Install
+## Installation
 
 `npm install wooks @wooksjs/event-cli`
 
@@ -21,13 +21,13 @@ As a part of `wooks` event processing framework, `@wooksjs/event-cli` implements
 
 ```js
 import { useRouteParams } from 'wooks'
-import { createCliApp, useFlags } from '@wooksjs/event-cli'
+import { createCliApp, useCliOptions } from '@wooksjs/event-cli'
 
 const app = createCliApp()
 
 app.cli('test', () => {
-    console.log('flags:')
-    return useFlags()
+    console.log('options:')
+    return useCliOptions()
 })
 
 app.cli(':arg', () => {
@@ -43,4 +43,4 @@ app.run()
 
 ## Documentation
 
-To check out docs, visit [wooksjs.org](https://wooksjs.org/).
+To check out docs, visit [wooksjs.org](https://wooksjs.org/guide/cli/).

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var eventCore = require('@wooksjs/event-core');
 var wooks = require('wooks');
+var cliHelp = require('@prostojs/cli-help');
 var minimist = require('minimist');
 
 function createCliContext(data, options) {
@@ -10,6 +11,11 @@ function createCliContext(data, options) {
         options,
     });
 }
+/**
+ * Wrapper on top of useEventContext that provides
+ * proper context types for CLI event
+ * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
+ */
 function useCliContext() {
     return eventCore.useEventContext('CLI');
 }
@@ -48,22 +54,138 @@ class WooksCli extends wooks.WooksAdapterBase {
     constructor(opts, wooks) {
         super(wooks, opts === null || opts === void 0 ? void 0 : opts.logger);
         this.opts = opts;
+        this.alreadyComputedAliases = false;
         this.logger = (opts === null || opts === void 0 ? void 0 : opts.logger) || this.getLogger('wooks-cli');
+        this.cliHelp =
+            (opts === null || opts === void 0 ? void 0 : opts.cliHelp) instanceof cliHelp.CliHelpRenderer
+                ? opts.cliHelp
+                : new cliHelp.CliHelpRenderer(opts === null || opts === void 0 ? void 0 : opts.cliHelp);
     }
-    cli(path, handler) {
-        return this.on('CLI', path, handler);
+    /**
+     * ### Register CLI Command
+     * 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
+     *
+     * ```js
+     * // example without options
+     * app.cli('command/:arg', () => 'arg = ' + useRouteParams().params.arg )
+     *
+     * // example with options
+     * app.cli('command/:arg', {
+     *   description: 'Description of the command',
+     *   options: [{ keys: ['project', 'p'], description: 'Description of the option', value: 'myProject' }],
+     *   args: { arg: 'Description of the arg' },
+     *   aliases: ['cmd'],  // alias "cmd/:arg" will be registered
+     *   examples: [{
+     *      description: 'Example of usage with someProject',
+     *      cmd: 'argValue -p=someProject',
+     *      // will result in help display:
+     *      // "# Example of usage with someProject\n" +
+     *      // "$ myCli command argValue -p=someProject\n"
+     *   }],
+     *   handler: () => 'arg = ' + useRouteParams().params.arg
+     * })
+     * ```
+     *
+     * @param path command path
+     * @param _options handler or options
+     *
+     * @returns
+     */
+    cli(path, _options) {
+        const options = typeof _options === 'function' ? { handler: _options } : _options;
+        const handler = typeof _options === 'function' ? _options : _options.handler;
+        const makePath = (s) => '/' + s.replace(/\s+/g, '/');
+        // register handler
+        const targetPath = makePath(path);
+        const routed = this.on('CLI', targetPath, handler);
+        if (options.onRegister) {
+            options.onRegister(targetPath, 0);
+        }
+        // register direct aliases
+        for (const alias of options.aliases || []) {
+            const vars = routed.getArgs().map((k) => ':' + k).join('/');
+            const targetPath = makePath(alias) + (vars ? '/' + vars : '');
+            this.on('CLI', targetPath, handler);
+            if (options.onRegister) {
+                options.onRegister(targetPath, 1);
+            }
+        }
+        // register helpCli entry
+        const command = routed.getStaticPart().replace(/\//g, ' ').trim();
+        const args = Object.assign({}, (options.args || {}));
+        for (const arg of routed.getArgs()) {
+            if (!args[arg]) {
+                args[arg] = '';
+            }
+        }
+        this.cliHelp.addEntry({
+            command,
+            aliases: options.aliases,
+            args,
+            description: options.description,
+            examples: options.examples,
+            options: options.options,
+            custom: { handler: options.handler, cb: options.onRegister },
+        });
+        return routed;
+    }
+    computeAliases() {
+        if (!this.alreadyComputedAliases) {
+            this.alreadyComputedAliases = true;
+            const aliases = this.cliHelp.getComputedAliases();
+            for (const [alias, entry] of Object.entries(aliases)) {
+                if (entry.custom) {
+                    const vars = Object.keys(entry.args || {})
+                        .map((k) => ':' + k)
+                        .join('/');
+                    const path = '/' +
+                        alias.replace(/\s+/g, '/').replace(/:/g, '\\:') +
+                        (vars ? '/' + vars : '');
+                    this.on('CLI', path, entry.custom.handler);
+                    if (entry.custom.cb) {
+                        entry.custom.cb(path, 3);
+                    }
+                }
+            }
+        }
     }
+    /**
+     * ## run
+     * ### Start command processing
+     * Triggers command processing
+     *
+     * By default takes `process.argv.slice(2)` as a command
+     *
+     * It's possible to replace the command by passing an argument
+     *
+     * @param _argv optionally overwrite `process.argv.slice(2)` with your `argv` array
+     */
     run(_argv) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
-            const argv = process.argv.slice(2) || _argv;
+            const argv = _argv || process.argv.slice(2);
             const firstFlagIndex = argv.findIndex((a) => a.startsWith('-')) + 1;
-            const pathParams = (firstFlagIndex
+            const pathParams = firstFlagIndex
                 ? argv.slice(0, firstFlagIndex - 1)
-                : argv);
-            const path = '/' + pathParams.map((v) => encodeURI(v).replace(/\//g, '%2F')).join('/');
-            const { restoreCtx, clearCtx } = createCliContext({ argv, pathParams }, this.mergeEventOptions((_a = this.opts) === null || _a === void 0 ? void 0 : _a.eventOptions));
-            const handlers = this.wooks.lookup('CLI', path) || ((_b = this.opts) === null || _b === void 0 ? void 0 : _b.onNotFound) && [this.opts.onNotFound] || null;
+                : argv;
+            const path = '/' +
+                pathParams.map((v) => encodeURI(v).replace(/\//g, '%2F')).join('/');
+            const { restoreCtx, clearCtx, store } = createCliContext({ argv, pathParams, cliHelp: this.cliHelp, command: path.replace(/\//g, ' ').trim() }, this.mergeEventOptions((_a = this.opts) === null || _a === void 0 ? void 0 : _a.eventOptions));
+            this.computeAliases();
+            const { handlers: foundHandlers, firstStatic } = this.wooks.lookup('CLI', path);
+            if (typeof firstStatic === 'string') {
+                // overwriting command with firstStatic to properly search for help
+                store('event').set('command', firstStatic.replace(/\//g, ' ').trim());
+            }
+            const handlers = foundHandlers ||
+                (((_b = this.opts) === null || _b === void 0 ? void 0 : _b.onNotFound) && [this.opts.onNotFound]) ||
+                null;
             if (handlers) {
                 try {
                     for (const handler of handlers) {
@@ -108,16 +230,21 @@ class WooksCli extends wooks.WooksAdapterBase {
             process.exit(1);
         }
     }
+    /**
+     * Triggers `unknown command` processing and callbacks
+     * @param pathParams `string[]` containing command
+     */
     onUnknownCommand(pathParams) {
         var _a;
+        const raiseError = () => {
+            this.error('' + 'Unknown command: ' + pathParams.join(' '));
+            process.exit(1);
+        };
         if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.onUnknownCommand) {
-            this.opts.onUnknownCommand(pathParams);
+            this.opts.onUnknownCommand(pathParams, raiseError);
         }
         else {
-            this.error('' +
-                'Unknown command: ' +
-                pathParams.join(' '));
-            process.exit(1);
+            raiseError();
         }
     }
     error(e) {
@@ -129,11 +256,158 @@ class WooksCli extends wooks.WooksAdapterBase {
         }
     }
 }
+/**
+ * Factory for WooksCli App
+ * @param opts TWooksCliOptions
+ * @param wooks Wooks | WooksAdapterBase
+ * @returns WooksHttp
+ */
 function createCliApp(opts, wooks) {
     return new WooksCli(opts, wooks);
 }
 
-function useFlags() {
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * // print with colors
+ * print(true)
+ * // print with no colors
+ * // print(false)
+ * ```
+ * @returns
+ */
+function useCliHelp() {
+    const event = useCliContext().store('event');
+    const getCliHelp = () => event.get('cliHelp');
+    const getEntry = () => { var _a; return (_a = getCliHelp().match(event.get('command'))) === null || _a === void 0 ? void 0 : _a.main; };
+    return {
+        getCliHelp,
+        getEntry,
+        render: (width, withColors) => getCliHelp().render(event.get('command'), width, withColors),
+        print: (withColors) => getCliHelp().print(event.get('command'), withColors),
+    };
+}
+/**
+ * ## useAutoHelp
+ * ### Composable
+ *
+ * Prints help if `--help` option provided.
+ *
+ * ```js
+ *  // example of use: print help and exit
+ *  app.cli('test', () => {
+ *      useAutoHelp() && process.exit(0)
+ *      return 'hit test command'
+ *  })
+ *
+ *  // add option -h to print help, no colors
+ *  app.cli('test/nocolors', () => {
+ *      useAutoHelp(['help', 'h'], false) && process.exit(0)
+ *      return 'hit test nocolors command'
+ *  })
+ * ```
+ * @param keys default `['help']` - list of options to trigger help render
+ * @param colors default `true`, prints with colors when true
+ * @returns true when --help was provided. Otherwise returns false
+ */
+function useAutoHelp(keys = ['help'], colors = true) {
+    for (const option of keys) {
+        if (useCliOption(option) === true) {
+            // try {
+            useCliHelp().print(colors);
+            return true;
+            // } catch (e) {
+            //     throw new 
+            // }
+        }
+    }
+}
+/**
+ * ##useCommandLookupHelp
+ * ### Composable
+ *
+ * Tries to find valid command based on provided command.
+ *
+ * If manages to find a valid command, throws an error
+ * suggesting a list of valid commands
+ *
+ * Best to use in `onUnknownCommand` callback:
+ *
+ * ```js
+ *  const app = createCliApp({
+ *      onUnknownCommand: (path, raiseError) => {
+ *          // will throw an error suggesting a list
+ *          // of valid commands if could find some
+ *          useCommandLookupHelp()
+ *          // fallback to a regular error handler
+ *          raiseError()
+ *      },
+ *  })
+ * ```
+ *
+ * @param lookupDepth depth of search in backwards
+ * @example
+ *
+ * For provided command `run test:drive dir`
+ *  - lookup1: `run test:drive dir`  (deep = 0)
+ *  - lookup2: `run test:drive`      (deep = 1)
+ *  - lookup3: `run test`            (deep = 2)
+ *  - lookup4: `run`                 (deep = 3)
+ * ...
+ */
+function useCommandLookupHelp(lookupDepth = 3) {
+    const parts = useCliContext()
+        .store('event')
+        .get('pathParams')
+        .map((p) => (p + ' ').split(':').map((s, i) => (i ? ':' + s : s)))
+        .flat();
+    const cliHelp = useCliHelp().getCliHelp();
+    const cmd = cliHelp.getCliName();
+    let data;
+    for (let i = 0; i < Math.min(parts.length, lookupDepth + 1); i++) {
+        const pathParams = parts
+            .slice(0, i ? -i : parts.length)
+            .join('')
+            .trim();
+        try {
+            data = cliHelp.match(pathParams);
+            break;
+        }
+        catch (e) {
+            const variants = cliHelp.lookup(pathParams);
+            if (variants.length) {
+                throw new Error(`Wrong command, did you mean:\n${variants
+                    .slice(0, 7)
+                    .map((c) => `  $ ${cmd} ${c.main.command}`)
+                    .join('\n')}`);
+            }
+        }
+    }
+    if (data) {
+        const { main, children } = data;
+        if (main.args && Object.keys(main.args).length) {
+            throw new Error(`Arguments expected: ${Object.keys(main.args)
+                .map((l) => `<${l}>`)
+                .join(', ')}`);
+        }
+        else if (children && children.length) {
+            throw new Error(`Wrong command, did you mean:\n${children
+                .slice(0, 7)
+                .map((c) => `  $ ${cmd} ${c.command}`)
+                .join('\n')}`);
+        }
+    }
+}
+
+/**
+ * Get CLI Options
+ *
+ * @returns an object with CLI options
+ */
+function useCliOptions() {
     const { store } = useCliContext();
     const flags = store('flags');
     if (!flags.value) {
@@ -141,21 +415,38 @@ function useFlags() {
     }
     return flags.value;
 }
-function useFlag(name) {
-    return useFlags()[name];
-}
-
-function usePathParams() {
-    const { store } = useCliContext();
-    const event = store('event');
-    return event.get('pathParams');
+/**
+ * Getter for Cli Option value
+ *
+ * @param name name of the option
+ * @returns value of a CLI option
+ */
+function useCliOption(name) {
+    var _a;
+    try {
+        const options = ((_a = useCliHelp().getEntry()) === null || _a === void 0 ? void 0 : _a.options) || [];
+        const opt = options.find(o => o.keys.includes(name));
+        if (opt) {
+            for (const key of opt.keys) {
+                if (useCliOptions()[key]) {
+                    return useCliOptions()[key];
+                }
+            }
+        }
+    }
+    catch (e) {
+        //
+    }
+    return useCliOptions()[name];
 }
 
 exports.WooksCli = WooksCli;
 exports.cliShortcuts = cliShortcuts;
 exports.createCliApp = createCliApp;
 exports.createCliContext = createCliContext;
+exports.useAutoHelp = useAutoHelp;
 exports.useCliContext = useCliContext;
-exports.useFlag = useFlag;
-exports.useFlags = useFlags;
-exports.usePathParams = usePathParams;
+exports.useCliHelp = useCliHelp;
+exports.useCliOption = useCliOption;
+exports.useCliOptions = useCliOptions;
+exports.useCommandLookupHelp = useCommandLookupHelp;

package/dist/index.d.ts

@@ -1,9 +1,13 @@
+import { CliHelpRenderer } from '@prostojs/cli-help';
+import { TCliEntry } from '@prostojs/cli-help';
+import { TCliHelpOptions } from '@prostojs/cli-help';
 import { TConsoleBase } from '@prostojs/logger';
 import { TEmpty } from '@wooksjs/event-core';
 import { TEventOptions } from '@wooksjs/event-core';
 import { TGenericContextStore } from '@wooksjs/event-core';
 import { TProstoRouterPathHandle } from '@prostojs/router';
-import { TWooksHandler } from 'wooks';
+import { TWooksHandler } from '@wooksjs/wooks';
+import { TWooksHandler as TWooksHandler_2 } from 'wooks';
 import { Wooks } from 'wooks';
 import { WooksAdapterBase } from 'wooks';
 
@@ -11,6 +15,12 @@ export declare const cliShortcuts: {
     cli: string;
 };
 
+/**
+ * Factory for WooksCli App
+ * @param opts TWooksCliOptions
+ * @param wooks Wooks | WooksAdapterBase
+ * @returns WooksHttp
+ */
 export declare function createCliApp(opts?: TWooksCliOptions, wooks?: Wooks | WooksAdapterBase): WooksCli;
 
 export declare function createCliContext(data: Omit<TCliEventData, 'type'>, options: TEventOptions): {
@@ -44,17 +54,68 @@ export declare interface TCliContextStore {
 export declare interface TCliEventData {
     argv: string[];
     pathParams: string[];
+    command: string;
     type: 'CLI';
+    cliHelp: TCliHelpRenderer;
+}
+
+export declare type TCliHelpCustom = {
+    handler: TWooksHandler<any>;
+    /**
+     * ### Callback for registered path
+     *
+     * @param path registered path
+     * @param aliasType 0 - direct command, 1 - direct alias, 2 - computed alias
+     */
+    cb?: (path: string, aliasType: number) => void;
+};
+
+export declare type TCliHelpRenderer = CliHelpRenderer<TCliHelpCustom>;
+
+export declare interface TWooksCliEntry<T> extends Omit<TCliEntry<TWooksHandler_2<T>>, 'custom' | 'command'> {
+    onRegister?: TCliHelpCustom['cb'];
+    handler: TWooksHandler_2<T>;
 }
 
 export declare interface TWooksCliOptions {
     onError?(e: Error): void;
-    onNotFound?: TWooksHandler<unknown>;
-    onUnknownCommand?: ((params: string[]) => unknown);
+    onNotFound?: TWooksHandler_2<unknown>;
+    onUnknownCommand?: (params: string[], raiseError: () => void) => unknown;
     logger?: TConsoleBase;
     eventOptions?: TEventOptions;
+    cliHelp?: TCliHelpRenderer | TCliHelpOptions;
 }
 
+/**
+ * ## useAutoHelp
+ * ### Composable
+ *
+ * Prints help if `--help` option provided.
+ *
+ * ```js
+ *  // example of use: print help and exit
+ *  app.cli('test', () => {
+ *      useAutoHelp() && process.exit(0)
+ *      return 'hit test command'
+ *  })
+ *
+ *  // add option -h to print help, no colors
+ *  app.cli('test/nocolors', () => {
+ *      useAutoHelp(['help', 'h'], false) && process.exit(0)
+ *      return 'hit test nocolors command'
+ *  })
+ * ```
+ * @param keys default `['help']` - list of options to trigger help render
+ * @param colors default `true`, prints with colors when true
+ * @returns true when --help was provided. Otherwise returns false
+ */
+export declare function useAutoHelp(keys?: string[], colors?: boolean): true | undefined;
+
+/**
+ * Wrapper on top of useEventContext that provides
+ * proper context types for CLI event
+ * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
+ */
 export declare function useCliContext<T extends TEmpty>(): {
     getCtx: () => TCliContextStore & T & TGenericContextStore<TCliEventData>;
     restoreCtx: () => TGenericContextStore<TEmpty>;
@@ -77,23 +138,141 @@ export declare function useCliContext<T extends TEmpty>(): {
     setStore: <K_2 extends "flags" | keyof TGenericContextStore<TCliEventData> | keyof T>(key: K_2, v: (TCliContextStore & T & TGenericContextStore<TCliEventData>)[K_2]) => void;
 };
 
-export declare function useFlag(name: string): string | boolean;
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * // print with colors
+ * print(true)
+ * // print with no colors
+ * // print(false)
+ * ```
+ * @returns
+ */
+export declare function useCliHelp(): {
+    getCliHelp: () => TCliHelpRenderer;
+    getEntry: () => TCliEntry<TCliHelpCustom>;
+    render: (width?: number, withColors?: boolean) => string[];
+    print: (withColors?: boolean) => void;
+};
+
+/**
+ * Getter for Cli Option value
+ *
+ * @param name name of the option
+ * @returns value of a CLI option
+ */
+export declare function useCliOption(name: string): string | boolean;
 
-export declare function useFlags(): {
+/**
+ * Get CLI Options
+ *
+ * @returns an object with CLI options
+ */
+export declare function useCliOptions(): {
     [name: string]: string | boolean;
 };
 
-export declare function usePathParams(): string[];
+/**
+ * ##useCommandLookupHelp
+ * ### Composable
+ *
+ * Tries to find valid command based on provided command.
+ *
+ * If manages to find a valid command, throws an error
+ * suggesting a list of valid commands
+ *
+ * Best to use in `onUnknownCommand` callback:
+ *
+ * ```js
+ *  const app = createCliApp({
+ *      onUnknownCommand: (path, raiseError) => {
+ *          // will throw an error suggesting a list
+ *          // of valid commands if could find some
+ *          useCommandLookupHelp()
+ *          // fallback to a regular error handler
+ *          raiseError()
+ *      },
+ *  })
+ * ```
+ *
+ * @param lookupDepth depth of search in backwards
+ * @example
+ *
+ * For provided command `run test:drive dir`
+ *  - lookup1: `run test:drive dir`  (deep = 0)
+ *  - lookup2: `run test:drive`      (deep = 1)
+ *  - lookup3: `run test`            (deep = 2)
+ *  - lookup4: `run`                 (deep = 3)
+ * ...
+ */
+export declare function useCommandLookupHelp(lookupDepth?: number): void;
 
 export declare class WooksCli extends WooksAdapterBase {
     protected opts?: TWooksCliOptions | undefined;
     protected logger: TConsoleBase;
+    protected cliHelp: TCliHelpRenderer;
     constructor(opts?: TWooksCliOptions | undefined, wooks?: Wooks | WooksAdapterBase);
-    cli<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): TProstoRouterPathHandle<ParamsType>;
+    /**
+     * ### Register CLI Command
+     * 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
+     *
+     * ```js
+     * // example without options
+     * app.cli('command/:arg', () => 'arg = ' + useRouteParams().params.arg )
+     *
+     * // example with options
+     * app.cli('command/:arg', {
+     *   description: 'Description of the command',
+     *   options: [{ keys: ['project', 'p'], description: 'Description of the option', value: 'myProject' }],
+     *   args: { arg: 'Description of the arg' },
+     *   aliases: ['cmd'],  // alias "cmd/:arg" will be registered
+     *   examples: [{
+     *      description: 'Example of usage with someProject',
+     *      cmd: 'argValue -p=someProject',
+     *      // will result in help display:
+     *      // "# Example of usage with someProject\n" +
+     *      // "$ myCli command argValue -p=someProject\n"
+     *   }],
+     *   handler: () => 'arg = ' + useRouteParams().params.arg
+     * })
+     * ```
+     *
+     * @param path command path
+     * @param _options handler or options
+     *
+     * @returns
+     */
+    cli<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, _options: TWooksCliEntry<ResType> | TWooksHandler_2<ResType>): TProstoRouterPathHandle<ParamsType>;
+    protected alreadyComputedAliases: boolean;
+    protected computeAliases(): void;
+    /**
+     * ## run
+     * ### Start command processing
+     * Triggers command processing
+     *
+     * By default takes `process.argv.slice(2)` as a command
+     *
+     * It's possible to replace the command by passing an argument
+     *
+     * @param _argv optionally overwrite `process.argv.slice(2)` with your `argv` array
+     */
     run(_argv?: string[]): Promise<void>;
-    onError(e: Error): void;
+    protected onError(e: Error): void;
+    /**
+     * Triggers `unknown command` processing and callbacks
+     * @param pathParams `string[]` containing command
+     */
     onUnknownCommand(pathParams: string[]): void;
-    error(e: string | Error): void;
+    protected error(e: string | Error): void;
 }
 
 export { }

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { createEventContext, useEventContext } from '@wooksjs/event-core';
 import { WooksAdapterBase } from 'wooks';
+import { CliHelpRenderer } from '@prostojs/cli-help';
 import minimist from 'minimist';
 
 function createCliContext(data, options) {
@@ -8,6 +9,11 @@ function createCliContext(data, options) {
         options,
     });
 }
+/**
+ * Wrapper on top of useEventContext that provides
+ * proper context types for CLI event
+ * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
+ */
 function useCliContext() {
     return useEventContext('CLI');
 }
@@ -46,22 +52,138 @@ class WooksCli extends WooksAdapterBase {
     constructor(opts, wooks) {
         super(wooks, opts === null || opts === void 0 ? void 0 : opts.logger);
         this.opts = opts;
+        this.alreadyComputedAliases = false;
         this.logger = (opts === null || opts === void 0 ? void 0 : opts.logger) || this.getLogger('wooks-cli');
+        this.cliHelp =
+            (opts === null || opts === void 0 ? void 0 : opts.cliHelp) instanceof CliHelpRenderer
+                ? opts.cliHelp
+                : new CliHelpRenderer(opts === null || opts === void 0 ? void 0 : opts.cliHelp);
     }
-    cli(path, handler) {
-        return this.on('CLI', path, handler);
+    /**
+     * ### Register CLI Command
+     * 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
+     *
+     * ```js
+     * // example without options
+     * app.cli('command/:arg', () => 'arg = ' + useRouteParams().params.arg )
+     *
+     * // example with options
+     * app.cli('command/:arg', {
+     *   description: 'Description of the command',
+     *   options: [{ keys: ['project', 'p'], description: 'Description of the option', value: 'myProject' }],
+     *   args: { arg: 'Description of the arg' },
+     *   aliases: ['cmd'],  // alias "cmd/:arg" will be registered
+     *   examples: [{
+     *      description: 'Example of usage with someProject',
+     *      cmd: 'argValue -p=someProject',
+     *      // will result in help display:
+     *      // "# Example of usage with someProject\n" +
+     *      // "$ myCli command argValue -p=someProject\n"
+     *   }],
+     *   handler: () => 'arg = ' + useRouteParams().params.arg
+     * })
+     * ```
+     *
+     * @param path command path
+     * @param _options handler or options
+     *
+     * @returns
+     */
+    cli(path, _options) {
+        const options = typeof _options === 'function' ? { handler: _options } : _options;
+        const handler = typeof _options === 'function' ? _options : _options.handler;
+        const makePath = (s) => '/' + s.replace(/\s+/g, '/');
+        // register handler
+        const targetPath = makePath(path);
+        const routed = this.on('CLI', targetPath, handler);
+        if (options.onRegister) {
+            options.onRegister(targetPath, 0);
+        }
+        // register direct aliases
+        for (const alias of options.aliases || []) {
+            const vars = routed.getArgs().map((k) => ':' + k).join('/');
+            const targetPath = makePath(alias) + (vars ? '/' + vars : '');
+            this.on('CLI', targetPath, handler);
+            if (options.onRegister) {
+                options.onRegister(targetPath, 1);
+            }
+        }
+        // register helpCli entry
+        const command = routed.getStaticPart().replace(/\//g, ' ').trim();
+        const args = Object.assign({}, (options.args || {}));
+        for (const arg of routed.getArgs()) {
+            if (!args[arg]) {
+                args[arg] = '';
+            }
+        }
+        this.cliHelp.addEntry({
+            command,
+            aliases: options.aliases,
+            args,
+            description: options.description,
+            examples: options.examples,
+            options: options.options,
+            custom: { handler: options.handler, cb: options.onRegister },
+        });
+        return routed;
+    }
+    computeAliases() {
+        if (!this.alreadyComputedAliases) {
+            this.alreadyComputedAliases = true;
+            const aliases = this.cliHelp.getComputedAliases();
+            for (const [alias, entry] of Object.entries(aliases)) {
+                if (entry.custom) {
+                    const vars = Object.keys(entry.args || {})
+                        .map((k) => ':' + k)
+                        .join('/');
+                    const path = '/' +
+                        alias.replace(/\s+/g, '/').replace(/:/g, '\\:') +
+                        (vars ? '/' + vars : '');
+                    this.on('CLI', path, entry.custom.handler);
+                    if (entry.custom.cb) {
+                        entry.custom.cb(path, 3);
+                    }
+                }
+            }
+        }
     }
+    /**
+     * ## run
+     * ### Start command processing
+     * Triggers command processing
+     *
+     * By default takes `process.argv.slice(2)` as a command
+     *
+     * It's possible to replace the command by passing an argument
+     *
+     * @param _argv optionally overwrite `process.argv.slice(2)` with your `argv` array
+     */
     run(_argv) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
-            const argv = process.argv.slice(2) || _argv;
+            const argv = _argv || process.argv.slice(2);
             const firstFlagIndex = argv.findIndex((a) => a.startsWith('-')) + 1;
-            const pathParams = (firstFlagIndex
+            const pathParams = firstFlagIndex
                 ? argv.slice(0, firstFlagIndex - 1)
-                : argv);
-            const path = '/' + pathParams.map((v) => encodeURI(v).replace(/\//g, '%2F')).join('/');
-            const { restoreCtx, clearCtx } = createCliContext({ argv, pathParams }, this.mergeEventOptions((_a = this.opts) === null || _a === void 0 ? void 0 : _a.eventOptions));
-            const handlers = this.wooks.lookup('CLI', path) || ((_b = this.opts) === null || _b === void 0 ? void 0 : _b.onNotFound) && [this.opts.onNotFound] || null;
+                : argv;
+            const path = '/' +
+                pathParams.map((v) => encodeURI(v).replace(/\//g, '%2F')).join('/');
+            const { restoreCtx, clearCtx, store } = createCliContext({ argv, pathParams, cliHelp: this.cliHelp, command: path.replace(/\//g, ' ').trim() }, this.mergeEventOptions((_a = this.opts) === null || _a === void 0 ? void 0 : _a.eventOptions));
+            this.computeAliases();
+            const { handlers: foundHandlers, firstStatic } = this.wooks.lookup('CLI', path);
+            if (typeof firstStatic === 'string') {
+                // overwriting command with firstStatic to properly search for help
+                store('event').set('command', firstStatic.replace(/\//g, ' ').trim());
+            }
+            const handlers = foundHandlers ||
+                (((_b = this.opts) === null || _b === void 0 ? void 0 : _b.onNotFound) && [this.opts.onNotFound]) ||
+                null;
             if (handlers) {
                 try {
                     for (const handler of handlers) {
@@ -106,16 +228,21 @@ class WooksCli extends WooksAdapterBase {
             process.exit(1);
         }
     }
+    /**
+     * Triggers `unknown command` processing and callbacks
+     * @param pathParams `string[]` containing command
+     */
     onUnknownCommand(pathParams) {
         var _a;
+        const raiseError = () => {
+            this.error('' + 'Unknown command: ' + pathParams.join(' '));
+            process.exit(1);
+        };
         if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.onUnknownCommand) {
-            this.opts.onUnknownCommand(pathParams);
+            this.opts.onUnknownCommand(pathParams, raiseError);
         }
         else {
-            this.error('' +
-                'Unknown command: ' +
-                pathParams.join(' '));
-            process.exit(1);
+            raiseError();
         }
     }
     error(e) {
@@ -127,11 +254,158 @@ class WooksCli extends WooksAdapterBase {
         }
     }
 }
+/**
+ * Factory for WooksCli App
+ * @param opts TWooksCliOptions
+ * @param wooks Wooks | WooksAdapterBase
+ * @returns WooksHttp
+ */
 function createCliApp(opts, wooks) {
     return new WooksCli(opts, wooks);
 }
 
-function useFlags() {
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * // print with colors
+ * print(true)
+ * // print with no colors
+ * // print(false)
+ * ```
+ * @returns
+ */
+function useCliHelp() {
+    const event = useCliContext().store('event');
+    const getCliHelp = () => event.get('cliHelp');
+    const getEntry = () => { var _a; return (_a = getCliHelp().match(event.get('command'))) === null || _a === void 0 ? void 0 : _a.main; };
+    return {
+        getCliHelp,
+        getEntry,
+        render: (width, withColors) => getCliHelp().render(event.get('command'), width, withColors),
+        print: (withColors) => getCliHelp().print(event.get('command'), withColors),
+    };
+}
+/**
+ * ## useAutoHelp
+ * ### Composable
+ *
+ * Prints help if `--help` option provided.
+ *
+ * ```js
+ *  // example of use: print help and exit
+ *  app.cli('test', () => {
+ *      useAutoHelp() && process.exit(0)
+ *      return 'hit test command'
+ *  })
+ *
+ *  // add option -h to print help, no colors
+ *  app.cli('test/nocolors', () => {
+ *      useAutoHelp(['help', 'h'], false) && process.exit(0)
+ *      return 'hit test nocolors command'
+ *  })
+ * ```
+ * @param keys default `['help']` - list of options to trigger help render
+ * @param colors default `true`, prints with colors when true
+ * @returns true when --help was provided. Otherwise returns false
+ */
+function useAutoHelp(keys = ['help'], colors = true) {
+    for (const option of keys) {
+        if (useCliOption(option) === true) {
+            // try {
+            useCliHelp().print(colors);
+            return true;
+            // } catch (e) {
+            //     throw new 
+            // }
+        }
+    }
+}
+/**
+ * ##useCommandLookupHelp
+ * ### Composable
+ *
+ * Tries to find valid command based on provided command.
+ *
+ * If manages to find a valid command, throws an error
+ * suggesting a list of valid commands
+ *
+ * Best to use in `onUnknownCommand` callback:
+ *
+ * ```js
+ *  const app = createCliApp({
+ *      onUnknownCommand: (path, raiseError) => {
+ *          // will throw an error suggesting a list
+ *          // of valid commands if could find some
+ *          useCommandLookupHelp()
+ *          // fallback to a regular error handler
+ *          raiseError()
+ *      },
+ *  })
+ * ```
+ *
+ * @param lookupDepth depth of search in backwards
+ * @example
+ *
+ * For provided command `run test:drive dir`
+ *  - lookup1: `run test:drive dir`  (deep = 0)
+ *  - lookup2: `run test:drive`      (deep = 1)
+ *  - lookup3: `run test`            (deep = 2)
+ *  - lookup4: `run`                 (deep = 3)
+ * ...
+ */
+function useCommandLookupHelp(lookupDepth = 3) {
+    const parts = useCliContext()
+        .store('event')
+        .get('pathParams')
+        .map((p) => (p + ' ').split(':').map((s, i) => (i ? ':' + s : s)))
+        .flat();
+    const cliHelp = useCliHelp().getCliHelp();
+    const cmd = cliHelp.getCliName();
+    let data;
+    for (let i = 0; i < Math.min(parts.length, lookupDepth + 1); i++) {
+        const pathParams = parts
+            .slice(0, i ? -i : parts.length)
+            .join('')
+            .trim();
+        try {
+            data = cliHelp.match(pathParams);
+            break;
+        }
+        catch (e) {
+            const variants = cliHelp.lookup(pathParams);
+            if (variants.length) {
+                throw new Error(`Wrong command, did you mean:\n${variants
+                    .slice(0, 7)
+                    .map((c) => `  $ ${cmd} ${c.main.command}`)
+                    .join('\n')}`);
+            }
+        }
+    }
+    if (data) {
+        const { main, children } = data;
+        if (main.args && Object.keys(main.args).length) {
+            throw new Error(`Arguments expected: ${Object.keys(main.args)
+                .map((l) => `<${l}>`)
+                .join(', ')}`);
+        }
+        else if (children && children.length) {
+            throw new Error(`Wrong command, did you mean:\n${children
+                .slice(0, 7)
+                .map((c) => `  $ ${cmd} ${c.command}`)
+                .join('\n')}`);
+        }
+    }
+}
+
+/**
+ * Get CLI Options
+ *
+ * @returns an object with CLI options
+ */
+function useCliOptions() {
     const { store } = useCliContext();
     const flags = store('flags');
     if (!flags.value) {
@@ -139,14 +413,29 @@ function useFlags() {
     }
     return flags.value;
 }
-function useFlag(name) {
-    return useFlags()[name];
-}
-
-function usePathParams() {
-    const { store } = useCliContext();
-    const event = store('event');
-    return event.get('pathParams');
+/**
+ * Getter for Cli Option value
+ *
+ * @param name name of the option
+ * @returns value of a CLI option
+ */
+function useCliOption(name) {
+    var _a;
+    try {
+        const options = ((_a = useCliHelp().getEntry()) === null || _a === void 0 ? void 0 : _a.options) || [];
+        const opt = options.find(o => o.keys.includes(name));
+        if (opt) {
+            for (const key of opt.keys) {
+                if (useCliOptions()[key]) {
+                    return useCliOptions()[key];
+                }
+            }
+        }
+    }
+    catch (e) {
+        //
+    }
+    return useCliOptions()[name];
 }
 
-export { WooksCli, cliShortcuts, createCliApp, createCliContext, useCliContext, useFlag, useFlags, usePathParams };
+export { WooksCli, cliShortcuts, createCliApp, createCliContext, useAutoHelp, useCliContext, useCliHelp, useCliOption, useCliOptions, useCommandLookupHelp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-cli",
-  "version": "0.2.23",
+  "version": "0.3.1",
   "description": "@wooksjs/event-cli",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -31,11 +31,12 @@
     "url": "https://github.com/wooksjs/wooksjs/issues"
   },
   "peerDependencies": {
-    "wooks": "0.2.23",
-    "@wooksjs/event-core": "0.2.23"
+    "wooks": "0.3.1",
+    "@wooksjs/event-core": "0.3.1"
   },
   "dependencies": {
     "minimist": "^1.2.6",
+    "@prostojs/cli-help": "^0.0.10",
     "@prostojs/logger": "^0.3.6"
   },
   "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-cli#readme"