juisy 2.0.0-beta.0

package/dist/cli/index.js

@@ -0,0 +1,559 @@
+/*!
+ * juisy v1.4.0
+ * Copyright © 2022-Present Hervé Perchec
+ */
+
+import { hideBin } from 'yargs/helpers';
+import execa from 'execa';
+import _prompts from 'prompts';
+import chalk from 'chalk';
+import indent from 'indent-string';
+import _stripAnsi from 'strip-ansi';
+import Yargs from 'yargs/yargs';
+import deepmerge from 'deepmerge';
+
+class Command {
+  /**
+   * Creates a Command instance from object (CommandModule)
+   * @param {CommandModule} commandObject - The command definition object
+   */
+  constructor(commandObject) {
+    this.command = commandObject.command;
+    this.aliases = commandObject.aliases;
+    this.describe = commandObject.describe;
+    this.deprecated = commandObject.deprecated;
+    this.meta = commandObject.meta;
+    this.builder = commandObject.builder || ((cli) => cli);
+    this.handler = commandObject.handler;
+  }
+  /**
+   * The command
+   */
+  command;
+  /**
+   * The aliases
+   */
+  aliases;
+  /**
+   * Command description
+   */
+  describe;
+  /**
+   * Is deprecated?
+   */
+  deprecated;
+  /**
+   * Command meta
+   */
+  meta;
+  /**
+   * Command builder
+   */
+  builder;
+  /**
+   * Command handler
+   */
+  handler;
+}
+
+const loading = {
+  // Duration of each character displaying (in ms)
+  velocity: 250,
+  // Reference to call setInterval and clearInterval
+  intervalRef: null,
+  // Display loading to STDOUT
+  display: function(message) {
+    const P = ["\\", "|", "/", "-"];
+    const S = ["   ", ".  ", ".. ", "..."];
+    let x = 0;
+    let y = 0;
+    const velocity = this.velocity;
+    this.intervalRef = setInterval(function() {
+      process.stdout.write("\r" + P[x++] + " " + message + " : " + S[y++]);
+      x &= 3;
+      y &= 3;
+    }, velocity);
+  },
+  stop: function() {
+    clearInterval(this.intervalRef);
+    try {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+    } catch (err) {
+      console.log("Warn: process.stdout.clearLine (or cursorTo) function is non-TTY. Skipped...");
+    }
+  }
+};
+class OutputUtils {
+  /**
+   * To automatically increment step index
+   * @ignore
+   */
+  static stepsCache = {
+    index: 0
+    // 0 by default
+  };
+  /**
+   * Use `chalk` package to style output in console/stdout
+   * @example
+   * const { $style } = OutputUtils
+   * console.log($style.green('Green text!')) // => '[32mGreen text![0m'
+   */
+  static $style = chalk;
+  /**
+   * Format a message for console output
+   * @param msg - The message to format
+   * @param options - Format options
+   * @returns The formatted message
+   * @example
+   * formatOutputMessage('laundry\nshopping', { indentChar: '- ' })
+   * // => '- laundry\n- shopping'
+   *
+   * formatOutputMessage('foo\nbar', { indent: 2, indentChar: '❤' })
+   * // => '❤❤foo\n❤❤bar'
+   */
+  static formatOutputMessage(msg, options = {}) {
+    let formatted = `${msg}`;
+    if (options.indentChar) {
+      if (options.indent === void 0) {
+        options.indent = 1;
+      }
+    } else {
+      options.indentChar = " ";
+      options.indent = options.indent || 0;
+    }
+    if (options.indent) {
+      formatted = indent(msg, options.indent, { indent: options.indentChar });
+    }
+    return formatted;
+  }
+  /**
+   * @param msg - The message
+   * @param options - (Optional) Options object
+   * @param options.indent - How many repeat indent (see `indent-string` package)
+   * @param options.indentChar - Indent character(s). If `options.indent` not provided, will be repeated only 1 time
+   * @description
+   * Log message in console
+   * @example
+   * const { log } = OutputUtils
+   * log() // => blank line
+   * log('Hello world! =)') // => 'Hello world! =)'
+   * log('To do:', { indent: 2 }) // => '  To do:'
+   */
+  static log(msg, options = {}) {
+    const loggerInstance = options.loggerInstance || console;
+    if (msg) {
+      loggerInstance.log(OutputUtils.formatOutputMessage(msg, options));
+    } else {
+      loggerInstance.log();
+    }
+  }
+  /**
+   * Display warning message
+   * @param msg - The message to display
+   * @example
+   * const { warn } = OutputUtils
+   * warn('No configuration file') // => '[33m⚠ Warning: No configuration file[0m'
+   */
+  static warn(msg) {
+    OutputUtils.log(OutputUtils.$style.yellow(`⚠ Warning: ${msg}`));
+  }
+  /**
+   * @param msg - The message to display
+   * @param {Error} [err] - If provided, throw the error
+   * @description
+   * Display error message. Throws `err` if provided.
+   * @example
+   * const { error } = require('@hperchec/juisy').utils
+   * error('No configuration file') // => '[31m⨉ ERROR: No configuration file[0m'
+   * error('No configuration file', error) // => Log and throws error
+   */
+  static error(msg, err = void 0) {
+    OutputUtils.log(OutputUtils.$style.red(`⨉ ERROR: ${msg}`));
+    if (err !== void 0) {
+      OutputUtils.log();
+      throw err;
+    }
+  }
+  /**
+   * Log step title
+   * @param msg - The message to display
+   * @param options - Options object
+   * @param options.index - Custom index. If `null`, no index prepended to string
+   * @example
+   * step('Important step') // => '● 1 - Important step'
+   * step('Very important step') // => '● 2 - Very important step'
+   */
+  static step(msg, options = {}) {
+    OutputUtils.stepsCache.index++;
+    if (options.index === void 0) {
+      options.index = OutputUtils.stepsCache.index;
+    }
+    OutputUtils.log(`${options.index !== null ? options.index + " - " : ""}${msg}`, { indentChar: "● " });
+  }
+  /**
+   * Log substep title
+   * @param msg - The message to display
+   * @param options - Options object
+   * @param options.last - Defines if it is the last substep
+   * @example
+   * const { substep } = require('@hperchec/juisy').utils
+   * substep('Awesome substep') // => '├ Awesome substep'
+   * substep('Last substep', { last: true }) // => '└ Last substep'
+   */
+  static substep(msg, options = {}) {
+    OutputUtils.log(msg, { indentChar: options.last ? "└ " : "├ " });
+  }
+  /**
+   * @param {string} message - Message to display
+   * @param {Function} fct - The function to execute
+   * @returns {Promise<void>}
+   * @description
+   * Wait function: display loading during 'fct' execution
+   * @example
+   * const { wait } = require('@hperchec/juisy').utils
+   * await wait('Waiting', async () => {
+   *   // Do async logic
+   * })
+   */
+  static async wait(message, fct) {
+    loading.display(message);
+    await fct();
+    loading.stop();
+  }
+  /**
+   * See `strip-ansi` package documentation
+   * @see https://www.npmjs.com/package/strip-ansi
+   */
+  static stripAnsi = _stripAnsi;
+}
+
+const { log, $style } = OutputUtils;
+class InterfaceUtils {
+  /**
+   * Get root directory path
+   * @example
+   * import { CLIUtils: { rootDir } } from '@hperchec/juisy'
+   * console.log(rootDir) // => 'path/to/your/root/dir'
+   */
+  static rootDir = process.cwd();
+  /**
+   * @param {string} bin - Command
+   * @param {string[]} args - Same as execa second arg
+   * @param {object} [opts] - Options
+   * @returns {Promise<object>} The `execa` Promise
+   * @description
+   * Run command (child_process). See also `execa` package documentation
+   * @example
+   * const { run } = require('@hperchec/juisy').utils
+   * await run('npm', [ 'run', 'test' ], { stdio: 'inherit' })
+   */
+  static run(bin, args, opts = {}) {
+    return execa(bin, args, { stdio: "inherit", cwd: InterfaceUtils.rootDir, ...opts });
+  }
+  /**
+   * @alias utils.abort
+   * @param {number} [code] - Code for process.exit() (default: 0)
+   * @returns {void}
+   * @description
+   * Exit process
+   * @example
+   * const { abort } = require('@hperchec/juisy').utils
+   * abort() // => exit process with code 0
+   * abort(1) // => error code
+   */
+  static abort(code = 0) {
+    log($style.yellow("Aborted..."));
+    process.exit(code);
+  }
+  /**
+   * @alias utils.confirm
+   * @param {prompts.PromptObject} question - A prompt question object (see https://gitlab.com/hperchec/juisy/-/blob/main/documentation/utils.md#utilspromptsargs-object)
+   * @returns {Promise<boolean>} - True if confirmed
+   * @description
+   * Demand confirmation with prompts native util. If not confirmed, it will automatically abort the script.
+   * @example
+   * confirm({ message: 'Confirm to continue' }) // Deny it will abort the script
+   */
+  static async confirm(question) {
+    if (!question) {
+      question = {
+        type: "confirm",
+        name: "yes"
+      };
+    }
+    const { yes } = await InterfaceUtils.prompts([
+      {
+        message: "Confirm?",
+        initial: true,
+        ...question,
+        type: "confirm",
+        name: "yes"
+      }
+    ]);
+    if (!yes) {
+      InterfaceUtils.abort();
+    } else {
+      return true;
+    }
+  }
+  /**
+   * See `prompts` package documentation
+   * @example
+   * const { prompts } = InterfaceUtils
+   * // See prompts documentation
+   * @see https://www.npmjs.com/package/prompts
+   */
+  static prompts = _prompts;
+}
+
+function wrapCommandBuilder(target, builder) {
+  const _target = target || ((cli) => cli);
+  return (cli) => {
+    return _target(builder(cli));
+  };
+}
+function wrapCommandhandler(target, handler) {
+  return function(args) {
+    handler.call(this, args);
+    return target.call(this, args);
+  };
+}
+
+const visitor$2 = function(commandObject, cli) {
+  commandObject.handler = wrapCommandhandler(commandObject.handler, function(args) {
+    Object.defineProperty(this, "engine", {
+      get() {
+        return cli;
+      }
+    });
+    Object.defineProperty(this, "log", {
+      get() {
+        return (msg, options2 = {}) => {
+          OutputUtils.log(msg, {
+            ...options2,
+            loggerInstance: cli.getInternalMethods().getLoggerInstance()
+          });
+        };
+      }
+    });
+  });
+  return commandObject;
+};
+const options$2 = {};
+
+const commandHandlerInjections = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
+    __proto__: null,
+    options: options$2,
+    visitor: visitor$2
+}, Symbol.toStringTag, { value: 'Module' }));
+
+const visitor$1 = function(commandObject, cli) {
+  if (commandObject.meta) {
+    const commandMeta = commandObject.meta;
+    commandObject.builder = wrapCommandBuilder(commandObject.builder, function(_cli) {
+      _cli._meta = deepmerge(_cli._meta, commandMeta);
+      return _cli;
+    });
+  }
+  return commandObject;
+};
+const options$1 = {};
+
+const getCommandMeta = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
+    __proto__: null,
+    options: options$1,
+    visitor: visitor$1
+}, Symbol.toStringTag, { value: 'Module' }));
+
+const visitor = function(commandObject, engine, options2) {
+  const { metaProp, envKey } = options2;
+  if (commandObject.meta?.[metaProp]) {
+    if (process.env[envKey] === "private") {
+      commandObject.builder = wrapCommandBuilder(commandObject.builder, function(cli) {
+        cli._isPrivate = true;
+        return cli;
+      });
+    } else {
+      return false;
+    }
+  }
+  return commandObject;
+};
+const options = {
+  metaProp: "private",
+  envKey: "CLI_ENV"
+};
+
+const privateCommand = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
+    __proto__: null,
+    options,
+    visitor
+}, Symbol.toStringTag, { value: 'Module' }));
+
+const commandVisitors = {
+  commandHandlerInjections,
+  getCommandMeta,
+  privateCommand
+};
+
+function createEngine(yargs) {
+  const xargs = yargs;
+  xargs._isPrivate = false;
+  xargs._globalCommandVisitors = {};
+  xargs._globalCommandVisitorsEnabled = /* @__PURE__ */ new Set([]);
+  xargs._meta = {
+    private: false
+  };
+  const originalCommandMethod = xargs.command;
+  xargs.originalCommand = originalCommandMethod;
+  xargs.command = command;
+  xargs.globalCommandVisitor = globalCommandVisitor;
+  xargs.globalCommandVisitorOptions = globalCommandVisitorOptions;
+  xargs.hasGlobalCommandVisitor = hasGlobalCommandVisitor;
+  xargs.disableGlobalCommandVisitors = disableGlobalCommandVisitors;
+  xargs.enableGlobalCommandVisitors = enableGlobalCommandVisitors;
+  xargs.isPrivate = isPrivate;
+  xargs.getMeta = getMeta;
+  return xargs.globalCommandVisitor("command-handler-injections-visitor", commandVisitors.commandHandlerInjections.visitor, commandVisitors.commandHandlerInjections.options).globalCommandVisitor("get-meta-command-visitor", commandVisitors.getCommandMeta.visitor, commandVisitors.getCommandMeta.options).globalCommandVisitor("private-command-visitor", commandVisitors.privateCommand.visitor, commandVisitors.privateCommand.options).strict().help();
+}
+function command(...args) {
+  const self = this;
+  if (args.length === 1) {
+    const visit = (cmdModule) => {
+      const cmdObj = {
+        ...cmdModule
+      };
+      let failOnFalsyReturn;
+      for (const name of self._globalCommandVisitorsEnabled) {
+        const globalVisitor = self._globalCommandVisitors[name];
+        if (!globalVisitor(cmdObj, self, globalVisitor.options)) {
+          failOnFalsyReturn = true;
+        }
+      }
+      return failOnFalsyReturn ? false : cmdObj;
+    };
+    if (args[0] instanceof Array) {
+      const cmdsArray = [];
+      for (const commandModule of args[0]) {
+        const visited = visit(commandModule);
+        if (visited)
+          cmdsArray.push(visited);
+      }
+      return self.originalCommand(cmdsArray);
+    } else {
+      const visited = visit(args[0]);
+      return visited ? self.originalCommand(visited) : self;
+    }
+  } else {
+    return self.originalCommand(...args);
+  }
+}
+function globalCommandVisitor(name, visitor, defaultOptions = {}) {
+  this._globalCommandVisitors[name] = visitor;
+  return this.enableGlobalCommandVisitors([name]).globalCommandVisitorOptions(name, defaultOptions);
+}
+function globalCommandVisitorOptions(name, options) {
+  this._globalCommandVisitors[name].options = {
+    ...this._globalCommandVisitors[name].options,
+    ...options
+  };
+  return this;
+}
+function hasGlobalCommandVisitor(name) {
+  return Object.keys(this._globalCommandVisitors).includes(name);
+}
+function disableGlobalCommandVisitors(visitors = []) {
+  for (const name of visitors) {
+    if (this.hasGlobalCommandVisitor(name)) {
+      this._globalCommandVisitorsEnabled.delete(name);
+    } else {
+      throw new Error('Global command visitor: "' + name + '" not defined.');
+    }
+  }
+  return this;
+}
+function enableGlobalCommandVisitors(visitors = []) {
+  for (const name of visitors) {
+    if (this.hasGlobalCommandVisitor(name)) {
+      this._globalCommandVisitorsEnabled.add(name);
+    } else {
+      throw new Error('Global command visitor: "' + name + '" not defined.');
+    }
+  }
+  return this;
+}
+function isPrivate() {
+  return this._isPrivate;
+}
+function getMeta() {
+  return this._meta;
+}
+
+function CLIFactory(builder) {
+  const cli = function(argv) {
+    const engine = createEngine(Yargs(argv));
+    return builder(engine);
+  };
+  return cli;
+}
+
+async function extractUsage(factory, recursive = false, args = [""], locale = "en") {
+  const innerYargs = factory([""]);
+  innerYargs.locale(locale);
+  const doclet = {
+    command: void 0,
+    args: void 0,
+    aliases: void 0,
+    deprecated: false,
+    extractedUsage: void 0,
+    rawUsage: void 0,
+    children: recursive ? {} : void 0
+  };
+  const parseCallback = function(err, argv, output) {
+    if (err)
+      throw err;
+    const self = this;
+    doclet.args = argv._;
+    doclet.command = argv._[argv._.length - 1];
+    doclet.rawUsage = output;
+    const extractedUsage = doclet.extractedUsage = {};
+    extractedUsage.demandedCommands = self.getDemandedCommands();
+    extractedUsage.demandedOptions = self.getDemandedOptions();
+    extractedUsage.deprecatedOptions = self.getDeprecatedOptions();
+    extractedUsage.groups = self.getGroups();
+    extractedUsage.options = self.getOptions();
+    const internalMethods = self.getInternalMethods();
+    const usageInstance = internalMethods.getUsageInstance();
+    extractedUsage.usages = usageInstance.getUsage();
+    const commandInstance = internalMethods.getCommandInstance();
+    doclet.aliases = commandInstance.aliasMap;
+    const childCommandsFromHandlers = commandInstance.handlers;
+    const childCommandsFromUsage = usageInstance.getCommands();
+    extractedUsage.commands = Object.keys(childCommandsFromHandlers).reduce((accumulator, handlerKey) => {
+      const [cmd, description, isDefault, aliases, deprecated] = childCommandsFromUsage.find((command) => {
+        return command[0] === childCommandsFromHandlers[handlerKey].original;
+      });
+      accumulator[handlerKey] = { cmd, description, isDefault, aliases, deprecated };
+      return accumulator;
+    }, {});
+  };
+  await innerYargs.parseAsync(args, { help: true }, parseCallback);
+  if (recursive) {
+    for (const childCommand in doclet.extractedUsage.commands) {
+      doclet.children[childCommand] = await extractUsage(factory, true, [...args.filter((a) => a !== ""), childCommand], locale);
+    }
+  }
+  return doclet;
+}
+
+globalThis.CLI = {
+  helpers: {
+    hideBin
+  },
+  Command,
+  InterfaceUtils,
+  OutputUtils
+};
+
+export { CLIFactory, Command, InterfaceUtils, OutputUtils, extractUsage };

package/dist/cli/types.d.ts

@@ -0,0 +1,112 @@
+import { Argv, CommandModule as YargsCommandModule, CommandBuilder, MiddlewareFunction } from 'yargs';
+/**
+ * An object whose all properties have the same type.
+ */
+type Dictionary<T = any> = {
+    [key: string]: T;
+};
+/**
+ * An array whose first element is not undefined.
+ */
+type NotEmptyArray<T = any> = [T, ...T[]];
+/** Shims for private yargs types */
+interface Positional {
+    cmd: NotEmptyArray<string>;
+    variadic: boolean;
+}
+export interface YargsCommandHandler {
+    builder: CommandBuilder;
+    demanded: Positional[];
+    deprecated?: boolean;
+    description?: string | false;
+    handler: CommandModule['handler'];
+    middlewares: MiddlewareFunction[];
+    optional: Positional[];
+    original: string;
+}
+/** ---------------------------- */
+/**
+ * Our custon extended Yargs type
+ */
+export interface CLIEngine extends Argv {
+    _isPrivate: boolean;
+    _globalCommandVisitors: Record<string, CommandVisitor>;
+    _globalCommandVisitorsEnabled: Set<string>;
+    _meta: Record<string, any> & {
+        private: boolean;
+    };
+    originalCommand: Argv['command'];
+    globalCommandVisitor: (name: string, visitor: CommandVisitor, defaultOptions: any) => this;
+    globalCommandVisitorOptions: (name: string, options: Record<any, any>) => this;
+    hasGlobalCommandVisitor: (name: string) => boolean;
+    disableGlobalCommandVisitors: (visitors: string[]) => this;
+    enableGlobalCommandVisitors: (visitors: string[]) => this;
+    isPrivate: () => this['_isPrivate'];
+    getMeta: () => this['_meta'];
+    getDemandedCommands: () => Dictionary<{
+        min: number;
+        max: number;
+        minMsg?: string | null;
+        maxMsg?: string | null;
+    }>;
+    getDemandedOptions: () => Dictionary<string | undefined>;
+    getDeprecatedOptions: () => Dictionary<string | boolean | undefined>;
+    getGroups: () => Dictionary<string[]>;
+    getOptions: () => Record<string, any>;
+    getInternalMethods: () => {
+        getCommandInstance(): any;
+        getContext(): any;
+        getHasOutput(): boolean;
+        getLoggerInstance(): any;
+        getParseContext(): any;
+        getParserConfiguration(): any;
+        getUsageConfiguration(): any;
+        getUsageInstance(): any;
+        getValidationInstance(): any;
+        hasParseCallback(): any;
+        isGlobalContext(): any;
+        postProcess(argv: any | Promise<any>, populateDoubleDash: boolean, calledFromCommand: boolean, runGlobalMiddleware: boolean): any;
+        reset(aliases?: any): any;
+        runValidation(aliases: Dictionary<string[]>, positionalMap: Dictionary<string[]>, parseErrors: Error | null, isDefaultCommand?: boolean): (argv: any) => void;
+        runYargsParserAndExecuteCommands(args: string | string[] | null, shortCircuit?: boolean | null, calledFromCommand?: boolean, commandIndex?: number, helpOnly?: boolean): any | Promise<any>;
+        setHasOutput(): void;
+    };
+}
+export type CommandModule = {
+    /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */
+    aliases: YargsCommandModule['aliases'];
+    /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */
+    command: YargsCommandModule['command'];
+    /** boolean (or string) to show deprecation notice */
+    deprecated: YargsCommandModule['deprecated'];
+    /** string used as the description for the command in help text, use `false` for a hidden command */
+    describe: YargsCommandModule['describe'];
+    /** a function which will be passed the parsed argv. */
+    handler: (this: YargsCommandHandler & {
+        engine?: CLIEngine;
+        log?: (msg?: string, options?: any) => void;
+    }, argv: Parameters<YargsCommandModule['handler']>[0]) => ReturnType<YargsCommandModule['handler']>;
+    /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */
+    builder: (cli: CLIEngine) => CLIEngine | PromiseLike<CLIEngine>;
+    meta: Record<string, any>;
+};
+export type CLIBuilder = (cli: CLIEngine) => CLIEngine;
+/**
+ * Custom global command visitor callback.
+ */
+export type CommandVisitor = {
+    options?: Record<any, any>;
+} & ((
+/**
+ * The exported command object
+ */
+commandObject: CommandModule, 
+/**
+ * The current CLI instance
+ */
+engine: CLIEngine, 
+/**
+ * The default options to set
+ */
+options: any) => false | CommandModule);
+export {};

package/dist/cli/utils.d.ts

@@ -0,0 +1,19 @@
+import { CommandModule, CLIEngine } from './types';
+/**
+ * @ignore
+ * @param target - The target builder
+ * @param builder - The wrap
+ * @description
+ * Wrap command builder (target) with builder passed as second parameter
+ * that will be called before target. Target can be undefined
+ */
+export declare function wrapCommandBuilder(target: CommandModule['builder'], builder: (cli: CLIEngine) => CLIEngine): (cli: CLIEngine) => CLIEngine | PromiseLike<CLIEngine>;
+/**
+ * @ignore
+ * @param target - The target handler
+ * @param handler - The wrap
+ * @description
+ * Wrap command handler (target) with handler passed as second parameter
+ * that will be called before target. Target can be undefined
+ */
+export declare function wrapCommandhandler(target: CommandModule['handler'], handler: CommandModule['handler']): CommandModule["handler"];