docs for libs and utils

Author: AaronFeledy

lib/lando.js

@@ -1,5 +1,110 @@
 'use strict';
 
+/**
+ * @typedef {import('./cache')} Cache
+ * @typedef {import('./cli')} Cli
+ * @typedef {import('./events')} AsyncEvents
+ * @typedef {import('bluebird')} Bluebird
+ * @typedef {Object} Debugger
+ * @property {(formatter: any, ...args: any[]) => void} __call - Debug function that logs messages
+ * @property {() => Debugger} contract - Returns a new debugger instance with the same namespace
+ * @property {() => Debugger} replace - Returns a new debugger instance replacing the current one
+ * @property {(name: string) => Debugger & {(formatter: any, ...args: any[]): void}} extend - Creates a new debugger with an extended namespace
+ * @property {string} color - ANSI color code for console output
+ * @property {number} diff - Time difference for timing operations
+ * @property {boolean} enabled - Whether debug output is enabled
+ * @property {(...args: any[]) => any} log - Raw logging function
+ * @property {string} namespace - Debug namespace identifier
+ * @property {() => void | boolean} destroy - Cleanup function for debugger instance
+ */
+
+/**
+ * @typedef {Object} LandoConfig
+ * @property {string|number} logLevelConsole - Log level for console output
+ * @property {string} userAgent - User agent string
+ * @property {string} channel - Update channel
+ * @property {Object} cli - CLI configuration
+ * @property {string} pluginConfigFile - Path to plugin config file
+ * @property {Object} pluginConfig - Plugin configuration
+ * @property {boolean} isInteractive - Whether running in interactive mode
+ * @property {string} caCert - Path to CA certificate
+ * @property {string} caKey - Path to CA private key
+ * @property {string} userConfRoot - Path to user config directory
+ * @property {Array<{path: string, type: string, dir?: string}>} pluginDirs - Plugin directories
+ * @property {string[]} preLandoFiles - Pre-lando configuration files
+ * @property {string} landoFile - Main lando configuration file
+ * @property {string[]} postLandoFiles - Post-lando configuration files
+ * @property {Object} setup - Setup configuration
+ */
+
+/**
+ * @typedef {Object} DebugShim
+ * @property {(...args: any[]) => void} debug - Debug logging function
+ * @property {() => any} contract - Contract function
+ * @property {() => any} replace - Replace function
+ * @property {(name: string) => any} extend - Extend function
+ * @property {string} [color] - Color property
+ * @property {boolean} [diff] - Diff property
+ * @property {boolean} [enabled] - Enabled property
+ * @property {Function} [log] - Log function
+ */
+
+/**
+ * @typedef {Object} LandoOptions
+ * @property {string} [logLevelConsole] - Log level for console output
+ * @property {string} [userConfRoot] - Path to user config directory
+ * @property {string} [envPrefix] - Environment variable prefix
+ * @property {Object[]} [configSources] - Config source definitions
+ * @property {string[]} [pluginDirs] - Directories to scan for plugins
+ * @property {string} [mode='cli'] - Operating mode
+ */
+
+/**
+ * @typedef {Object} SetupResults
+ * @property {Array<Error>} errors - Setup errors
+ * @property {Array<Object>} results - Setup results
+ * @property {boolean} restart - Whether restart is needed
+ * @property {number} total - Total number of operations
+ */
+
+/**
+ * @typedef {Object} PluginStatus
+ * @property {string} description - Plugin description
+ * @property {string} state - Current state (INSTALLED|NOT INSTALLED|CANNOT INSTALL)
+ * @property {string} version - Plugin version
+ * @property {string} [comment] - Additional status details
+ */
+
+/**
+ * @typedef {Object} TaskResults
+ * @property {Object} data - Raw task data
+ * @property {Array<Error>} errors - Task errors
+ * @property {Array<Object>} results - Task results
+ * @property {number} total - Total number of tasks processed
+ * @property {number} [skipped] - Number of skipped tasks
+ * @property {number} [ran] - Number of tasks that ran
+ */
+
+/**
+ * @typedef {Object} TaskRunnerOptions
+ * @property {string} [renderer='simple'] - Progress renderer to use
+ * @property {Object} [rendererOptions] - Options for the renderer
+ * @property {boolean} [concurrent] - Whether to run tasks concurrently
+ * @property {boolean} [exitOnError] - Whether to exit on first error
+ * @property {string} [debug] - Debug renderer to use
+ * @property {string} [fallbackRenderer] - Fallback renderer if primary fails
+ * @property {boolean} [rendererForce] - Force use of specified renderer
+ */
+
+/**
+ * @typedef {Object} UpdateManagerOptions
+ * @property {string} [agent] - User agent string
+ * @property {string} [channel] - Update channel
+ * @property {Object} [cli] - CLI configuration
+ * @property {Object} [config] - Plugin configuration
+ * @property {any} [debug] - Debug logger
+ */
+
 const _ = require('lodash');
 const fs = require('fs');
 const glob = require('glob');
@@ -170,63 +275,78 @@ const bootstrapRouter = async (level, lando) => {
 };
 
 /**
- * The class to instantiate a new Lando
+ * The Lando class provides core functionality for the Lando framework
  *
- * Generally you will not need to do this unless you are using Lando to build your own
- * interface.
+ * Generally you will not need to instantiate this directly unless you are using Lando
+ * to build your own interface.
  *
  * Check out `./bin/lando.js` in this repository for an example of how we instantiate
  * `lando` for usage in a CLI.
  *
  * @since 3.0.0
+ * @class
  * @name Lando
- * @param {Object} [options] Options to initialize a Lando object with
- * @return {Lando} An initialized Lando instance
- * @example
- * // Get a new lando instance
- * const Lando = require('lando');
- * const lando = new Lando({
- *   logLevelConsole: LOGLEVELCONSOLE,
- *   userConfRoot: USERCONFROOT,
- *   envPrefix: ENVPREFIX,
- *   configSources: configSources,
- *   pluginDirs: [USERCONFROOT],
- *   mode: 'cli'
- * });
+ * @module Lando
+ * @alias lando
+ * @property {Object} BOOTSTRAP_LEVELS Bootstrap level constants {config: 1, tasks: 2, engine: 3, app: 4}
+ * @property {LandoConfig} config The complete Lando configuration object
+ * @property {Bluebird} Promise A Promise implementation
+ * @property {Array} tasks Array of registered Lando tasks
+ * @property {Cache} cache Cache manager instance
+ * @property {Object} log Winston logger instance
+ * @property {Object} metrics Metrics tracking system
+ * @property {Object} error Error handler instance
+ * @property {AsyncEvents} events Event emitter for async events
+ * @property {Object} user User configuration
+ * @property {Object} updates Update manager instance
+ * @property {boolean} debuggy Whether debug mode is enabled
+ * @property {Object} engine Docker engine interface
+ * @property {Object} shell Shell command executor
+ * @property {Object} scanUrls URL scanning utility
+ * @property {Object} utils Collection of utility functions
+ * @property {Object} factory Service/recipe factory
+ * @property {Object} yaml YAML parser/writer utility
  */
-module.exports = class Lando {
+class Lando {
+  /**
+   * Creates a new Lando instance
+   * @param {LandoOptions} [options] Options to initialize a Lando object with
+   */
   constructor(options = {}) {
     const getPluginConfig = require('../utils/get-plugin-config');
 
     this.BOOTSTRAP_LEVELS = BOOTSTRAP_LEVELS;
+    /** @type {LandoConfig} */
     this.config = require('../utils/build-config')(options);
+    /** @type {Bluebird} */
     this.Promise = require('./promise');
     this.tasks = [];
     const AsyncEvents = require('./events');
     const Log = require('./logger');
     const ErrorHandler = require('./error');
     const UpdateManager = require('./updates');
     this.cache = require('../utils/setup-cache')(this.log, this.config);
-    this.log = new Log(this.config);
+    this.log = new Log({logLevelConsole: String(this.config.logLevelConsole)});
     this.metrics = require('../utils/setup-metrics')(this.log, this.config);
     this.error = new ErrorHandler(this.log, this.metrics),
     this.events = new AsyncEvents(this.log);
     this.user = require('./user');
 
     // updater is more complex now
-    this.updates = new UpdateManager({
+    /** @type {UpdateManagerOptions} */
+    const updateOpts = {
       agent: this.config.userAgent,
       channel: this.config.channel,
       cli: _.get(this, 'config.cli'),
       config: getPluginConfig(this.config.pluginConfigFile, this.config.pluginConfig),
       debug: require('../utils/debug-shim')(this.log),
-    });
+    };
+    this.updates = new UpdateManager(updateOpts);
 
     // helper just to determine whether we are "debuggy" or not
-    this.debuggy = this.config.logLevelConsole > 2
-      || this.config.logLevelConsole === 'verbose'
-      || this.config.logLevelConsole === 'debug'
-      || this.config.logLevelConsole === 'silly';
+    this.debuggy = this.config.logLevelConsole === 'verbose' ||
+      this.config.logLevelConsole === 'debug' ||
+      this.config.logLevelConsole === 'silly';
   }
 
   /**
@@ -265,11 +385,8 @@ module.exports = class Lando {
    * @fires post_bootstrap_tasks
    * @fires post_bootstrap_engine
    * @fires post_bootstrap_app
-   * @param {String} [level=app] Level with which to bootstrap Lando
-   * @return {Promise} A Promise
-   * @example
-   * // Bootstrap lando at default level and then exit
-   * lando.bootstrap().then(() => process.exit(0))l
+   * @param {string} [level='app'] Level with which to bootstrap Lando
+   * @return {Promise<Lando>} A Promise that resolves with the bootstrapped Lando instance
    */
   bootstrap(level = 'app') {
     // Log that we've begun
@@ -397,6 +514,20 @@ module.exports = class Lando {
     .then(() => this);
   }
 
+  /**
+   * Generates an SSL certificate for a domain
+   *
+   * @param {string} name - Name to use for the certificate files
+   * @param {Object} [options] - Certificate generation options
+   * @param {string} [options.caCert] - Path to CA certificate
+   * @param {string} [options.caKey] - Path to CA private key
+   * @param {string[]} [options.domains=[]] - Additional domains for the cert
+   * @param {string} [options.organization='Lando System'] - Organization name
+   * @param {number} [options.validity=365] - Certificate validity in days
+   * @return {Promise<Object>} Object containing paths to generated cert and key
+   * @property {string} certPath - Path to generated certificate
+   * @property {string} keyPath - Path to generated private key
+   */
   async generateCert(name, {
     caCert = this.config.caCert,
     caKey = this.config.caKey,
@@ -436,15 +567,15 @@ module.exports = class Lando {
   }
 
   /**
-   * Gets a fully instantiated App instance.
+   * Gets a fully instantiated App instance
    *
-   * Lando will also scan parent directories if no app is found in `startFrom`
+   * Lando will scan parent directories if no app is found in the starting directory.
    *
    * @since 3.0.0
    * @alias lando.getApp
-   * @param {String} [startFrom=process.cwd()] The directory to start looking for an app
-   * @param {Boolean} [warn=true] Show a warning if we can't find an app
-   * @return {App} Returns an instantiated App instandce.
+   * @param {string} [startFrom=process.cwd()] - The directory to start looking for an app
+   * @param {boolean} [warn=true] - Whether to show a warning if no app is found
+   * @return {App|undefined} Returns an instantiated App instance or undefined if no app found
    * @example
    * const app = lando.getApp('/path/to/my/app')
    */
@@ -472,6 +603,12 @@ module.exports = class Lando {
     return new App(config.name, _.merge({}, config, {files: landoFiles}), this);
   }
 
+  /**
+   * Gets installation status for plugins
+   * @param {Object} [options] - Plugin installation options
+   * @param {Object} [options.plugins] - Plugin definitions to check
+   * @return {Promise<PluginStatus[]>} Array of plugin status objects
+   */
   async getInstallPluginsStatus(options = this.config.setup) {
     const getPluginConfig = require('../utils/get-plugin-config');
     const Plugin = require('../components/plugin');
@@ -481,7 +618,8 @@ module.exports = class Lando {
     Plugin.debug = require('../utils/debug-shim')(this.log);
 
     // attempt to compute the destination to install the plugin
-    const {dir} = this.config.pluginDirs.find(dir => dir.type === require('../utils/get-plugin-type')());
+    const pluginDir = this.config.pluginDirs.find(dir => dir.type === require('../utils/get-plugin-type')());
+    const dir = pluginDir?.dir;
 
     // event that lets plugins modify the status check
     await this.events.emit('pre-install-plugins', options);
@@ -517,6 +655,12 @@ module.exports = class Lando {
     return results;
   }
 
+  /**
+   * Installs Lando plugins
+   * @param {Object} [options] - Plugin installation options
+   * @param {Object} [options.plugins] - Plugin definitions to install
+   * @return {Promise<TaskResults>} Installation results
+   */
   async installPlugins(options = this.config.setup) {
     const getPluginConfig = require('../utils/get-plugin-config');
     const Plugin = require('../components/plugin');
@@ -559,7 +703,12 @@ module.exports = class Lando {
     return {data, errors, results, total};
   }
 
-  // run tasks
+  /**
+   * Runs a series of tasks with progress reporting
+   * @param {Array} tasks - Tasks to run
+   * @param {TaskRunnerOptions} [options] - Task runner options
+   * @return {Promise<TaskResults>} Task results
+   */
   async runTasks(tasks, options = {}) {
     // some defaults
     const defaults = {rendererOptions: {log: this.log.debug}};
@@ -570,7 +719,7 @@ module.exports = class Lando {
     }
 
     // set to the debug renderer if we are in debug mode
-    if (this.config.logLevelConsole > 3
+    if ((typeof this.config.logLevelConsole === 'number' && this.config.logLevelConsole > 3)
       || this.config.logLevelConsole === 'debug'
       || this.config.logLevelConsole === 'silly') {
       options.renderer = options.debug || 'debug';
@@ -582,15 +731,27 @@ module.exports = class Lando {
     return await require('../utils/run-tasks')(tasks, _.merge(defaults, options));
   }
 
-  // this lets us reload plugins mid-process as though we were bootstrapping lando freshly
+  /**
+   * Reloads plugins as if bootstrapping fresh
+   *
+   * @return {Promise<void>}
+   */
   async reloadPlugins() {
     // if we dont do this we have at least double added setup tasks/plugins
     this.events.removeAllListeners();
     // reload plugins
     return await bootstrapConfig(this);
   }
 
-  // setup
+  /**
+   * Runs setup tasks and plugin installation
+   * @param {Object} [options] - Setup options
+   * @param {Array} [options.tasks=[]] - Setup tasks to run
+   * @param {Object} [options.plugins={}] - Plugins to install
+   * @param {boolean} [options.installPlugins] - Whether to install plugins
+   * @param {boolean} [options.installTasks] - Whether to run setup tasks
+   * @return {Promise<SetupResults>} Setup results
+   */
   async setup(options = this.config.setup) {
     // merge needed defaults into options
     options = _.merge({tasks: [], plugins: {}}, options);
@@ -655,6 +816,18 @@ module.exports = class Lando {
     return data;
   }
 
+  /**
+   * Gets status of setup tasks
+   *
+   * @param {Object} [options] - Setup options
+   * @param {Array} [options.tasks] - Tasks to check status for
+   * @return {Promise<Array<Object>>} Array of task status objects
+   * @property {string} version - Task version
+   * @property {string} description - Task description
+   * @property {string} state - Current state
+   * @property {string} [comment] - Additional status details
+   * @property {boolean} restart - Whether task requires restart
+   */
   async getSetupStatus(options = this.config.setup) {
     // pre setup event to mutate the setup tasks
     await this.events.emit('pre-setup', options);
@@ -690,4 +863,6 @@ module.exports = class Lando {
 
     return results;
   }
-};
+}
+
+module.exports = Lando;