@moostjs/event-cli 0.2.27 → 0.2.29

package/README.md

@@ -35,8 +35,6 @@ app.init()
 // "command run with flag test=true"
 ```
 
-
-
 ## Install
 
 `npm install moost @moostjs/event-cli`

package/dist/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-var eventCli = require('@wooksjs/event-cli');
-var eventCore = require('@wooksjs/event-core');
 var moost = require('moost');
+var eventCli = require('@wooksjs/event-cli');
+var cliHelp = require('@prostojs/cli-help');
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -18,6 +18,8 @@ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 PERFORMANCE OF THIS SOFTWARE.
 ***************************************************************************** */
+/* global Reflect, Promise */
+
 
 function __awaiter(thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -29,106 +31,241 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+function getCliMate() {
+    return moost.getMoostMate();
+}
+
+/**
+ * ### setCliHelpForEvent
+ * Used internally to set CliHelpRenderer instance for an event state
+ * @param cliHelp CliHelpRenderer
+ */
+function setCliHelpForEvent(cliHelp) {
+    eventCli.useCliContext().store('event').set('cliHelp', cliHelp);
+}
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * print(true)
+ * ```
+ * @returns
+ */
+function useCliHelp() {
+    const event = eventCli.useCliContext().store('event');
+    const getCliHelp = () => event.get('cliHelp');
+    return {
+        getCliHelp,
+        render: (width, withColors) => getCliHelp().render(event.get('pathParams').join(' '), width, withColors),
+        print: (withColors) => getCliHelp().print(event.get('pathParams').join(' '), withColors),
+    };
+}
+
+const LOGGER_TITLE = 'moost-cli';
+const CONTEXT_TYPE = 'CLI';
+/**
+ * ## 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()
+ * ```
+ */
 class MoostCli {
-    constructor(cliApp) {
-        if (cliApp && cliApp instanceof eventCli.WooksCli) {
-            this.cliApp = cliApp;
+    constructor(opts) {
+        this.opts = opts;
+        const cliAppOpts = opts === null || opts === void 0 ? void 0 : opts.wooksCli;
+        if (cliAppOpts && cliAppOpts instanceof eventCli.WooksCli) {
+            this.cliApp = cliAppOpts;
+        }
+        else if (cliAppOpts) {
+            this.cliApp = eventCli.createCliApp(Object.assign(Object.assign({}, cliAppOpts), { onNotFound: this.onNotFound.bind(this) }));
+        }
+        else {
+            this.cliApp = eventCli.createCliApp({
+                onNotFound: this.onNotFound.bind(this),
+            });
         }
-        else if (cliApp) {
-            this.cliApp = eventCli.createCliApp(cliApp);
+        const cliHelpOpts = opts === null || opts === void 0 ? void 0 : opts.cliHelp;
+        if (cliHelpOpts && cliHelpOpts instanceof cliHelp.CliHelpRenderer) {
+            this.cliHelp = cliHelpOpts;
+        }
+        else if (cliHelpOpts) {
+            this.cliHelp = new cliHelp.CliHelpRenderer(cliHelpOpts);
         }
         else {
-            this.cliApp = eventCli.createCliApp();
+            this.cliHelp = new cliHelp.CliHelpRenderer();
+        }
+        if (!(opts === null || opts === void 0 ? void 0 : opts.debug)) {
+            moost.getMoostInfact().silent(true);
         }
     }
-    onInit() {
+    onNotFound() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const pathParams = eventCli.useCliContext().store('event').get('pathParams');
+            const response = yield moost.defineMoostEventHandler({
+                loggerTitle: LOGGER_TITLE,
+                getIterceptorHandler: () => { var _a; return (_a = this.moost) === null || _a === void 0 ? void 0 : _a.getGlobalInterceptorHandler(); },
+                getControllerInstance: () => this.moost,
+                callControllerMethod: () => undefined,
+                logErrors: (_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug,
+                hooks: {
+                    init: () => setCliHelpForEvent(this.cliHelp),
+                },
+            })();
+            if (typeof response === 'undefined') {
+                this.cliApp.onUnknownCommand(pathParams);
+            }
+            return response;
+        });
+    }
+    onInit(moost) {
+        var _a;
+        this.moost = moost;
+        for (const [alias, entry] of Object.entries(this.cliHelp.getComputedAliases())) {
+            if (entry.custom) {
+                const vars = Object.keys(entry.args || {}).map(k => ':' + k).join('/');
+                const path = '/' + alias.replace(/\s+/g, '/').replace(/:/g, '\\:') + (vars ? '/' + vars : '');
+                this.cliApp.cli(path, entry.custom.fn);
+                if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug) {
+                    entry.custom.log(`${''}(CLI-alias*)${''}${path}`);
+                }
+            }
+        }
         void this.cliApp.run();
     }
     bindHandler(opts) {
+        var _a, _b, _c, _d, _e, _f;
         let fn;
         for (const handler of opts.handlers) {
             if (handler.type !== 'CLI')
                 continue;
-            const path = typeof handler.path === 'string' ? handler.path : typeof opts.method === 'string' ? opts.method : '';
-            const targetPath = `${opts.prefix || ''}/${path}`.replace(/\/\/+/g, '/');
+            const path = typeof handler.path === 'string'
+                ? handler.path
+                : typeof opts.method === 'string'
+                    ? opts.method
+                    : '';
+            const makePath = (p) => `${opts.prefix.replace(/\s+/g, '/') || ''}/${p}`
+                .replace(/\/\/+/g, '/')
+                // avoid interpreting "cmd:tail" as "cmd/:tail"
+                .replace(/\/\\:/g, '\\:');
+            let cliCommand = '';
             if (!fn) {
-                fn = () => __awaiter(this, void 0, void 0, function* () {
-                    const { restoreCtx } = eventCli.useCliContext();
-                    const scopeId = eventCore.useEventId().getId();
-                    const unscope = opts.registerEventScope(scopeId);
-                    const instance = yield opts.getInstance();
-                    restoreCtx();
-                    let response;
-                    const interceptorHandler = yield opts.getIterceptorHandler();
-                    restoreCtx();
-                    yield interceptorHandler.init();
-                    // params
-                    let args = [];
-                    try {
-                        restoreCtx();
-                        args = yield opts.resolveArgs();
-                    }
-                    catch (e) {
-                        response = e;
-                    }
-                    if (!response) {
-                        restoreCtx();
-                        // fire before interceptors
-                        response = yield interceptorHandler.fireBefore(response);
-                        // fire request handler
-                        if (!interceptorHandler.responseOverwritten) {
-                            try {
-                                restoreCtx();
-                                response = yield instance[opts.method](...args);
-                            }
-                            catch (e) {
-                                response = e;
-                            }
-                        }
-                    }
-                    restoreCtx();
-                    // fire after interceptors
-                    response = yield interceptorHandler.fireAfter(response);
-                    unscope();
-                    return response;
+                fn = moost.defineMoostEventHandler({
+                    contextType: CONTEXT_TYPE,
+                    loggerTitle: LOGGER_TITLE,
+                    getIterceptorHandler: opts.getIterceptorHandler,
+                    getControllerInstance: opts.getInstance,
+                    controllerMethod: opts.method,
+                    resolveArgs: opts.resolveArgs,
+                    logErrors: (_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug,
+                    hooks: {
+                        init: () => setCliHelpForEvent(this.cliHelp),
+                    },
                 });
             }
-            this.cliApp.cli(targetPath, fn);
-            opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            const targetPath = makePath(path);
+            const { getArgs, getStaticPart } = this.cliApp.cli(targetPath, fn);
+            const meta = getCliMate().read(opts.fakeInstance, opts.method);
+            const classMeta = getCliMate().read(opts.fakeInstance);
+            const args = {};
+            getArgs().forEach(a => {
+                var _a;
+                const argParam = (_a = meta === null || meta === void 0 ? void 0 : meta.params) === null || _a === void 0 ? void 0 : _a.find(p => p.label === a && p.description);
+                args[a] = (argParam === null || argParam === void 0 ? void 0 : argParam.description) || '';
+            });
+            cliCommand = getStaticPart().replace(/\//g, ' ').trim();
+            const cliOptions = new Map();
+            [
+                ...(((_c = (_b = this.opts) === null || _b === void 0 ? void 0 : _b.globalCliOptions) === null || _c === void 0 ? void 0 : _c.length) ? this.opts.globalCliOptions : []),
+                ...((classMeta === null || classMeta === void 0 ? void 0 : classMeta.cliOptions) || []),
+                ...(((_d = meta === null || meta === void 0 ? void 0 : meta.params) === null || _d === void 0 ? void 0 : _d.filter(param => !!param.cliParamKeys && param.cliParamKeys.length > 0).map(param => ({
+                    keys: param.cliParamKeys,
+                    value: typeof param.value === 'string' ? param.value : '',
+                    description: param.description || '',
+                }))) || []),
+            ].forEach(o => cliOptions.set(o.keys[0], o));
+            if ((_e = this.opts) === null || _e === void 0 ? void 0 : _e.debug) {
+                opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            }
+            const aliases = [];
+            if (meta === null || meta === void 0 ? void 0 : meta.cliAliases) {
+                for (const alias of meta.cliAliases) {
+                    const targetPath = makePath(alias);
+                    const { getStaticPart } = this.cliApp.cli(targetPath, fn);
+                    aliases.push(getStaticPart().replace(/\//g, ' ').trim());
+                    if ((_f = this.opts) === null || _f === void 0 ? void 0 : _f.debug) {
+                        opts.logHandler(`${''}(CLI-alias)${''}${targetPath}`);
+                    }
+                }
+            }
+            this.cliHelp.addEntry({
+                description: (meta === null || meta === void 0 ? void 0 : meta.description) || '',
+                command: cliCommand,
+                options: Array.from(cliOptions.values()),
+                args,
+                aliases: aliases,
+                custom: { fn, log: opts.logHandler },
+                examples: (meta === null || meta === void 0 ? void 0 : meta.cliExamples) || [],
+            });
         }
     }
 }
 
-function getCliMate() {
-    return moost.getMoostMate();
+function formatParams(keys) {
+    const names = [keys].flat();
+    return names.map((n) => (n.length === 1 ? '-' + n : '--' + n));
 }
 
 /**
- * Get Cli Flag
- * @decorator
- * @param name - flag name
- * @paramType string
- */
-function Flag(name) {
-    return moost.Resolve(() => eventCli.useFlags()[name], name);
-}
-/**
- * Get Cli Flags
- * @decorator
- * @paramType object
+ * ## Define CLI Option
+ * ### @ParameterDecorator
+ * Use together with @Description('...') to document cli option
+ *
+ * ```ts
+ * │   @Cli('command')
+ * │   command(
+ * │      @Description('Test flag...')
+ * │      @CliOption('test', 't')
+ * │      test: boolean,
+ * │   ) {
+ * │       return `test=${ test }`
+ * │   }
+ * ```
+ *
+ * @param keys list of keys (short and long alternatives)
+ * @returns
  */
-function Flags() {
-    return moost.Resolve(() => eventCli.useFlags(), 'flags');
-}
-function formatParams(keys) {
-    const names = [keys].flat();
-    return names.map(n => n.length === 1 ? '-' + n : '--' + n);
-}
-function CliParam(keys, descr) {
+function CliOption(...keys) {
     const mate = getCliMate();
-    return mate.apply(mate.decorate('cliParams', { keys, descr }, true), moost.Resolve(() => {
+    return mate.apply(mate.decorate('cliParamKeys', keys, false), moost.Resolve(() => {
         const flags = eventCli.useFlags();
-        const names = [keys].flat();
+        const names = keys;
         const vals = [];
         for (const name of names) {
             if (flags[name]) {
@@ -143,14 +280,152 @@ function CliParam(keys, descr) {
         }
         return vals[0];
     }, formatParams(keys).join(', ')));
+}
+/**
+ * ## Define Global CLI Option
+ * ### @ClassDecorator
+ * The option described here will appear in every command instructions
+ * @param option keys and description of CLI option
+ * @returns
+ */
+function CliGlobalOption(option) {
+    const mate = getCliMate();
+    return mate.decorate('cliOptions', option, true);
 }
 
+/**
+ * ## 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
+ */
 function Cli(path) {
-    return getCliMate().decorate('handlers', { path, type: 'CLI' }, true);
+    return getCliMate().decorate('handlers', { path: path === null || path === void 0 ? void 0 : path.replace(/\s+/g, '/'), type: 'CLI' }, true);
+}
+/**
+ * ## Define CLI Command Alias
+ * ### @MethodDecorator
+ *
+ * Use it to define alias for @Cli('...') command
+ *
+ * @param path - command alias path
+ * @returns
+ */
+function CliAlias(alias) {
+    return getCliMate().decorate('cliAliases', alias, true);
+}
+/**
+ * ## Define CLI Example
+ * ### @MethodDecorator
+ *
+ * Use it to define example for Cli Help display
+ *
+ * @param path - command alias path
+ * @returns
+ */
+function CliExample(cmd, description) {
+    return getCliMate().decorate('cliExamples', { cmd, description }, true);
 }
 
+/**
+ * ### 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 TInterceptorFn
+ */
+const cliHelpInterceptor = (opts) => {
+    return moost.defineInterceptorFn(() => {
+        const helpOptions = (opts === null || opts === void 0 ? void 0 : opts.helpOptions) || ['help'];
+        for (const option of helpOptions) {
+            if (eventCli.useFlag(option) === true) {
+                try {
+                    useCliHelp().print(opts === null || opts === void 0 ? void 0 : opts.colors);
+                    return '';
+                }
+                catch (e) {
+                    //
+                }
+            }
+        }
+        if ((opts === null || opts === void 0 ? void 0 : opts.helpWithArgs) || (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd)) {
+            const { getMethod } = moost.useControllerContext();
+            if (!getMethod()) {
+                const parts = eventCli.useCliContext().store('event').get('pathParams');
+                const cliHelp = useCliHelp().getCliHelp();
+                const cmd = cliHelp.getCliName();
+                let data;
+                for (let i = 0; i < Math.min(parts.length, 4); i++) {
+                    const pathParams = parts.slice(0, i ? -i : parts.length).join(' ');
+                    try {
+                        data = cliHelp.match(pathParams);
+                        break;
+                    }
+                    catch (e) {
+                        if (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) {
+                            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 ((opts === null || opts === void 0 ? void 0 : opts.helpWithArgs) && main.args && Object.keys(main.args).length) {
+                        throw new Error(`Arguments expected: ${Object.keys(main.args).map(l => `<${l}>`).join(', ')}`);
+                    }
+                    else if ((opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) && children && children.length) {
+                        throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map(c => `  $ ${cmd} ${c.command}`).join('\n')}`);
+                    }
+                }
+            }
+        }
+    }, moost.TInterceptorPriority.BEFORE_ALL);
+};
+/**
+ * ## @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
+ */
+const CliHelpInterceptor = (...opts) => moost.Intercept(cliHelpInterceptor(...opts));
+
 exports.Cli = Cli;
-exports.CliParam = CliParam;
-exports.Flag = Flag;
-exports.Flags = Flags;
+exports.CliAlias = CliAlias;
+exports.CliExample = CliExample;
+exports.CliGlobalOption = CliGlobalOption;
+exports.CliHelpInterceptor = CliHelpInterceptor;
+exports.CliOption = CliOption;
 exports.MoostCli = MoostCli;
+exports.cliHelpInterceptor = cliHelpInterceptor;
+exports.setCliHelpForEvent = setCliHelpForEvent;
+exports.useCliHelp = useCliHelp;

package/dist/index.d.ts

@@ -1,36 +1,257 @@
+import { CliHelpRenderer } from '@prostojs/cli-help';
+import { Moost } from 'moost';
+import { TCliHelpOptions } from '@prostojs/cli-help';
+import { TInterceptorFn } from 'moost';
 import { TMoostAdapter } from 'moost';
 import { TMoostAdapterOptions } from 'moost';
 import { TWooksCliOptions } from '@wooksjs/event-cli';
+import { TWooksHandler } from 'wooks';
 import { WooksCli } from '@wooksjs/event-cli';
 
+/**
+ * ## 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
+ */
 export declare function Cli(path?: string): MethodDecorator;
 
-export declare function CliParam(keys: string | [string, string], descr?: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Define CLI Command Alias
+ * ### @MethodDecorator
+ *
+ * Use it to define alias for @Cli('...') command
+ *
+ * @param path - command alias path
+ * @returns
+ */
+export 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
+ */
+export declare function CliExample(cmd: string, description?: string): MethodDecorator;
+
+/**
+ * ## Define Global CLI Option
+ * ### @ClassDecorator
+ * The option described here will appear in every command instructions
+ * @param option keys and description of CLI option
+ * @returns
+ */
+export declare function CliGlobalOption(option: {
+    keys: string[];
+    description?: string;
+    value?: string;
+}): ClassDecorator;
+
+/**
+ * ## @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
+ */
+export declare const CliHelpInterceptor: (opts?: {
+    /**
+     * CLI Options that invoke help
+     * ```js
+     * helpOptions: ['help', 'h']
+     * ```
+     */
+    helpOptions?: string[] | undefined;
+    /**
+     * Enable colored help
+     */
+    colors?: boolean | undefined;
+    /**
+     * Enable help message when arguments are missing
+     */
+    helpWithArgs?: boolean | undefined;
+    /**
+     * Enable help message when command is incomplete
+     * and it is possible to suggest related commands
+     */
+    helpWithIncompleteCmd?: boolean | undefined;
+} | undefined) => ClassDecorator & MethodDecorator;
 
 /**
- * Get Cli Flag
- * @decorator
- * @param name - flag name
- * @paramType string
+ * ### 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 TInterceptorFn
  */
-export declare function Flag(name: string): ParameterDecorator & PropertyDecorator;
+export declare const cliHelpInterceptor: (opts?: {
+    /**
+     * CLI Options that invoke help
+     * ```js
+     * helpOptions: ['help', 'h']
+     * ```
+     */
+    helpOptions?: string[];
+    /**
+     * Enable colored help
+     */
+    colors?: boolean;
+    /**
+     * Enable help message when arguments are missing
+     */
+    helpWithArgs?: boolean;
+    /**
+     * Enable help message when command is incomplete
+     * and it is possible to suggest related commands
+     */
+    helpWithIncompleteCmd?: boolean;
+}) => TInterceptorFn;
+
+declare type CliHelpRendererWithFn = CliHelpRenderer<{
+    fn: TWooksHandler;
+    log: ((eventName: string) => void);
+}>;
 
 /**
- * Get Cli Flags
- * @decorator
- * @paramType object
+ * ## Define CLI Option
+ * ### @ParameterDecorator
+ * Use together with @Description('...') to document cli option
+ *
+ * ```ts
+ * │   @Cli('command')
+ * │   command(
+ * │      @Description('Test flag...')
+ * │      @CliOption('test', 't')
+ * │      test: boolean,
+ * │   ) {
+ * │       return `test=${ test }`
+ * │   }
+ * ```
+ *
+ * @param keys list of keys (short and long alternatives)
+ * @returns
  */
-export declare function Flags(): ParameterDecorator & PropertyDecorator;
+export declare function CliOption(...keys: string[]): ParameterDecorator;
 
+/**
+ * ## 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()
+ * ```
+ */
 export declare class MoostCli implements TMoostAdapter<TCliHandlerMeta> {
+    protected opts?: TMoostCliOpts | undefined;
     protected cliApp: WooksCli;
-    constructor(cliApp?: WooksCli | TWooksCliOptions);
-    onInit(): void;
+    protected cliHelp: CliHelpRendererWithFn;
+    constructor(opts?: TMoostCliOpts | undefined);
+    onNotFound(): Promise<unknown>;
+    protected moost?: Moost;
+    onInit(moost: Moost): void;
     bindHandler<T extends object = object>(opts: TMoostAdapterOptions<TCliHandlerMeta, T>): void | Promise<void>;
 }
 
+/**
+ * ### setCliHelpForEvent
+ * Used internally to set CliHelpRenderer instance for an event state
+ * @param cliHelp CliHelpRenderer
+ */
+export declare function setCliHelpForEvent(cliHelp: CliHelpRendererWithFn): void;
+
 export declare interface TCliHandlerMeta {
     path: string;
 }
 
+export declare interface TMoostCliOpts {
+    /**
+     * WooksCli options or instance
+     */
+    wooksCli?: WooksCli | TWooksCliOptions;
+    /**
+     * CliHelpRenderer options or instance
+     */
+    cliHelp?: CliHelpRendererWithFn | TCliHelpOptions;
+    /**
+     * more internal logs are printed when true
+     */
+    debug?: boolean;
+    /**
+     * Array of cli options applicable to every cli command
+     */
+    globalCliOptions?: {
+        keys: string[];
+        description?: string;
+    }[];
+}
+
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * print(true)
+ * ```
+ * @returns
+ */
+export declare function useCliHelp(): {
+    getCliHelp: () => CliHelpRendererWithFn;
+    render: (width?: number, withColors?: boolean) => string[];
+    print: (withColors?: boolean) => void;
+};
+
 export { }

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { WooksCli, createCliApp, useCliContext, useFlags } from '@wooksjs/event-cli';
-import { useEventId } from '@wooksjs/event-core';
-import { getMoostMate, Resolve } from 'moost';
+import { getMoostMate, getMoostInfact, defineMoostEventHandler, Resolve, defineInterceptorFn, useControllerContext, TInterceptorPriority, Intercept } from 'moost';
+import { useCliContext, WooksCli, createCliApp, useFlags, useFlag } from '@wooksjs/event-cli';
+import { CliHelpRenderer } from '@prostojs/cli-help';
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -16,6 +16,8 @@ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 PERFORMANCE OF THIS SOFTWARE.
 ***************************************************************************** */
+/* global Reflect, Promise */
+
 
 function __awaiter(thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -27,106 +29,241 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+function getCliMate() {
+    return getMoostMate();
+}
+
+/**
+ * ### setCliHelpForEvent
+ * Used internally to set CliHelpRenderer instance for an event state
+ * @param cliHelp CliHelpRenderer
+ */
+function setCliHelpForEvent(cliHelp) {
+    useCliContext().store('event').set('cliHelp', cliHelp);
+}
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * print(true)
+ * ```
+ * @returns
+ */
+function useCliHelp() {
+    const event = useCliContext().store('event');
+    const getCliHelp = () => event.get('cliHelp');
+    return {
+        getCliHelp,
+        render: (width, withColors) => getCliHelp().render(event.get('pathParams').join(' '), width, withColors),
+        print: (withColors) => getCliHelp().print(event.get('pathParams').join(' '), withColors),
+    };
+}
+
+const LOGGER_TITLE = 'moost-cli';
+const CONTEXT_TYPE = 'CLI';
+/**
+ * ## 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()
+ * ```
+ */
 class MoostCli {
-    constructor(cliApp) {
-        if (cliApp && cliApp instanceof WooksCli) {
-            this.cliApp = cliApp;
+    constructor(opts) {
+        this.opts = opts;
+        const cliAppOpts = opts === null || opts === void 0 ? void 0 : opts.wooksCli;
+        if (cliAppOpts && cliAppOpts instanceof WooksCli) {
+            this.cliApp = cliAppOpts;
         }
-        else if (cliApp) {
-            this.cliApp = createCliApp(cliApp);
+        else if (cliAppOpts) {
+            this.cliApp = createCliApp(Object.assign(Object.assign({}, cliAppOpts), { onNotFound: this.onNotFound.bind(this) }));
         }
         else {
-            this.cliApp = createCliApp();
+            this.cliApp = createCliApp({
+                onNotFound: this.onNotFound.bind(this),
+            });
+        }
+        const cliHelpOpts = opts === null || opts === void 0 ? void 0 : opts.cliHelp;
+        if (cliHelpOpts && cliHelpOpts instanceof CliHelpRenderer) {
+            this.cliHelp = cliHelpOpts;
+        }
+        else if (cliHelpOpts) {
+            this.cliHelp = new CliHelpRenderer(cliHelpOpts);
+        }
+        else {
+            this.cliHelp = new CliHelpRenderer();
+        }
+        if (!(opts === null || opts === void 0 ? void 0 : opts.debug)) {
+            getMoostInfact().silent(true);
         }
     }
-    onInit() {
+    onNotFound() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const pathParams = useCliContext().store('event').get('pathParams');
+            const response = yield defineMoostEventHandler({
+                loggerTitle: LOGGER_TITLE,
+                getIterceptorHandler: () => { var _a; return (_a = this.moost) === null || _a === void 0 ? void 0 : _a.getGlobalInterceptorHandler(); },
+                getControllerInstance: () => this.moost,
+                callControllerMethod: () => undefined,
+                logErrors: (_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug,
+                hooks: {
+                    init: () => setCliHelpForEvent(this.cliHelp),
+                },
+            })();
+            if (typeof response === 'undefined') {
+                this.cliApp.onUnknownCommand(pathParams);
+            }
+            return response;
+        });
+    }
+    onInit(moost) {
+        var _a;
+        this.moost = moost;
+        for (const [alias, entry] of Object.entries(this.cliHelp.getComputedAliases())) {
+            if (entry.custom) {
+                const vars = Object.keys(entry.args || {}).map(k => ':' + k).join('/');
+                const path = '/' + alias.replace(/\s+/g, '/').replace(/:/g, '\\:') + (vars ? '/' + vars : '');
+                this.cliApp.cli(path, entry.custom.fn);
+                if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug) {
+                    entry.custom.log(`${''}(CLI-alias*)${''}${path}`);
+                }
+            }
+        }
         void this.cliApp.run();
     }
     bindHandler(opts) {
+        var _a, _b, _c, _d, _e, _f;
         let fn;
         for (const handler of opts.handlers) {
             if (handler.type !== 'CLI')
                 continue;
-            const path = typeof handler.path === 'string' ? handler.path : typeof opts.method === 'string' ? opts.method : '';
-            const targetPath = `${opts.prefix || ''}/${path}`.replace(/\/\/+/g, '/');
+            const path = typeof handler.path === 'string'
+                ? handler.path
+                : typeof opts.method === 'string'
+                    ? opts.method
+                    : '';
+            const makePath = (p) => `${opts.prefix.replace(/\s+/g, '/') || ''}/${p}`
+                .replace(/\/\/+/g, '/')
+                // avoid interpreting "cmd:tail" as "cmd/:tail"
+                .replace(/\/\\:/g, '\\:');
+            let cliCommand = '';
             if (!fn) {
-                fn = () => __awaiter(this, void 0, void 0, function* () {
-                    const { restoreCtx } = useCliContext();
-                    const scopeId = useEventId().getId();
-                    const unscope = opts.registerEventScope(scopeId);
-                    const instance = yield opts.getInstance();
-                    restoreCtx();
-                    let response;
-                    const interceptorHandler = yield opts.getIterceptorHandler();
-                    restoreCtx();
-                    yield interceptorHandler.init();
-                    // params
-                    let args = [];
-                    try {
-                        restoreCtx();
-                        args = yield opts.resolveArgs();
-                    }
-                    catch (e) {
-                        response = e;
-                    }
-                    if (!response) {
-                        restoreCtx();
-                        // fire before interceptors
-                        response = yield interceptorHandler.fireBefore(response);
-                        // fire request handler
-                        if (!interceptorHandler.responseOverwritten) {
-                            try {
-                                restoreCtx();
-                                response = yield instance[opts.method](...args);
-                            }
-                            catch (e) {
-                                response = e;
-                            }
-                        }
-                    }
-                    restoreCtx();
-                    // fire after interceptors
-                    response = yield interceptorHandler.fireAfter(response);
-                    unscope();
-                    return response;
+                fn = defineMoostEventHandler({
+                    contextType: CONTEXT_TYPE,
+                    loggerTitle: LOGGER_TITLE,
+                    getIterceptorHandler: opts.getIterceptorHandler,
+                    getControllerInstance: opts.getInstance,
+                    controllerMethod: opts.method,
+                    resolveArgs: opts.resolveArgs,
+                    logErrors: (_a = this.opts) === null || _a === void 0 ? void 0 : _a.debug,
+                    hooks: {
+                        init: () => setCliHelpForEvent(this.cliHelp),
+                    },
                 });
             }
-            this.cliApp.cli(targetPath, fn);
-            opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            const targetPath = makePath(path);
+            const { getArgs, getStaticPart } = this.cliApp.cli(targetPath, fn);
+            const meta = getCliMate().read(opts.fakeInstance, opts.method);
+            const classMeta = getCliMate().read(opts.fakeInstance);
+            const args = {};
+            getArgs().forEach(a => {
+                var _a;
+                const argParam = (_a = meta === null || meta === void 0 ? void 0 : meta.params) === null || _a === void 0 ? void 0 : _a.find(p => p.label === a && p.description);
+                args[a] = (argParam === null || argParam === void 0 ? void 0 : argParam.description) || '';
+            });
+            cliCommand = getStaticPart().replace(/\//g, ' ').trim();
+            const cliOptions = new Map();
+            [
+                ...(((_c = (_b = this.opts) === null || _b === void 0 ? void 0 : _b.globalCliOptions) === null || _c === void 0 ? void 0 : _c.length) ? this.opts.globalCliOptions : []),
+                ...((classMeta === null || classMeta === void 0 ? void 0 : classMeta.cliOptions) || []),
+                ...(((_d = meta === null || meta === void 0 ? void 0 : meta.params) === null || _d === void 0 ? void 0 : _d.filter(param => !!param.cliParamKeys && param.cliParamKeys.length > 0).map(param => ({
+                    keys: param.cliParamKeys,
+                    value: typeof param.value === 'string' ? param.value : '',
+                    description: param.description || '',
+                }))) || []),
+            ].forEach(o => cliOptions.set(o.keys[0], o));
+            if ((_e = this.opts) === null || _e === void 0 ? void 0 : _e.debug) {
+                opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            }
+            const aliases = [];
+            if (meta === null || meta === void 0 ? void 0 : meta.cliAliases) {
+                for (const alias of meta.cliAliases) {
+                    const targetPath = makePath(alias);
+                    const { getStaticPart } = this.cliApp.cli(targetPath, fn);
+                    aliases.push(getStaticPart().replace(/\//g, ' ').trim());
+                    if ((_f = this.opts) === null || _f === void 0 ? void 0 : _f.debug) {
+                        opts.logHandler(`${''}(CLI-alias)${''}${targetPath}`);
+                    }
+                }
+            }
+            this.cliHelp.addEntry({
+                description: (meta === null || meta === void 0 ? void 0 : meta.description) || '',
+                command: cliCommand,
+                options: Array.from(cliOptions.values()),
+                args,
+                aliases: aliases,
+                custom: { fn, log: opts.logHandler },
+                examples: (meta === null || meta === void 0 ? void 0 : meta.cliExamples) || [],
+            });
         }
     }
 }
 
-function getCliMate() {
-    return getMoostMate();
+function formatParams(keys) {
+    const names = [keys].flat();
+    return names.map((n) => (n.length === 1 ? '-' + n : '--' + n));
 }
 
 /**
- * Get Cli Flag
- * @decorator
- * @param name - flag name
- * @paramType string
+ * ## Define CLI Option
+ * ### @ParameterDecorator
+ * Use together with @Description('...') to document cli option
+ *
+ * ```ts
+ * │   @Cli('command')
+ * │   command(
+ * │      @Description('Test flag...')
+ * │      @CliOption('test', 't')
+ * │      test: boolean,
+ * │   ) {
+ * │       return `test=${ test }`
+ * │   }
+ * ```
+ *
+ * @param keys list of keys (short and long alternatives)
+ * @returns
  */
-function Flag(name) {
-    return Resolve(() => useFlags()[name], name);
-}
-/**
- * Get Cli Flags
- * @decorator
- * @paramType object
- */
-function Flags() {
-    return Resolve(() => useFlags(), 'flags');
-}
-function formatParams(keys) {
-    const names = [keys].flat();
-    return names.map(n => n.length === 1 ? '-' + n : '--' + n);
-}
-function CliParam(keys, descr) {
+function CliOption(...keys) {
     const mate = getCliMate();
-    return mate.apply(mate.decorate('cliParams', { keys, descr }, true), Resolve(() => {
+    return mate.apply(mate.decorate('cliParamKeys', keys, false), Resolve(() => {
         const flags = useFlags();
-        const names = [keys].flat();
+        const names = keys;
         const vals = [];
         for (const name of names) {
             if (flags[name]) {
@@ -141,10 +278,143 @@ function CliParam(keys, descr) {
         }
         return vals[0];
     }, formatParams(keys).join(', ')));
+}
+/**
+ * ## Define Global CLI Option
+ * ### @ClassDecorator
+ * The option described here will appear in every command instructions
+ * @param option keys and description of CLI option
+ * @returns
+ */
+function CliGlobalOption(option) {
+    const mate = getCliMate();
+    return mate.decorate('cliOptions', option, true);
 }
 
+/**
+ * ## 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
+ */
 function Cli(path) {
-    return getCliMate().decorate('handlers', { path, type: 'CLI' }, true);
+    return getCliMate().decorate('handlers', { path: path === null || path === void 0 ? void 0 : path.replace(/\s+/g, '/'), type: 'CLI' }, true);
+}
+/**
+ * ## Define CLI Command Alias
+ * ### @MethodDecorator
+ *
+ * Use it to define alias for @Cli('...') command
+ *
+ * @param path - command alias path
+ * @returns
+ */
+function CliAlias(alias) {
+    return getCliMate().decorate('cliAliases', alias, true);
+}
+/**
+ * ## Define CLI Example
+ * ### @MethodDecorator
+ *
+ * Use it to define example for Cli Help display
+ *
+ * @param path - command alias path
+ * @returns
+ */
+function CliExample(cmd, description) {
+    return getCliMate().decorate('cliExamples', { cmd, description }, true);
 }
 
-export { Cli, CliParam, Flag, Flags, MoostCli };
+/**
+ * ### 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 TInterceptorFn
+ */
+const cliHelpInterceptor = (opts) => {
+    return defineInterceptorFn(() => {
+        const helpOptions = (opts === null || opts === void 0 ? void 0 : opts.helpOptions) || ['help'];
+        for (const option of helpOptions) {
+            if (useFlag(option) === true) {
+                try {
+                    useCliHelp().print(opts === null || opts === void 0 ? void 0 : opts.colors);
+                    return '';
+                }
+                catch (e) {
+                    //
+                }
+            }
+        }
+        if ((opts === null || opts === void 0 ? void 0 : opts.helpWithArgs) || (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd)) {
+            const { getMethod } = useControllerContext();
+            if (!getMethod()) {
+                const parts = useCliContext().store('event').get('pathParams');
+                const cliHelp = useCliHelp().getCliHelp();
+                const cmd = cliHelp.getCliName();
+                let data;
+                for (let i = 0; i < Math.min(parts.length, 4); i++) {
+                    const pathParams = parts.slice(0, i ? -i : parts.length).join(' ');
+                    try {
+                        data = cliHelp.match(pathParams);
+                        break;
+                    }
+                    catch (e) {
+                        if (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) {
+                            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 ((opts === null || opts === void 0 ? void 0 : opts.helpWithArgs) && main.args && Object.keys(main.args).length) {
+                        throw new Error(`Arguments expected: ${Object.keys(main.args).map(l => `<${l}>`).join(', ')}`);
+                    }
+                    else if ((opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) && children && children.length) {
+                        throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map(c => `  $ ${cmd} ${c.command}`).join('\n')}`);
+                    }
+                }
+            }
+        }
+    }, TInterceptorPriority.BEFORE_ALL);
+};
+/**
+ * ## @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
+ */
+const CliHelpInterceptor = (...opts) => Intercept(cliHelpInterceptor(...opts));
+
+export { Cli, CliAlias, CliExample, CliGlobalOption, CliHelpInterceptor, CliOption, MoostCli, cliHelpInterceptor, setCliHelpForEvent, useCliHelp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-cli",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "@moostjs/event-cli",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -28,11 +28,12 @@
   },
   "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/event-cli#readme",
   "peerDependencies": {
-    "moost": "0.2.27",
-    "wooks": "^0.2.18",
-    "@wooksjs/event-core": "^0.2.18"
+    "moost": "0.2.29",
+    "wooks": "^0.2.23",
+    "@wooksjs/event-core": "^0.2.23"
   },
   "dependencies": {
-    "@wooksjs/event-cli": "^0.2.18"
+    "@wooksjs/event-cli": "^0.2.23",
+    "@prostojs/cli-help": "^0.0.9"
   }
 }