docs for libs and utils

Author: AaronFeledy

lib/cli.js

@@ -11,6 +11,80 @@ const EOL = os.EOL;
 const formatters = require('./formatters');
 const getSysDataPath = require('../utils/get-system-data-dir');
 
+/**
+ * @typedef {import('chalk').Chalk} Chalk
+ * @typedef {import('inquirer')} Inquirer
+ * @typedef {import('yargs')} YargsInstance
+ * @typedef {import('yargs').Arguments} Arguments
+ * @typedef {import('yargs').CommandModule} CommandModule
+ * @typedef {import('yargs').Options} Options
+ * @typedef {import('yargs').ParserConfigurationOptions} ParserConfigurationOptions
+ * @typedef {import('yargs').BuilderCallback} BuilderCallback
+ */
+
+/**
+ * @typedef {Object} GlobalOptions
+ * @property {Object} channel - Channel option configuration
+ * @property {string} channel.describe - Option description
+ * @property {string[]} channel.choices - Valid channel choices
+ * @property {boolean} channel.global - Whether option is global
+ * @property {string} channel.type - Option type
+ * @property {Object} clear - Clear option configuration
+ * @property {string} clear.describe - Option description
+ * @property {boolean} clear.global - Whether option is global
+ * @property {string} clear.type - Option type
+ * @property {Object} debug - Debug option configuration
+ * @property {string} debug.describe - Option description
+ * @property {boolean} debug.global - Whether option is global
+ * @property {string} debug.type - Option type
+ * @property {Object} experimental - Experimental option configuration
+ * @property {string} experimental.describe - Option description
+ * @property {boolean} experimental.global - Whether option is global
+ * @property {boolean} experimental.hidden - Whether option is hidden
+ * @property {string} experimental.type - Option type
+ * @property {Object} help - Help option configuration
+ * @property {string} help.describe - Option description
+ * @property {string} help.type - Option type
+ * @property {Object} lando - Lando option configuration
+ * @property {boolean} lando.hidden - Whether option is hidden
+ * @property {string} lando.type - Option type
+ * @property {Object} verbose - Verbose option configuration
+ * @property {string} verbose.alias - Option alias
+ * @property {string} verbose.describe - Option description
+ * @property {string} verbose.type - Option type
+ */
+
+/**
+ * @typedef {Object} TaskConfig
+ * @property {string} [command] - Command name
+ * @property {string} [describe] - Command description
+ * @property {Array<string|Array>} [examples] - Command examples
+ * @property {string} [file] - Path to task file
+ * @property {Options} [options] - Command options
+ * @property {Object} [positionals] - Command positional arguments
+ * @property {Function|Object} [run] - Command run function
+ * @property {string} [level='app'] - Command level
+ * @property {string} [usage] - Command usage
+ */
+
+/**
+ * @typedef {Object} CliConfig
+ * @property {string} [prefix='LANDO'] - Environment variable prefix
+ * @property {string} [logLevel='warn'] - Default log level
+ * @property {string} [userConfRoot='~/.lando'] - Path to user config directory
+ * @property {string} [coreBase='../'] - Path to Lando core base directory
+ * @property {Function} [debug=require('debug')('@lando/cli')] - Debug function
+ */
+
+/**
+ * @typedef {Object} ErrorHandler
+ * @property {(error: Error & {verbose?: number}, reportErrors?: boolean) => Promise<number>} handle - Handles an error and returns exit code
+ */
+
+/**
+ * @typedef {Error & {verbose?: number}} LandoError
+ */
+
 // Global options
 const globalOptions = {
   channel: {
@@ -50,17 +124,42 @@ const globalOptions = {
   },
 };
 
-/*
- * Construct the CLI
+/**
+ * The CLI class provides command line interface functionality for Lando
+ *
+ * This class handles command line argument parsing, task management, and user interaction
+ * for the Lando CLI. It integrates with the core Lando system to provide a complete
+ * command line interface.
+ *
+ * @since 3.0.0
+ * @class
+ * @memberof module:Lando
+ * @property {string} prefix - Environment variable prefix for CLI
+ * @property {string} logLevel - Default log level
+ * @property {string} userConfRoot - Path to user config directory
+ * @property {string} coreBase - Path to Lando core base directory
+ * @property {Function} debug - Debug logging function
+ * @property {Chalk} chalk - Chalk instance for terminal coloring
+ * @property {Arguments} argv Parsed CLI arguments
+ * @property {Function} checkPerms Checks if Lando is running with sudo
+ * @property {Function} clearTaskCaches Clears the Lando task caches
+ * @property {Function} confirm Creates a confirmation prompt configuration
+ * @property {Function} defaultConfig Returns default configuration for CLI bootstrap
+ * @property {Function} formatData Formats data for CLI output
+ * @property {Function} formatOptions Gets CLI options formatting
  */
-module.exports = class Cli {
-  constructor(
+class Cli {
+  /**
+   * Creates a new CLI instance
+   * @param {CliConfig} config - CLI configuration options
+   */
+  constructor({
     prefix = 'LANDO',
     logLevel = 'warn',
     userConfRoot = path.join(os.homedir(), '.lando'),
     coreBase = path.resolve(__dirname, '..'),
     debug = require('debug')('@lando/cli'),
-  ) {
+  } = {}) {
     this.prefix = prefix;
     this.logLevel = logLevel;
     this.userConfRoot = userConfRoot;
@@ -74,7 +173,7 @@ module.exports = class Cli {
    *
    * @since 3.0.0
    * @alias lando.cli.argv
-   * @return {Object} Yarg parsed options
+   * @return {Arguments} Yargs parsed command line arguments
    * @example
    * const argv = lando.cli.argv();
    * @todo make this static and then fix all call sites
@@ -84,29 +183,35 @@ module.exports = class Cli {
   }
 
   /**
-   * Checks to see if lando is running with sudo. If it is it
-   * will exit the process with a stern warning
+   * Checks if Lando is running with sudo and exits if true
    *
    * @since 3.0.0
    * @alias lando.cli.checkPerms
    * @example
    * lando.cli.checkPerms()
+   * @throws {Error} If Lando is running with sudo
    */
   checkPerms() {
     const sudoBlock = require('sudo-block');
     sudoBlock(this.makeArt('sudoRun'));
   }
 
-  /*
-   * Toggle the secret toggle
+  /**
+   * Clears the Lando task caches
+   * @private
    */
   clearTaskCaches() {
-    if (fs.existsSync(process.landoTaskCacheFile)) fs.unlinkSync(process.landoTaskCacheFile);
-    if (fs.existsSync(process.landoAppCacheFile)) fs.unlinkSync(process.landoAppCacheFile);
+    const taskCacheFile = process.env.LANDO_TASK_CACHE_FILE;
+    const appCacheFile = process.env.LANDO_APP_CACHE_FILE;
+    if (taskCacheFile && fs.existsSync(taskCacheFile)) fs.unlinkSync(taskCacheFile);
+    if (appCacheFile && fs.existsSync(appCacheFile)) fs.unlinkSync(appCacheFile);
   }
 
-  /*
-   * Confirm question
+  /**
+   * Creates a confirmation prompt configuration
+   *
+   * @param {string} [message='Are you sure?'] Prompt message
+   * @return {Object} Inquirer prompt configuration
    */
   confirm(message = 'Are you sure?') {
     return {
@@ -123,13 +228,12 @@ module.exports = class Cli {
   }
 
   /**
-   * Returns a config object with some good default settings for bootstrapping
-   * lando as a command line interface
+   * Returns default configuration for CLI bootstrap
    *
    * @since 3.5.0
    * @alias lando.cli.defaultConfig
    * @param {Object} [appConfig={}] Optional raw landofile
-   * @return {Object} Config that can be used in a Lando CLI bootstrap
+   * @return {Object} CLI bootstrap configuration
    * @example
    * const config = lando.cli.defaultConfig();
    * // Kick off our bootstrap
@@ -218,44 +322,70 @@ module.exports = class Cli {
     return config;
   }
 
-  /*
-   * Format data
+  /**
+   * Formats data for CLI output
+   *
+   * @param {*} data Data to format
+   * @param {Object} [options] Format options
+   * @param {string} [options.path=''] Path to data property
+   * @param {string} [options.format='default'] Output format
+   * @param {Array} [options.filter=[]] Properties to filter
+   * @param {Object} [opts={}] Additional formatting options
+   * @return {string} Formatted output
    */
   formatData(data, {path = '', format = 'default', filter = []} = {}, opts = {}) {
     return formatters.formatData(data, {path, format, filter}, opts);
   }
 
-  /*
-   * FormatOptios
+  /**
+   * Gets CLI options formatting
+   *
+   * @param {Array} [omit=[]] Options to omit
+   * @return {Object} Formatted options
    */
   formatOptions(omit = []) {
     return formatters.formatOptions(omit);
   }
 
+  /**
+   * Gets Inquirer instance for prompts
+   *
+   * @return {Inquirer} Inquirer instance
+   */
   getInquirer() {
     return require('inquirer');
   }
 
+  /**
+   * Gets oclif UX instance
+   *
+   * @return {Object} oclif UX instance
+   */
   getUX() {
     return require('@oclif/core').ux;
   }
 
+  /**
+   * Checks if debug mode is enabled
+   *
+   * @return {number} Debug level
+   */
   isDebug() {
     const {debug, verbose} = this.argv();
     return debug ? 1 + verbose : 0 + verbose;
   }
 
   /**
-   * Cli wrapper for error handler
+   * Handles CLI errors
    *
    * @since 3.0.0
    * @alias lando.cli.handleError
-   * @param {Error} error The error
-   * @param {Function} handler The error handler function
-   * @param {Integer} verbose [verbose=this.argv().verbose] The verbosity level
-   * @param {Object} lando The Lando object
-   * @param {Boolean} yes [yes=this.argv().yes] The auto yes value
-   * @return {Integer} The exit codes
+   * @param {LandoError} error Error object
+   * @param {ErrorHandler} handler Error handler
+   * @param {number} [verbose=this.argv().verbose] Verbosity level
+   * @param {Object} [lando={}] Lando instance
+   * @param {boolean} [yes=this.argv().yes] Auto-confirm prompts
+   * @return {Promise<number>} Exit code
    */
   handleError(error, handler, verbose = this.argv().verbose, lando = {}, yes = this.argv().yes) {
     // Set the verbosity
@@ -289,8 +419,13 @@ module.exports = class Cli {
     .then(() => handler.handle(error, lando.cache.get('report_errors')).then(code => process.exit(code)));
   }
 
-  /*
-   * Init
+  /**
+   * Initializes the CLI with tasks and configuration
+   *
+   * @param {YargsInstance} yargs Yargs instance
+   * @param {Array<CommandModule>} tasks CLI tasks
+   * @param {Object} config Lando configuration
+   * @param {Object} [userConfig={}] User configuration
    */
   init(yargs, tasks, config, userConfig = {}) {
     // if we have LANDO_ENTRYPOINT_NAME
@@ -351,15 +486,14 @@ module.exports = class Cli {
     yargs.argv;
   }
 
-
   /**
-   * Returns some cli "art"
+   * Generates CLI art
    *
    * @since 3.0.0
    * @alias lando.cli.makeArt
-   * @param {String} [func='start'] The art func you want to call
-   * @param {Object} [opts] Func options
-   * @return {String} Usually a printable string
+   * @param {string} func Art function to call
+   * @param {Object} [opts] Function options
+   * @return {string} Generated art
    * @example
    * console.log(lando.cli.makeArt('secretToggle', true);
    */
@@ -368,18 +502,18 @@ module.exports = class Cli {
   }
 
   /**
-   * Parses a lando task object into something that can be used by the [yargs](http://yargs.js.org/docs/) CLI.
+   * Parses a Lando task into Yargs command format
    *
    * A lando task object is an abstraction on top of yargs that also contains some
    * metadata about how to interactively ask questions on both a CLI and GUI.
    *
    * @since 3.5.0
    * @alias lando.cli.parseToYargs
-   * @see [yargs docs](http://yargs.js.org/docs/)
-   * @see [inquirer docs](https://github.com/sboudrias/Inquirer.js)
-   * @param {Object} task A Lando task object (@see add for definition)
-   * @param {Object} [config={}] The landofile
-   * @return {Object} A yargs command object
+   * @param {TaskConfig} task - Lando task configuration
+   * @param {Object} [config={}] - Lando configuration
+   * @return {CommandModule} Yargs command object
+   * @see {@link http://yargs.js.org/docs/|Yargs}
+   * @see {@link https://github.com/sboudrias/Inquirer.js|Inquirer.js}
    * @example
    * // Add a task to the yargs CLI
    * yargs.command(lando.tasks.parseToYargs(task));
@@ -502,12 +636,23 @@ module.exports = class Cli {
     }};
   }
 
+  /**
+   * Prettifies data for CLI output
+   *
+   * @param {*} data Data to prettify
+   * @param {Object} [options] Prettify options
+   * @param {string} [options.arraySeparator=', '] Separator for arrays
+   * @return {string} Prettified output
+   */
   prettify(data, {arraySeparator = ', '} = {}) {
     return require('../utils/prettify')(data, {arraySeparator});
   }
 
-  /*
-   * Run the CLI
+  /**
+   * Runs the CLI
+   *
+   * @param {Array<CommandModule>} [tasks=[]] CLI tasks
+   * @param {Object} [config={}] Lando configuration
    */
   run(tasks = [], config = {}) {
     const yargonaut = require('yargonaut');
@@ -551,8 +696,11 @@ module.exports = class Cli {
     this.init(yargs, tasks, config, userConfig);
   }
 
-  /*
-   * Toggle a toggle
+  /**
+   * Updates user configuration
+   *
+   * @param {Object} [data={}] Configuration updates
+   * @return {Object} Updated configuration
    */
   updateUserConfig(data = {}) {
     const Yaml = require(`../lib/yaml`);
@@ -562,4 +710,6 @@ module.exports = class Cli {
     const file = yaml.dump(configFile, _.assign({}, config, data));
     return yaml.load(file);
   }
-};
+}
+
+module.exports = Cli;