@wooksjs/event-cli 0.6.0 → 0.6.1

package/dist/index.cjs

@@ -1,4 +1,3 @@
-"use strict";
 //#region rolldown:runtime
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -37,6 +36,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 (0, __wooksjs_event_core.useAsyncEventContext)("CLI");
 }
@@ -50,7 +54,7 @@ var WooksCli = class extends wooks.WooksAdapterBase {
 	constructor(opts, wooks$1) {
 		super(wooks$1, opts?.logger, opts?.router);
 		this.opts = opts;
-		this.logger = opts?.logger || this.getLogger(`${"\x1B[96m"}[wooks-cli]`);
+		this.logger = opts?.logger || this.getLogger(`[wooks-cli]`);
 		this.cliHelp = opts?.cliHelp instanceof __prostojs_cli_help.CliHelpRenderer ? opts.cliHelp : new __prostojs_cli_help.CliHelpRenderer(opts?.cliHelp);
 	}
 	/**
@@ -166,10 +170,10 @@ var WooksCli = class extends wooks.WooksAdapterBase {
 				for (const handler of handlers) {
 					const response = await handler();
 					if (typeof response === "string") console.log(response);
-else if (Array.isArray(response)) response.forEach((r) => {
+					else if (Array.isArray(response)) response.forEach((r) => {
 						console.log(typeof r === "string" ? r : JSON.stringify(r, null, "  "));
 					});
-else if (response instanceof Error) {
+					else if (response instanceof Error) {
 						this.onError(response);
 						return response;
 					} else if (response) console.log(JSON.stringify(response, null, "  "));
@@ -178,15 +182,15 @@ else if (response instanceof Error) {
 				this.onError(error);
 				return error;
 			}
-else {
+			else {
 				this.onUnknownCommand(pathParams);
-				return new Error("Unknown command");
+				return /* @__PURE__ */ new Error("Unknown command");
 			}
 		});
 	}
 	onError(e) {
 		if (this.opts?.onError) this.opts.onError(e);
-else {
+		else {
 			this.error(e.message);
 			process.exit(1);
 		}
@@ -197,23 +201,34 @@ else {
 	*/
 	onUnknownCommand(pathParams) {
 		const raiseError = () => {
-			this.error(`${"\x1B[0m"}Unknown command: ${pathParams.join(" ")}`);
+			this.error(`Unknown command: ${pathParams.join(" ")}`);
 			process.exit(1);
 		};
 		if (this.opts?.onUnknownCommand) this.opts.onUnknownCommand(pathParams, raiseError);
-else raiseError();
+		else raiseError();
 	}
 	error(e) {
-		if (typeof e === "string") console.error(`${"\x1B[31m"}ERROR: ${"\x1B[0m"}${e}`);
-else console.error(`${"\x1B[31m"}ERROR: ${"\x1B[0m"}${e.message}`);
+		if (typeof e === "string") console.error(`ERROR: ${e}`);
+		else console.error(`ERROR: ${e.message}`);
 	}
 };
+/**
+* Factory for WooksCli App
+* @param opts TWooksCliOptions
+* @param wooks Wooks | WooksAdapterBase
+* @returns WooksCli
+*/
 function createCliApp(opts, wooks$1) {
 	return new WooksCli(opts, wooks$1);
 }
 
 //#endregion
 //#region packages/event-cli/src/composables/options.ts
+/**
+* Get CLI Options
+*
+* @returns an object with CLI options
+*/
 function useCliOptions() {
 	const { store } = useCliContext();
 	const flags = store("flags");
@@ -223,6 +238,12 @@ function useCliOptions() {
 	}
 	return flags.value;
 }
+/**
+* Getter for Cli Option value
+*
+* @param name name of the option
+* @returns value of a CLI option
+*/
 function useCliOption(name) {
 	try {
 		const options = useCliHelp().getEntry().options || [];
@@ -236,6 +257,19 @@ function useCliOption(name) {
 
 //#endregion
 //#region packages/event-cli/src/composables/cli-help.ts
+/**
+* ## 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");
@@ -249,12 +283,68 @@ function useCliHelp() {
 		}
 	};
 }
+/**
+* ## 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) {
 		useCliHelp().print(colors);
 		return true;
 	}
 }
+/**
+* ##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")?.flatMap((p) => `${p} `.split(":").map((s, i) => i ? `:${s}` : s)) || [];
 	const cliHelp = useCliHelp().getCliHelp();
@@ -273,18 +363,18 @@ function useCommandLookupHelp(lookupDepth = 3) {
 	if (data) {
 		const { main, children } = data;
 		if (main.args && Object.keys(main.args).length > 0) throw new Error(`Arguments expected: ${Object.keys(main.args).map((l) => `<${l}>`).join(", ")}`);
-else if (children?.length > 0) throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map((c) => `  $ ${cmd} ${c.command}`).join("\n")}`);
+		else if (children?.length > 0) throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map((c) => `  $ ${cmd} ${c.command}`).join("\n")}`);
 	}
 }
 
 //#endregion
-exports.WooksCli = WooksCli
-exports.cliShortcuts = cliShortcuts
-exports.createCliApp = createCliApp
-exports.createCliContext = createCliContext
-exports.useAutoHelp = useAutoHelp
-exports.useCliContext = useCliContext
-exports.useCliHelp = useCliHelp
-exports.useCliOption = useCliOption
-exports.useCliOptions = useCliOptions
-exports.useCommandLookupHelp = useCommandLookupHelp
+exports.WooksCli = WooksCli;
+exports.cliShortcuts = cliShortcuts;
+exports.createCliApp = createCliApp;
+exports.createCliContext = createCliContext;
+exports.useAutoHelp = useAutoHelp;
+exports.useCliContext = useCliContext;
+exports.useCliHelp = useCliHelp;
+exports.useCliOption = useCliOption;
+exports.useCliOptions = useCliOptions;
+exports.useCommandLookupHelp = useCommandLookupHelp;

package/dist/index.d.ts

@@ -21,6 +21,12 @@ interface TCliContextStore {
 }
 interface TCliHelpCustom {
     handler: TWooksHandler<any>;
+    /**
+     * ### Callback for registered path
+     *
+     * @param path registered path
+     * @param aliasType 0 - direct command, 1 - direct alias, 2 - computed alias
+     */
     cb?: <T>(path: string, aliasType: number, route?: TProstoRouterPathHandle<T>) => void;
 }
 type TCliHelpRenderer = CliHelpRenderer<TCliHelpCustom>;
@@ -46,29 +52,171 @@ declare class WooksCli extends WooksAdapterBase {
     protected logger: TConsoleBase;
     protected cliHelp: TCliHelpRenderer;
     constructor(opts?: TWooksCliOptions | undefined, wooks?: Wooks | WooksAdapterBase);
+    /**
+     * ### 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<ResType>): wooks.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[], _opts?: minimist.Opts): Promise<unknown>;
     protected onError(e: Error): void;
+    /**
+     * Triggers `unknown command` processing and callbacks
+     * @param pathParams `string[]` containing command
+     */
     onUnknownCommand(pathParams: string[]): void;
     protected error(e: string | Error): void;
 }
+/**
+ * Factory for WooksCli App
+ * @param opts TWooksCliOptions
+ * @param wooks Wooks | WooksAdapterBase
+ * @returns WooksCli
+ */
 declare function createCliApp(opts?: TWooksCliOptions, wooks?: Wooks | WooksAdapterBase): WooksCli;
 
+/**
+ * ## useCliHelp
+ * ### Composable
+ * ```js
+ * // example of printing cli instructions
+ * const { print } = useCliHelp()
+ * // print with colors
+ * print(true)
+ * // print with no colors
+ * // print(false)
+ * ```
+ * @returns
+ */
 declare function useCliHelp(): {
     getCliHelp: () => TCliHelpRenderer;
     getEntry: () => _prostojs_cli_help.TCliEntry<TCliHelpCustom>;
     render: (width?: number, withColors?: boolean) => string[];
     print: (withColors?: boolean) => void;
 };
+/**
+ * ## 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
+ */
 declare function useAutoHelp(keys?: string[], colors?: boolean): true | undefined;
+/**
+ * ##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)
+ * ...
+ */
 declare function useCommandLookupHelp(lookupDepth?: number): void;
 
+/**
+ * Get CLI Options
+ *
+ * @returns an object with CLI options
+ */
 declare function useCliOptions(): Record<string, string | boolean>;
+/**
+ * Getter for Cli Option value
+ *
+ * @param name name of the option
+ * @returns value of a CLI option
+ */
 declare function useCliOption(name: string): string | boolean;
 
 declare function createCliContext(data: Omit<TCliEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
+/**
+ * Wrapper on top of useEventContext that provides
+ * proper context types for CLI event
+ * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
+ */
 declare function useCliContext<T extends TEmpty>(): _wooksjs_event_core.TCtxHelpers<TCliContextStore & T & _wooksjs_event_core.TGenericContextStore<TCliEventData>>;
 
 export { type TCliContextStore, type TCliEventData, type TCliHelpCustom, type TCliHelpRenderer, type TWooksCliEntry, type TWooksCliOptions, WooksCli, cliShortcuts, createCliApp, createCliContext, useAutoHelp, useCliContext, useCliHelp, useCliOption, useCliOptions, useCommandLookupHelp };

package/dist/index.mjs

@@ -13,6 +13,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 useAsyncEventContext("CLI");
 }
@@ -26,7 +31,7 @@ var WooksCli = class extends WooksAdapterBase {
 	constructor(opts, wooks) {
 		super(wooks, opts?.logger, opts?.router);
 		this.opts = opts;
-		this.logger = opts?.logger || this.getLogger(`${"\x1B[96m"}[wooks-cli]`);
+		this.logger = opts?.logger || this.getLogger(`[wooks-cli]`);
 		this.cliHelp = opts?.cliHelp instanceof CliHelpRenderer ? opts.cliHelp : new CliHelpRenderer(opts?.cliHelp);
 	}
 	/**
@@ -142,10 +147,10 @@ var WooksCli = class extends WooksAdapterBase {
 				for (const handler of handlers) {
 					const response = await handler();
 					if (typeof response === "string") console.log(response);
-else if (Array.isArray(response)) response.forEach((r) => {
+					else if (Array.isArray(response)) response.forEach((r) => {
 						console.log(typeof r === "string" ? r : JSON.stringify(r, null, "  "));
 					});
-else if (response instanceof Error) {
+					else if (response instanceof Error) {
 						this.onError(response);
 						return response;
 					} else if (response) console.log(JSON.stringify(response, null, "  "));
@@ -154,15 +159,15 @@ else if (response instanceof Error) {
 				this.onError(error);
 				return error;
 			}
-else {
+			else {
 				this.onUnknownCommand(pathParams);
-				return new Error("Unknown command");
+				return /* @__PURE__ */ new Error("Unknown command");
 			}
 		});
 	}
 	onError(e) {
 		if (this.opts?.onError) this.opts.onError(e);
-else {
+		else {
 			this.error(e.message);
 			process.exit(1);
 		}
@@ -173,23 +178,34 @@ else {
 	*/
 	onUnknownCommand(pathParams) {
 		const raiseError = () => {
-			this.error(`${"\x1B[0m"}Unknown command: ${pathParams.join(" ")}`);
+			this.error(`Unknown command: ${pathParams.join(" ")}`);
 			process.exit(1);
 		};
 		if (this.opts?.onUnknownCommand) this.opts.onUnknownCommand(pathParams, raiseError);
-else raiseError();
+		else raiseError();
 	}
 	error(e) {
-		if (typeof e === "string") console.error(`${"\x1B[31m"}ERROR: ${"\x1B[0m"}${e}`);
-else console.error(`${"\x1B[31m"}ERROR: ${"\x1B[0m"}${e.message}`);
+		if (typeof e === "string") console.error(`ERROR: ${e}`);
+		else console.error(`ERROR: ${e.message}`);
 	}
 };
+/**
+* Factory for WooksCli App
+* @param opts TWooksCliOptions
+* @param wooks Wooks | WooksAdapterBase
+* @returns WooksCli
+*/
 function createCliApp(opts, wooks) {
 	return new WooksCli(opts, wooks);
 }
 
 //#endregion
 //#region packages/event-cli/src/composables/options.ts
+/**
+* Get CLI Options
+*
+* @returns an object with CLI options
+*/
 function useCliOptions() {
 	const { store } = useCliContext();
 	const flags = store("flags");
@@ -199,6 +215,12 @@ function useCliOptions() {
 	}
 	return flags.value;
 }
+/**
+* Getter for Cli Option value
+*
+* @param name name of the option
+* @returns value of a CLI option
+*/
 function useCliOption(name) {
 	try {
 		const options = useCliHelp().getEntry().options || [];
@@ -212,6 +234,19 @@ function useCliOption(name) {
 
 //#endregion
 //#region packages/event-cli/src/composables/cli-help.ts
+/**
+* ## 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");
@@ -225,12 +260,68 @@ function useCliHelp() {
 		}
 	};
 }
+/**
+* ## 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) {
 		useCliHelp().print(colors);
 		return true;
 	}
 }
+/**
+* ##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")?.flatMap((p) => `${p} `.split(":").map((s, i) => i ? `:${s}` : s)) || [];
 	const cliHelp = useCliHelp().getCliHelp();
@@ -249,7 +340,7 @@ function useCommandLookupHelp(lookupDepth = 3) {
 	if (data) {
 		const { main, children } = data;
 		if (main.args && Object.keys(main.args).length > 0) throw new Error(`Arguments expected: ${Object.keys(main.args).map((l) => `<${l}>`).join(", ")}`);
-else if (children?.length > 0) throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map((c) => `  $ ${cmd} ${c.command}`).join("\n")}`);
+		else if (children?.length > 0) throw new Error(`Wrong command, did you mean:\n${children.slice(0, 7).map((c) => `  $ ${cmd} ${c.command}`).join("\n")}`);
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "@wooksjs/event-cli",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -39,19 +39,19 @@
     "url": "https://github.com/wooksjs/wooksjs/issues"
   },
   "peerDependencies": {
-    "@wooksjs/event-core": "^0.6.0",
-    "wooks": "^0.6.0"
+    "@prostojs/logger": "^0.4.3",
+    "@prostojs/router": "^0.2.1",
+    "@wooksjs/event-core": "^0.6.1",
+    "wooks": "^0.6.1"
   },
   "dependencies": {
     "@prostojs/cli-help": "^0.0.11",
-    "@prostojs/logger": "^0.4.3",
-    "@prostojs/router": "^0.2.1",
-    "minimist": "^1.2.6"
+    "minimist": "^1.2.8"
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",
-    "typescript": "^5.7.3",
-    "vitest": "^2.1.8"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
   },
   "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-cli#readme",
   "scripts": {