juisy 2.0.0-beta.0

package/bin/scripts/commit-msg.js

@@ -0,0 +1,32 @@
+import run from 'execa'
+/**
+ * commit-msg git hook
+ */
+;(async function () {
+  console.log('Git hook: commit-msg')
+
+  // Get git commit msg path from args
+  const args = process.argv.slice(2)
+  const gitMsgPath = args[0]
+
+  try {
+    // original is: npx --no -- commitlint --edit ${1}
+    // we replace "${1}" by gitMsgPath arg
+    await run('npx', [
+      '--no',
+      '--',
+      'commitlint',
+      '--edit',
+      gitMsgPath
+    ])
+  } catch (e) {
+    console.error('❌ Git hook: "commit-msg" failed. Please check ./COMMIT_CONVENTION.md for more informations.', e)
+    console.log() // blank line
+    process.exit(1) // Abort with error
+  }
+
+  // Everything is okay
+  console.log('✔ Git hook: "commit-msg" passed')
+
+  console.log() // blank line
+})()

package/bin/scripts/pre-commit.js

@@ -0,0 +1,24 @@
+import run from 'execa'
+
+/**
+ * Pre commit git hook
+ */
+;(async function () {
+  console.log('Git hook: pre-commit')
+
+  try {
+    // npx lint-staged
+    await run('npx', [
+      'lint-staged'
+    ], { stdio: 'pipe' })
+  } catch (e) {
+    console.error('Git hook: "commit-msg" error: ', e)
+    console.log() // blank line
+    process.exit(1)
+  }
+
+  // Everything is okay
+  console.log('✔ Git hook: "pre-commit" passed')
+
+  console.log() // blank line
+})()

package/dist/DataExporter.d.ts

@@ -0,0 +1,67 @@
+import { default as yaml } from 'yaml';
+import { Json2CsvOptions } from 'json-2-csv';
+import { Options as XMLoptions } from 'jstoxml';
+declare const SUPPORTED_FORMATS: readonly ["json", "yaml", "csv", "xml"];
+export type DataExporterFormat = typeof SUPPORTED_FORMATS[number];
+export type ExportOptions<F extends DataExporterFormat> = F extends 'json' ? Parameters<typeof jsonExporter>[1] : F extends 'yaml' ? Parameters<typeof yamlExporter>[1] : F extends 'csv' ? Parameters<typeof csvExporter>[1] : F extends 'xml' ? Parameters<typeof xmlExporter>[1] : {};
+/**
+ * JSON exporter
+ * @param data - The data object
+ * @param options - Specific JSON exporter options
+ * @returns The data as JSON string
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+ */
+declare const jsonExporter: (data: any, options?: {
+    replacer?: Parameters<typeof JSON.stringify>[1];
+    space?: Parameters<typeof JSON.stringify>[2];
+}) => string;
+/**
+ * YAML exporter
+ * @param data - The data object
+ * @param options - Specific YAML exporter options
+ * @returns The data as YAML string
+ * @see https://www.npmjs.com/package/yaml
+ * @see https://eemeli.org/yaml/#yaml
+ */
+declare const yamlExporter: (data: any, options?: {
+    replacer?: Parameters<typeof yaml.stringify>[1];
+    exporter?: Parameters<typeof yaml.stringify>[2];
+}) => string;
+/**
+ * CSV exporter
+ * @param data - The data object
+ * @param options - Specific CSV exporter options
+ * @returns The data as CSV string
+ * @see https://www.npmjs.com/package/json-2-csv
+ * @see https://mrodrig.github.io/json-2-csv/
+ */
+declare const csvExporter: (data: any, options: Json2CsvOptions) => string;
+/**
+ * XML exporter
+ * @param data - The data object
+ * @param options - Specific XML exporter options
+ * @returns The data as XML string
+ * @see https://www.npmjs.com/package/jstoxml
+ * @see https://github.com/davidcalhoun/jstoxml
+ */
+declare const xmlExporter: (data: any, options: XMLoptions) => string;
+/**
+ * Universal data exporter
+ */
+export declare class DataExporter {
+    /**
+     * The target format
+     */
+    private format;
+    /**
+     * Creates new instance of Costume
+     * @param options - Costume options
+     */
+    constructor(format: DataExporterFormat);
+    exportSync(data: any, options?: ExportOptions<'json'>): ReturnType<typeof jsonExporter>;
+    exportSync(data: any, options?: ExportOptions<'yaml'>): ReturnType<typeof yamlExporter>;
+    exportSync(data: any, options?: ExportOptions<'csv'>): ReturnType<typeof csvExporter>;
+    exportSync(data: any, options?: ExportOptions<'xml'>): ReturnType<typeof xmlExporter>;
+    export(...args: Parameters<typeof this.exportSync>): Promise<ReturnType<typeof this.exportSync>>;
+}
+export {};

package/dist/cli/CLIFactory.d.ts

@@ -0,0 +1,19 @@
+import { CLIBuilder } from './types';
+/**
+ * Creates a CLI factory (default: yargs instance)
+ * @param  builder - The CLI builder function
+ * @returns A function that takes optional argv as first parameter
+ * @example
+ * import { CLIFactory } from '@hperchec/juisy'
+ *
+ * const cli = CLIFactory(cli => cli
+ *   .scriptName('my-juicy-cli')
+ *   .usage('Usage: $0 <command> [<options>]')
+ * )
+ *
+ * const argv = process.argv.slice(2)
+ *
+ * // Parse argv
+ * cli().parse(argv)
+ */
+export declare function CLIFactory(builder: CLIBuilder): (argv: typeof process.argv) => import('./types').CLIEngine;

package/dist/cli/Command.d.ts

@@ -0,0 +1,44 @@
+import { CommandModule } from './types';
+/**
+ * Class to wrap command definition (CommandModule)
+ */
+export declare class Command implements CommandModule {
+    /**
+     * Creates a Command instance from object (CommandModule)
+     * @param {CommandModule} commandObject - The command definition object
+     */
+    constructor(commandObject: CommandModule & {
+        builder?: CommandModule['builder'];
+    });
+    /**
+     * The command
+     */
+    command: string | readonly string[] | undefined;
+    /**
+     * The aliases
+     */
+    aliases: string | readonly string[] | undefined;
+    /**
+     * Command description
+     */
+    describe: string | false | undefined;
+    /**
+     * Is deprecated?
+     */
+    deprecated: string | boolean | undefined;
+    /**
+     * Command meta
+     */
+    meta: Record<string, any>;
+    /**
+     * Command builder
+     */
+    builder: (cli: import('./types').CLIEngine) => import('./types').CLIEngine | PromiseLike<import('./types').CLIEngine>;
+    /**
+     * Command handler
+     */
+    handler: (this: import('./types').YargsCommandHandler & {
+        engine?: import('./types').CLIEngine;
+        log?: (msg?: string, options?: any) => void;
+    }, argv: Parameters<import('yargs').CommandModule["handler"]>[0]) => ReturnType<import('yargs').CommandModule["handler"]>;
+}

package/dist/cli/InterfaceUtils.d.ts

@@ -0,0 +1,53 @@
+import { default as execa } from 'execa';
+import { default as _prompts } from 'prompts';
+export declare class InterfaceUtils {
+    /**
+     * Get root directory path
+     * @example
+     * import { CLIUtils: { rootDir } } from '@hperchec/juisy'
+     * console.log(rootDir) // => 'path/to/your/root/dir'
+     */
+    static rootDir: string;
+    /**
+     * @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: string, args: string[], opts?: {}): execa.ExecaChildProcess<string>;
+    /**
+     * @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?: number): void;
+    /**
+     * @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 confirm(question: _prompts.PromptObject): Promise<true | undefined>;
+    /**
+     * See `prompts` package documentation
+     * @example
+     * const { prompts } = InterfaceUtils
+     * // See prompts documentation
+     * @see https://www.npmjs.com/package/prompts
+     */
+    static prompts: typeof _prompts;
+}

package/dist/cli/OutputUtils.d.ts

@@ -0,0 +1,123 @@
+import { default as chalk } from 'chalk';
+import { default as indent } from 'indent-string';
+import { default as _stripAnsi } from 'strip-ansi';
+export declare class OutputUtils {
+    /**
+     * To automatically increment step index
+     * @ignore
+     */
+    private static stepsCache;
+    /**
+     * 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.Chalk & chalk.ChalkFunction & {
+        supportsColor: chalk.ColorSupport | false;
+        Level: chalk.Level;
+        Color: ("black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright") | ("bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "bgWhite" | "bgGray" | "bgGrey" | "bgBlackBright" | "bgRedBright" | "bgGreenBright" | "bgYellowBright" | "bgBlueBright" | "bgMagentaBright" | "bgCyanBright" | "bgWhiteBright");
+        ForegroundColor: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright";
+        BackgroundColor: "bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "bgWhite" | "bgGray" | "bgGrey" | "bgBlackBright" | "bgRedBright" | "bgGreenBright" | "bgYellowBright" | "bgBlueBright" | "bgMagentaBright" | "bgCyanBright" | "bgWhiteBright";
+        Modifiers: "bold" | "reset" | "dim" | "italic" | "underline" | "inverse" | "hidden" | "strikethrough" | "visible";
+        stderr: chalk.Chalk & {
+            supportsColor: chalk.ColorSupport | false;
+        };
+    };
+    /**
+     * 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: string, options?: {
+        indent?: Parameters<typeof indent>[1];
+        indentChar?: string;
+    }): string;
+    /**
+     * @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?: string, options?: Parameters<typeof this.formatOutputMessage>[1] & {
+        loggerInstance?: {
+            log: Function;
+        };
+    }): void;
+    /**
+     * 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: string): void;
+    /**
+     * @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: string, err?: undefined): void;
+    /**
+     * 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: string, options?: {
+        index?: number | string;
+    }): void;
+    /**
+     * 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: string, options?: {
+        last?: boolean;
+    }): void;
+    /**
+     * @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 wait(message: string, fct: () => PromiseLike<void>): Promise<void>;
+    /**
+     * See `strip-ansi` package documentation
+     * @see https://www.npmjs.com/package/strip-ansi
+     */
+    static stripAnsi: typeof _stripAnsi;
+}

package/dist/cli/command-visitors/command-handler-injections.d.ts

@@ -0,0 +1,10 @@
+import { CommandVisitor } from '../types';
+/**
+ * Global command visitor to auto-set command meta
+ * @ignore
+ * @param commandObject - The command object
+ * @param cli - The CLIEngine instance
+ * @returns The commandObject with wrapped handler to inject properties.
+ */
+export declare const visitor: CommandVisitor;
+export declare const options: {};

package/dist/cli/command-visitors/get-command-meta.d.ts

@@ -0,0 +1,10 @@
+import { CommandVisitor } from '../types';
+/**
+ * Global command visitor to auto-set command meta
+ * @ignore
+ * @param commandObject - The command object
+ * @param cli - The CLIEngine instance
+ * @returns The commandObject with wrapped builder to inject CLI instance meta.
+ */
+export declare const visitor: CommandVisitor;
+export declare const options: {};

package/dist/cli/command-visitors/index.d.ts

@@ -0,0 +1,9 @@
+import * as commandHandlerInjections from './command-handler-injections';
+import * as getCommandMeta from './get-command-meta';
+import * as privateCommand from './private-command';
+declare const _default: {
+    commandHandlerInjections: typeof commandHandlerInjections;
+    getCommandMeta: typeof getCommandMeta;
+    privateCommand: typeof privateCommand;
+};
+export default _default;

package/dist/cli/command-visitors/private-command.d.ts

@@ -0,0 +1,16 @@
+import { CommandVisitor } from '../types';
+/**
+ * @ignore
+ * @param commandModule - The exported command object
+ * @param engine - The CLI (yargs) instance
+ * @param options - The global command visitor defined options
+ * @returns {object|boolean} False if command is private and env key is set to "private".
+ * Otherwise, returns the commandModule with wrapped builder to tag CLI instance as private.
+ * @description
+ * Global command visitor to auto-set command private status
+ */
+export declare const visitor: CommandVisitor;
+export declare const options: {
+    metaProp: string;
+    envKey: string;
+};

package/dist/cli/create-engine.d.ts

@@ -0,0 +1,7 @@
+import { Argv } from 'yargs';
+import { CLIEngine } from './types';
+/**
+ * @ignore
+ * @param yargs - The Yargs instance
+ */
+export declare function createEngine(yargs: Argv): CLIEngine;

package/dist/cli/extract-usage.d.ts

@@ -0,0 +1,72 @@
+import { CLIEngine } from './types';
+import { CLIFactory } from './CLIFactory';
+export type CommandDoclet = {
+    /**
+     * The command
+     */
+    command: string | undefined;
+    /**
+     * The command args
+     */
+    args: string[] | undefined;
+    /**
+     * The yargs instance `aliasMap` reference
+     * @todo Declare type?
+     */
+    aliases: unknown;
+    /**
+     * If command is deprecated
+     */
+    deprecated: boolean;
+    /**
+     * The extracted usage object from yargs usage instance
+     */
+    extractedUsage: ExtractedUsage | undefined;
+    /**
+     * The usage output as string (as if `--help` option passed)
+     */
+    rawUsage: string | undefined;
+    /**
+     * The child commands
+     */
+    children: Record<string, ExtractedUsage> | undefined;
+};
+export type ExtractedUsage = {
+    /**
+     * Same as yargs instance `getDemandedCommands` method
+     */
+    demandedCommands: ReturnType<CLIEngine['getDemandedCommands']>;
+    /**
+     * Same as yargs instance `getDemandedOptions` method
+     */
+    demandedOptions: ReturnType<CLIEngine['getDemandedOptions']>;
+    /**
+     * Same as yargs instance `getDeprecatedOptions` method
+     */
+    deprecatedOptions: ReturnType<CLIEngine['getDeprecatedOptions']>;
+    /**
+     * Same as yargs instance `getGroups` method
+     */
+    groups: ReturnType<CLIEngine['getGroups']>;
+    /**
+     * Same as yargs instance `getOptions` method
+     */
+    options: ReturnType<CLIEngine['getOptions']>;
+    /**
+     * Same as yargs usage instance `getUsage` method
+     */
+    usages: [string, string][];
+    /**
+     * The result of yargs usage instance `getCommands` method as object.
+     * While the UsageInstance commands items are defined as follow: `[cmd, description, isDefault, aliases, deprecated]`,
+     * we cast it to an object like: `{cmd, description, isDefault, aliases, deprecated}`.
+     */
+    commands: Record<string, {
+        cmd: string;
+        description: string;
+        isDefault: boolean;
+        aliases: string[];
+        deprecated: boolean;
+    }>;
+};
+export declare function extractUsage(factory: ReturnType<typeof CLIFactory>, recursive?: boolean, args?: string[], locale?: string): Promise<CommandDoclet>;

package/dist/cli/index.d.ts

@@ -0,0 +1,20 @@
+import { hideBin } from 'yargs/helpers';
+import { Command } from './Command';
+import { InterfaceUtils } from './InterfaceUtils';
+import { OutputUtils } from './OutputUtils';
+export * from './CLIFactory';
+export * from './Command';
+export * from './InterfaceUtils';
+export * from './OutputUtils';
+export { extractUsage } from './extract-usage';
+export type * from './types';
+declare global {
+    var CLI: {
+        helpers: {
+            hideBin: typeof hideBin;
+        };
+        Command: typeof Command;
+        InterfaceUtils: typeof InterfaceUtils;
+        OutputUtils: typeof OutputUtils;
+    };
+}