@moostjs/event-cli 0.2.26 → 0.2.28

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,209 @@ 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 (cliApp) {
-            this.cliApp = eventCli.createCliApp(cliApp);
+        else if (cliAppOpts) {
+            this.cliApp = eventCli.createCliApp(Object.assign(Object.assign({}, cliAppOpts), { onNotFound: this.onNotFound.bind(this) }));
         }
         else {
-            this.cliApp = eventCli.createCliApp();
+            this.cliApp = eventCli.createCliApp({
+                onNotFound: this.onNotFound.bind(this),
+            });
+        }
+        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.cliHelp = new cliHelp.CliHelpRenderer();
+        }
+        if (!(opts === null || opts === void 0 ? void 0 : opts.debug)) {
+            moost.getMoostInfact().silent(true);
+        }
+    }
+    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() {
+    onInit(moost) {
+        this.moost = moost;
         void this.cliApp.run();
     }
     bindHandler(opts) {
+        var _a, _b, _c;
         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 targetPath = `${opts.prefix.replace(/\s+/g, '/') || ''}/${path}`
+                .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 { getArgs, getStaticPart } = this.cliApp.cli(targetPath, fn);
+            const meta = getCliMate().read(opts.fakeInstance, opts.method);
+            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();
+            this.cliHelp.addEntry({
+                description: (meta === null || meta === void 0 ? void 0 : meta.description) || '',
+                command: cliCommand,
+                options: ((_b = meta === null || meta === void 0 ? void 0 : meta.params) === null || _b === void 0 ? void 0 : _b.filter(param => !!param.cliParamKeys && param.cliParamKeys.length > 0).map(param => ({
+                    keys: param.cliParamKeys,
+                    value: typeof param.value === 'string' ? param.value : '',
+                    description: param.description || '',
+                }))) || [],
+                args,
+                aliases: meta === null || meta === void 0 ? void 0 : meta.cliAliases,
+            });
+            if ((_c = this.opts) === null || _c === void 0 ? void 0 : _c.debug) {
+                opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            }
         }
     }
 }
 
-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
+ * ## 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 moost.Resolve(() => eventCli.useFlags()[name], name);
-}
-/**
- * Get Cli Flags
- * @decorator
- * @paramType object
- */
-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]) {
@@ -145,12 +250,121 @@ function CliParam(keys, descr) {
     }, formatParams(keys).join(', ')));
 }
 
+/**
+ * ## 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);
 }
 
+/**
+ * ### 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 pathParams = eventCli.useCliContext().store('event').get('pathParams').join(' ');
+                const cliHelp = useCliHelp().getCliHelp();
+                const cmd = cliHelp.getCliName();
+                let data;
+                try {
+                    data = cliHelp.match(pathParams);
+                }
+                catch (e) {
+                    if (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) {
+                        const variants = cliHelp.lookup(pathParams);
+                        if (variants.length) {
+                            throw new Error(`Command is incomplete, 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) {
+                        throw new Error(`Command is incomplete, 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.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,220 @@
+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 { 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;
 
 /**
- * Get Cli Flag
- * @decorator
- * @param name - flag name
- * @paramType string
+ * ## @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 function Flag(name: string): ParameterDecorator & PropertyDecorator;
+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 Flags
- * @decorator
- * @paramType object
+ * ### 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 Flags(): 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;
 
+/**
+ * ## 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 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: CliHelpRenderer;
+    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: CliHelpRenderer): void;
+
 export declare interface TCliHandlerMeta {
     path: string;
 }
 
+export declare interface TMoostCliOpts {
+    /**
+     * WooksCli options or instance
+     */
+    wooksCli?: WooksCli | TWooksCliOptions;
+    /**
+     * CliHelpRenderer options or instance
+     */
+    cliHelp?: CliHelpRenderer | TCliHelpOptions;
+    /**
+     * more internal logs are printed when true
+     */
+    debug?: boolean;
+}
+
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * print(true)
+ * ```
+ * @returns
+ */
+export declare function useCliHelp(): {
+    getCliHelp: () => CliHelpRenderer;
+    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,209 @@ 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);
+        }
+    }
+    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() {
+    onInit(moost) {
+        this.moost = moost;
         void this.cliApp.run();
     }
     bindHandler(opts) {
+        var _a, _b, _c;
         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 targetPath = `${opts.prefix.replace(/\s+/g, '/') || ''}/${path}`
+                .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 { getArgs, getStaticPart } = this.cliApp.cli(targetPath, fn);
+            const meta = getCliMate().read(opts.fakeInstance, opts.method);
+            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();
+            this.cliHelp.addEntry({
+                description: (meta === null || meta === void 0 ? void 0 : meta.description) || '',
+                command: cliCommand,
+                options: ((_b = meta === null || meta === void 0 ? void 0 : meta.params) === null || _b === void 0 ? void 0 : _b.filter(param => !!param.cliParamKeys && param.cliParamKeys.length > 0).map(param => ({
+                    keys: param.cliParamKeys,
+                    value: typeof param.value === 'string' ? param.value : '',
+                    description: param.description || '',
+                }))) || [],
+                args,
+                aliases: meta === null || meta === void 0 ? void 0 : meta.cliAliases,
+            });
+            if ((_c = this.opts) === null || _c === void 0 ? void 0 : _c.debug) {
+                opts.logHandler(`${''}(CLI)${''}${targetPath}`);
+            }
         }
     }
 }
 
-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]) {
@@ -143,8 +248,114 @@ function CliParam(keys, descr) {
     }, formatParams(keys).join(', ')));
 }
 
+/**
+ * ## 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);
 }
 
-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 pathParams = useCliContext().store('event').get('pathParams').join(' ');
+                const cliHelp = useCliHelp().getCliHelp();
+                const cmd = cliHelp.getCliName();
+                let data;
+                try {
+                    data = cliHelp.match(pathParams);
+                }
+                catch (e) {
+                    if (opts === null || opts === void 0 ? void 0 : opts.helpWithIncompleteCmd) {
+                        const variants = cliHelp.lookup(pathParams);
+                        if (variants.length) {
+                            throw new Error(`Command is incomplete, 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) {
+                        throw new Error(`Command is incomplete, 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, CliHelpInterceptor, CliOption, MoostCli, cliHelpInterceptor, setCliHelpForEvent, useCliHelp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-cli",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "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.26",
-    "wooks": "^0.2.17",
-    "@wooksjs/event-core": "^0.2.17"
+    "moost": "0.2.28",
+    "wooks": "^0.2.22",
+    "@wooksjs/event-core": "^0.2.22"
   },
   "dependencies": {
-    "@wooksjs/event-cli": "^0.2.17"
+    "@wooksjs/event-cli": "^0.2.22",
+    "@prostojs/cli-help": "^0.0.7"
   }
 }