juisy 2.0.0-beta.0 → 2.0.0-beta.8

package/bin/cli/cli.js

@@ -6,8 +6,8 @@ const { $style } = CLI.OutputUtils
 
 function getBanner () {
   let str = ''
-  const title = '@hperchec/juisy'
-  const length = title.length - 9 // removes characters generated by $style.bold from length
+  const title = 'juisy'
+  const length = title.length
   str += $style.cyan('-'.repeat(length) + '\n')
   str += $style.cyan(title + '\n')
   str += $style.cyan('-'.repeat(length) + '\n')
@@ -15,9 +15,11 @@ function getBanner () {
   return str
 }
 
-export default CLIFactory(cli => cli
+export default await CLIFactory(cli => cli
   .scriptName('juisy')
   .usage(`${getBanner()}\nUsage: $0 <command> [<options>]`)
+  .disableDefaultCommand('docs generate:api')
+  .globalCommandVisitorOptions('private-command-visitor', { envKey: '__JUISY_CLI_ENV__' })
   .command(commands)
-  .demandCommand(1, ('Command is missing. See help to learn more.').red)
+  // .demandCommand(1, ('Command is missing. See help to learn more.').red)
 )

package/bin/cli/cmds/index.js

@@ -1,15 +1,15 @@
-import docs from './docs/index.js'
-import eject from './eject.js'
-import gitHooks from './git-hooks/index.js'
-import printGlobals from './print-globals.js'
-import squeeze from './squeeze.js'
-import test from './test.js'
+// Private commands
+import docs from './private/docs/index.js'
+// import test from './private/test.js'
+// Public commands
+import printGlobals from './public/print-globals.js'
+import squeeze from './public/squeeze.js'
 
 export const commands = [
+  // Private
   docs,
-  eject,
-  gitHooks,
+  // test,
+  // Public
   printGlobals,
-  squeeze,
-  test
+  squeeze
 ]

package/bin/cli/cmds/private/docs/generate-api.js

@@ -0,0 +1,31 @@
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'generate:api',
+  describe: 'Generate API docs from source code',
+  builder (cli) {
+    cli
+  },
+  async handler (argv) {
+    // Utils
+    const { $style, step, substep } = CLI.OutputUtils
+    const { run } = CLI.InterfaceUtils
+
+    const config = (await import(pathToFileURL(path.resolve('./docs/api/docs.config.js')).toString())).default
+    // Process options
+    const typedocConfigPath = config.typedoc.configPath
+
+    /**
+     * Generate api documentation
+     */
+    step('Generating API documentation')
+
+    // Run typedoc command
+    await run('typedoc', [ '--options', typedocConfigPath ], { stdio: 'pipe' })
+
+    substep($style.green('✔ Successfuly generated'), { last: true })
+    this.log() // blank line
+  }
+})

package/bin/cli/cmds/{docs → private/docs}/index.js

@@ -1,6 +1,4 @@
 import generateAPI from './generate-api.js'
-import generateCLI from './generate-cli.js'
-import generateReadme from './generate-readme.js'
 
 /** @type {import('#juisy/cli').Command} */
 export default new CLI.Command({
@@ -12,11 +10,11 @@ export default new CLI.Command({
   builder (cli) {
     return cli
       .command([
-        generateAPI,
-        generateCLI,
-        generateReadme
+        /**
+         * Default command are automatically injected here...
+         */
+        generateAPI
       ])
-      .demandCommand(1, 'Command is missing. See help to learn more.')
   },
   handler (argv) {}
 })

package/bin/cli/cmds/{print-globals.js → public/print-globals.js}

@@ -4,7 +4,6 @@ import { getProjectGlobals, DataExporter } from '#juisy'
 export default new CLI.Command({
   command: 'print:globals',
   describe: 'Print the computed project globals as JSON',
-  meta: {},
   builder (cli) {
     cli.option('f', {
       alias: 'format',

package/bin/cli/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict'
 

package/bin/scripts/prepare.js

@@ -0,0 +1,22 @@
+import run from 'execa'
+
+/**
+ * Prepare script
+ */
+;(async function () {
+  console.log('Prepare packages/juisy')
+
+  // Copy env file
+  try {
+    await run('npx', [ 'cpy', '.env.example', '.', '--rename', '.env', '--no-overwrite' ], { stdio: 'inherit' })
+  } catch (e) {
+    console.error('✖ env file already exists. Ignoring step...')
+    console.log() // blank line
+  }
+  // Build juisy because we depend on CLI tools
+  await run('pnpm', [ 'build' ], { stdio: 'inherit' })
+
+  // Everything is okay
+  console.log('✔ Prepare script passed')
+  console.log() // blank line
+})()

package/dist/DataExporter.d.ts

@@ -2,7 +2,13 @@ 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"];
+/**
+ * @group Types
+ */
 export type DataExporterFormat = typeof SUPPORTED_FORMATS[number];
+/**
+ * @group Types
+ */
 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

package/dist/cli/CLIFactory.d.ts

@@ -1,19 +1,56 @@
-import { CLIBuilder } from './types';
+import { Plugin } from './Plugin';
+import { CLIFactoryOptions, CLIEngine, CLIBuilder, DefaultCommandObject } from './types';
+declare function defineDefaultCommand(command: DefaultCommandObject): void;
 /**
- * Creates a CLI factory (default: yargs instance)
- * @param  builder - The CLI builder function
+ * @private
+ */
+export declare const getDefaultCommand: (fullSignature: string) => DefaultCommandObject | undefined;
+type DefineSettingsOptions = {
+    /**
+     * Must return an object like:
+     * ```
+     * {
+     *   'lint': (settings) => {
+     *     // ...
+     *     return settings
+     *   }
+     * }
+     * ```
+     */
+    resolve?(settings: any): any;
+};
+declare function defineSettings(target: string, settings: any, options?: DefineSettingsOptions): void;
+/**
+ * @group Types
+ */
+export type PluginAPI = {
+    defineDefaultCommand: typeof defineDefaultCommand;
+    defineSettings: typeof defineSettings;
+    engine: CLIEngine;
+    builder: CLIBuilder;
+    factoryOptions: CLIFactoryOptions;
+};
+/**
+ * Creates a CLI factory. If `options.settingsPath` is not provided, it will try to find:
+ *
+ * - `dev.config.{ts,js,json}`
+ * - `cli.config.{ts,js,json}`
+ * - `.clirc.{ts,js,json}`
+ *
+ * @param builder - The CLI builder function
+ * @param options - The options object
+ * @param options.settingsPath - The path to CLI config file
  * @returns A function that takes optional argv as first parameter
  * @example
- * import { CLIFactory } from '@hperchec/juisy'
+ * import { CLIFactory } from 'juisy/cli'
  *
- * const cli = CLIFactory(cli => cli
+ * const cli = await 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;
+export declare function CLIFactory(builder: CLIBuilder, options?: CLIFactoryOptions): Promise<(argv?: typeof process.argv) => CLIEngine>;
+export declare namespace CLIFactory {
+    var use: (plugin: Plugin) => void;
+}
+export {};

package/dist/cli/Command.d.ts

@@ -1,15 +1,23 @@
-import { CommandModule } from './types';
+import { CommandObject } from './types';
+type CommandOptions = {
+    command: CommandObject['command'];
+    aliases?: CommandObject['aliases'];
+    describe?: CommandObject['describe'];
+    deprecated?: CommandObject['deprecated'];
+    builder?: CommandObject['builder'];
+    handler?: CommandObject['handler'];
+    middlewares?: CommandObject['middlewares'];
+    meta?: CommandObject['meta'];
+};
 /**
- * Class to wrap command definition (CommandModule)
+ * Class to wrap command definition (CommandObject)
  */
-export declare class Command implements CommandModule {
+export declare class Command implements CommandObject {
     /**
-     * Creates a Command instance from object (CommandModule)
-     * @param {CommandModule} commandObject - The command definition object
+     * Creates a Command instance from object (CommandObject)
+     * @param {CommandObject} commandObject - The command definition object
      */
-    constructor(commandObject: CommandModule & {
-        builder?: CommandModule['builder'];
-    });
+    constructor(commandObject: CommandOptions);
     /**
      * The command
      */
@@ -29,7 +37,7 @@ export declare class Command implements CommandModule {
     /**
      * Command meta
      */
-    meta: Record<string, any>;
+    meta: Partial<import('./types').CommandMeta> | undefined;
     /**
      * Command builder
      */
@@ -37,8 +45,10 @@ export declare class Command implements CommandModule {
     /**
      * 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"]>;
+    handler: import('./types').CommandHandler | undefined;
+    /**
+     * Command middlewares
+     */
+    middlewares: import('yargs').MiddlewareFunction[] | undefined;
 }
+export {};

package/dist/cli/GlobalSettings.schema.json

@@ -0,0 +1 @@
+{"$schema":"http://json-schema.org/draft-07/schema#","$ref":"#/definitions/GlobalSettings","definitions":{"GlobalSettings":{"type":"object","properties":{"release":{"$ref":"#/definitions/UserProvidedConfigSetting%3CReleaseIt.Config%3E","description":"Release configuration"}}},"UserProvidedConfigSetting<ReleaseIt.Config>":{"anyOf":[{"type":"object","properties":{"config":{"type":"string","description":"The configuration file path"}},"required":["config"]},{"type":"object","properties":{}}],"description":"Provide a configuration object or an object with only \"config\" property","examples":[{"config":"path/to/config/file"}]}}}

package/dist/cli/InterfaceUtils.d.ts

@@ -1,5 +1,10 @@
-import { default as execa } from 'execa';
+import { ExecaError } from 'execa';
 import { default as _prompts } from 'prompts';
+/**
+ * Command execution error thrown by execa
+ */
+export interface RunError extends ExecaError {
+}
 export declare class InterfaceUtils {
     /**
      * Get root directory path
@@ -13,13 +18,14 @@ export declare class InterfaceUtils {
      * @param {string[]} args - Same as execa second arg
      * @param {object} [opts] - Options
      * @returns {Promise<object>} The `execa` Promise
+     * @throws {RunError}
      * @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>;
+    static run(bin: string, args: string[], opts?: {}): import('execa').ExecaChildProcess<string>;
     /**
      * @alias utils.abort
      * @param {number} [code] - Code for process.exit() (default: 0)

package/dist/cli/OutputUtils.d.ts

@@ -19,7 +19,7 @@ export declare class OutputUtils {
         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";
+        Modifiers: "bold" | "hidden" | "reset" | "dim" | "italic" | "underline" | "inverse" | "strikethrough" | "visible";
         stderr: chalk.Chalk & {
             supportsColor: chalk.ColorSupport | false;
         };
@@ -68,7 +68,7 @@ export declare class OutputUtils {
     static warn(msg: string): void;
     /**
      * @param msg - The message to display
-     * @param {Error} [err] - If provided, throw the error
+     * @param err - If provided, throw the error
      * @description
      * Display error message. Throws `err` if provided.
      * @example
@@ -76,7 +76,7 @@ export declare class OutputUtils {
      * 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;
+    static error(msg: string, err?: Error): void;
     /**
      * Log step title
      * @param msg - The message to display

package/dist/cli/Plugin.d.ts

@@ -0,0 +1,21 @@
+import { PluginAPI } from './CLIFactory';
+type PluginObject = {
+    beforeCreate?: Plugin['beforeCreate'];
+    created?: Plugin['created'];
+};
+export declare class Plugin {
+    constructor(name: string, pluginObject: PluginObject);
+    /**
+     * The plugin unique name
+     */
+    name: string;
+    /**
+     * The beforeCreate hook (can be async)
+     */
+    beforeCreate: (context: Pick<PluginAPI, 'defineDefaultCommand' | 'defineSettings' | 'builder' | 'factoryOptions'>) => Promise<any> | any;
+    /**
+     * The created hook (must be sync)
+     */
+    created: (context: Pick<PluginAPI, 'engine' | 'builder' | 'factoryOptions'>) => any;
+}
+export {};

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

@@ -1,5 +1,8 @@
 import { CLIEngine } from './types';
 import { CLIFactory } from './CLIFactory';
+/**
+ * @group Types
+ */
 export type CommandDoclet = {
     /**
      * The command
@@ -31,6 +34,9 @@ export type CommandDoclet = {
      */
     children: Record<string, ExtractedUsage> | undefined;
 };
+/**
+ * @group Types
+ */
 export type ExtractedUsage = {
     /**
      * Same as yargs instance `getDemandedCommands` method
@@ -69,4 +75,4 @@ export type ExtractedUsage = {
         deprecated: boolean;
     }>;
 };
-export declare function extractUsage(factory: ReturnType<typeof CLIFactory>, recursive?: boolean, args?: string[], locale?: string): Promise<CommandDoclet>;
+export declare function extractUsage(factory: Awaited<ReturnType<typeof CLIFactory>>, recursive?: boolean, args?: string[], locale?: string): Promise<CommandDoclet>;

package/dist/cli/index.d.ts

@@ -2,12 +2,6 @@ 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: {
@@ -18,3 +12,21 @@ declare global {
         OutputUtils: typeof OutputUtils;
     };
 }
+export { CLIFactory } from './CLIFactory';
+export * from './Command';
+export * from './InterfaceUtils';
+export * from './OutputUtils';
+export { extractUsage } from './extract-usage';
+export type * from './CLIFactory';
+export type * from './extract-usage';
+export type * from './types';
+export type * from './plugins/load-env-file/augment';
+export type * from './plugins/register-changelog-command/augment';
+export type * from './plugins/register-docs-commands/augment';
+export type * from './plugins/register-git-hooks-commands/augment';
+export type * from './plugins/register-lint-commands/augment';
+export type * from './plugins/register-release-command/augment';
+export type * from './plugins/default-command-fallbacks/augment';
+export type * from './plugins/command-handler-injections/augment';
+export type * from './plugins/command-meta/augment';
+export type * from './plugins/private-commands/augment';