@automattic/vip 4.1.5 → 4.1.8

package/node_modules/lando/lib/cli.js

@@ -8,6 +8,7 @@ const os = require('os');
 const path = require('path');
 
 // Global options
+/** @type {object} */
 const globalOptions = {
   channel: {
     describe: 'Sets the update channel',
@@ -35,13 +36,21 @@ const globalOptions = {
   },
 };
 
-/*
- * Construct the CLI
+/**
+ * CLI helper for task registration, prompting, and runtime config.
  */
 module.exports = class Cli {
+  /**
+   * @param {string} [prefix] Environment prefix.
+   * @param {string} [logLevel] Default log level.
+   * @param {string} [userConfRoot] User config directory.
+   */
   constructor(prefix = 'LANDO', logLevel = 'warn', userConfRoot = path.join(os.homedir(), '.lando')) {
+    /** @type {string} */
     this.prefix = prefix;
+    /** @type {string} */
     this.logLevel = logLevel;
+    /** @type {string} */
     this.userConfRoot = userConfRoot;
   }
 
@@ -55,43 +64,32 @@ module.exports = class Cli {
    * @todo make this static and then fix all call sites
    */
   argv() {
-    return require('yargs').help(false).version(false).argv;
+    return require('./esm/yargs').default(process.argv.slice(2))
+        .option('verbose', globalOptions.verbose)
+        .help(false)
+        .version(false)
+        .parseSync();
   }
 
   /**
-   * Checks to see if lando is running with sudo. If it is it
-   * will exit the process with a stern warning
-   * @since 3.0.0
-   * @alias lando.cli.checkPerms
-   * @example
-   * lando.cli.checkPerms()
-   */
-  checkPerms() {
-    /* Do nothing */
-  }
-
-  /*
-   * Toggle the secret toggle
+   * Clears cached task metadata files.
+   * @returns {void}
    */
   clearTaskCaches() {
     if (fs.existsSync(process.landoTaskCacheFile)) fs.unlinkSync(process.landoTaskCacheFile);
     if (fs.existsSync(process.landoAppTaskCacheFile)) fs.unlinkSync(process.landoAppTaskCacheFile);
   }
 
-  /*
-   * Confirm question
+  /**
+   * Builds a reusable confirmation option definition.
+   * @returns {object} CLI option definition.
    */
-  confirm(message = 'Are you sure?') {
+  confirm() {
     return {
       describe: 'Auto answer yes to prompts',
       alias: ['y'],
       default: false,
       boolean: true,
-      interactive: {
-        type: 'confirm',
-        default: false,
-        message: message,
-      },
     };
   }
 
@@ -143,15 +141,24 @@ module.exports = class Cli {
     };
   }
 
-  /*
-   * Format data
+  /**
+   * Formats task output for CLI display.
+   * @param {unknown} data Output data.
+   * @param {object} [formatting] Formatting options.
+   * @param {string} [formatting.path] Object path to extract.
+   * @param {'default'|'json'|'table'} [formatting.format] Output format.
+   * @param {string[]} [formatting.filter] Array filters in `key=value` form.
+   * @param {object} [opts] Formatter options.
+   * @returns {string} Formatted output.
    */
   formatData(data, {path = '', format = 'default', filter = []} = {}, opts = {}) {
     return formatters.formatData(data, {path, format, filter}, opts);
   }
 
-  /*
-   * FormatOptios
+  /**
+   * Returns formatter-related CLI options.
+   * @param {string[]} [omit] Option keys to omit.
+   * @returns {object} Formatter option config.
    */
   formatOptions(omit = []) {
     return formatters.formatOptions(omit);
@@ -163,9 +170,9 @@ module.exports = class Cli {
    * @alias lando.cli.handleError
    * @param {Error} error The error
    * @param {import('./error')} handler The error handler function
-   * @param {number} verbose [verbose=this.argv().verbose] The verbosity level
+   * @param {number} verbose The verbosity level
    * @param {object} lando The Lando object
-   * @returns {Promise<never>}
+   * @returns {Promise<never>} Promise that exits the process with the resolved code.
    */
   handleError(error, handler, verbose = this.argv().verbose, lando = {}) {
     // Set the verbosity
@@ -174,10 +181,17 @@ module.exports = class Cli {
     return handler.handle(error).then(code => process.exit(code));
   }
 
-  /*
-   * Init
+  /**
+   * Initializes yargs with global options and registered tasks.
+   * @param {object} yargs Yargs instance.
+   * @param {object[]} tasks Registered task definitions.
+   * @param {object} config App config.
+   * @param {object} userConfig User config data.
+   * @returns {Promise<object>} Parsed arguments after command completion.
    */
   init(yargs, tasks, config, userConfig) {
+    // Read global flags before registering handlers, which can parse asynchronously.
+    const argv = yargs.argv;
     // Define usage
     const cmd = !_.has(process, 'pkg') ? '$0' : path.basename(_.get(process, 'execPath', 'lando'));
     const usage = [`Usage: ${cmd} <command> [args] [options]`];
@@ -209,14 +223,14 @@ module.exports = class Cli {
     });
 
     // Show help unless this is a delegation command
-    const current = _.find(tasks, {command: yargs.argv._[0]});
-    if ((yargs.argv.help || yargs.argv.lando) && _.get(current, 'delegate', false) === false) {
+    const current = _.find(tasks, {command: argv._[0]});
+    if ((argv.help || argv.lando) && _.get(current, 'delegate', false) === false) {
       yargs.showHelp('log');
       process.exit(0);
     }
 
     // YARGZ MATEY
-    yargs.argv;
+    return yargs.parseAsync();
   }
 
 
@@ -242,11 +256,11 @@ module.exports = class Cli {
    * @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 task.command
-   * @param task.describe
-   * @param task.options
-   * @param task.run
-   * @param task.level
+   * @param {string} task.command Command name.
+   * @param {string} task.describe Command description.
+   * @param {object} task.options Command options.
+   * @param {function(object, object): (Promise<object>|object|void)} task.run Command runner.
+   * @param {string} task.level Bootstrap level.
    * @param {object} [config] The landofile
    * @returns {object} A yargs command object
    * @example
@@ -255,8 +269,7 @@ module.exports = class Cli {
    */
   parseToYargs({command, describe, options = {}, run = {}, level = 'app'}, config = {}) {
     const handler = argv => {
-      // Immediately build some arg data set opts and interactive options
-      const data = {options: argv, inquiry: formatters.getInteractive(options, argv)};
+      const data = {options: argv};
 
       // Summon lando
       const Lando = require('./../lib/lando');
@@ -286,21 +299,7 @@ module.exports = class Cli {
             }
           }
         })
-        /**
-         * Event that allows altering of argv or inquirer before interactive prompts
-         * are run
-         *
-         * You will want to replace CMD with the actual task name eg `task-start-answers`.
-         * @since 3.0.0
-         * @event task_CMD_answers
-         * @property {object} answers argv and inquirer questions
-         */
-            .then(() => lando.events.emit('cli-answers', data, argv._[0]))
-            .then(() => lando.events.emit(`cli-${argv._[0]}-answers`, data, argv._[0]))
-
-        // Attempt to filter out questions that have already been answered
-        // Prompt the use for feedback if needed and sort by weight
-            .then(() => formatters.handleInteractive(data.inquiry, data.options, command, lando))
+            .then(() => ({}))
 
         /**
          * Event that allows final altering of answers before the task runs
@@ -334,11 +333,14 @@ module.exports = class Cli {
     return {command, describe, builder: formatters.sortOptions(options), handler};
   }
 
-  /*
-   * Run the CLI
+  /**
+   * Runs the CLI with the provided task set.
+   * @param {object[]} [tasks] Registered task definitions.
+   * @param {object} [config] App config.
+   * @returns {Promise<object>} Parsed arguments after command completion.
    */
   run(tasks = [], config = {}) {
-    const yargs = require('yargs');
+    const yargs = require('./esm/yargs').default(process.argv.slice(2)).help(false).version(false);
     const {clear} = yargs.argv;
 
     // Handle all our configuration global opts first
@@ -350,11 +352,13 @@ module.exports = class Cli {
     }
 
     // Initialize
-    this.init(yargs, tasks, config, userConfig);
+    return this.init(yargs, tasks, config, userConfig);
   }
 
-  /*
-   * Toggle a toggle
+  /**
+   * Updates user config and persists toggle-related settings.
+   * @param {object} [data] Partial user config updates.
+   * @returns {object} Persisted user config.
    */
   updateUserConfig(data = {}) {
     const Yaml = require('./yaml');

package/node_modules/lando/lib/compose.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Helper object for flags
+/** @type {Record<string, string>} */
 const composeFlags = {
   background: '--detach',
   detach: '--detach',
@@ -19,7 +19,7 @@ const composeFlags = {
   volumes: '-v',
 };
 
-// Default options nad things
+/** @type {Record<string, object>} */
 const defaultOptions = {
   build: {noCache: false, pull: true},
   down: {removeOrphans: true, volumes: true},
@@ -34,18 +34,16 @@ const defaultOptions = {
 
 /**
  * Helper to merge options with default
- *
  * @param {string} run The command to run
- * @param {Object} opts The options to merge
- * @return {Object} The merged options
+ * @param {object} [opts] The options to merge
+ * @returns {object} The merged options
  */
 const mergeOpts = (run, opts = {}) => ({...defaultOptions[run], ...opts});
 
 /**
  * Parse docker-compose options
- *
- * @param {Object} opts The options to parse
- * @return {Array} The parsed options
+ * @param {object} [opts] The options to parse
+ * @returns {string[]} The parsed options
  */
 const parseOptions = (opts = {}) => {
   const flags = Object.keys(composeFlags).map(key => opts[key] ? composeFlags[key] : '');
@@ -59,12 +57,14 @@ const parseOptions = (opts = {}) => {
 
 /**
  * Helper to standardize construction of docker commands
- *
  * @param {string} run The command to run
  * @param {string} name The name of the project
  * @param {string[]} compose The array of compose files
- * @param {Object} opts The options to pass to the command
- * @return {Array} The constructed command
+ * @param {object} args Command args.
+ * @param {string[]} [args.services] Target services.
+ * @param {string|string[]} [args.cmd] Command argv.
+ * @param {object} [opts] The options to pass to the command
+ * @returns {string[]} The constructed command
  */
 const buildCmd = (run, name, compose, {services, cmd}, opts = {}) => {
   if (!name) throw new Error('Need to give this composition a project name!');
@@ -78,52 +78,67 @@ const buildCmd = (run, name, compose, {services, cmd}, opts = {}) => {
 
 /**
  * Helper to build build object needed by lando.shell.sh
- *
  * @param {string} run The command to run
  * @param {string} name The name of the project
  * @param {string[]} compose The array of compose files
- * @param {Object} opts The options to pass to the command
- * @param {string[]} [opts.pullable]
- * @param {string[]} [opts.local]
- * @param {boolean} [opts.purge]
- * @param {boolean} [opts.pull]
- * @param {string[]} [opts.services]
- * @param {string[]} [opts.cmd]
- * @param {Array} [opts.cstdio]
- * @param {string} [opts.mode]
- * @param {boolean} [opts.prestart]
- * @param {boolean} [opts.last]
- * @param {boolean} [opts.detach]
- * @param {boolean} [opts.silent]
- * @param {string} [opts.user]
- * @param {string} [opts.id]
- * @param {Record<string,string>} [opts.environment]
- * @return {Object} The shell object
+ * @param {object} [opts] The options to pass to the command
+ * @param {string[]} [opts.pullable] Services that may be pulled.
+ * @param {string[]} [opts.local] Services that should not be pulled.
+ * @param {boolean} [opts.purge] Whether removal should purge networks and volumes.
+ * @param {boolean} [opts.pull] Whether images should be pulled during build.
+ * @param {string[]} [opts.services] Target services.
+ * @param {string[]} [opts.cmd] Command argv passed to the service.
+ * @param {Array} [opts.cstdio] Custom stdio configuration.
+ * @param {string} [opts.mode] Shell execution mode.
+ * @param {boolean} [opts.prestart] Whether this runs before startup.
+ * @param {boolean} [opts.last] Whether this is the final step in a sequence.
+ * @param {boolean} [opts.detach] Whether the process should detach.
+ * @param {boolean} [opts.silent] Whether shell output should be silenced.
+ * @param {string} [opts.user] User to run the command as.
+ * @param {string} [opts.id] Target container id.
+ * @param {Record<string,string>} [opts.environment] Extra environment variables.
+ * @returns {object} The shell object
  */
 const buildShell = (run, name, compose, opts = {}) => ({
   cmd: buildCmd(run, name, compose, {services: opts.services, cmd: opts.cmd}, mergeOpts(run, opts)),
   opts: {mode: 'spawn', cstdio: opts.cstdio, silent: opts.silent},
 });
 
-/*
- * Run docker compose build
+/**
+ * Builds a docker compose build shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Build options.
+ * @returns {object} Shell descriptor.
  */
 exports.build = (compose, project, opts = {}) => {
   return buildShell('build', project, compose, {pull: !opts.local});
 };
 
-/*
- * Run docker compose ps
+/**
+ * Builds a docker compose ps shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Ps options.
+ * @returns {object} Shell descriptor.
  */
 exports.getId = (compose, project, opts = {}) => buildShell('ps', project, compose, opts);
 
-/*
- * Run docker compose logs
+/**
+ * Builds a docker compose logs shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Log options.
+ * @returns {object} Shell descriptor.
  */
 exports.logs = (compose, project, opts = {}) => buildShell('logs', project, compose, opts);
 
-/*
- * Run docker compose pull
+/**
+ * Builds a docker compose pull shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Pull options.
+ * @returns {object} Shell descriptor.
  */
 exports.pull = (compose, project, opts = {}) => {
   /** @type {string[]} */
@@ -136,25 +151,41 @@ exports.pull = (compose, project, opts = {}) => {
   return buildShell('ps', project, compose, {});
 };
 
-/*
- * Run docker compose remove
+/**
+ * Builds a docker compose remove or down shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Remove options.
+ * @returns {object} Shell descriptor.
  */
 exports.remove = (compose, project, opts = {}) => {
   const subCmd = (opts.purge) ? 'down' : 'rm';
   return buildShell(subCmd, project, compose, opts);
 };
 
-/*
- * Run docker compose run
+/**
+ * Builds a docker compose exec shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Exec options.
+ * @returns {object} Shell descriptor.
  */
 exports.run = (compose, project, opts = {}) => buildShell('exec', project, compose, opts);
 
-/*
- * You can do a create, rebuild and start with variants of this
+/**
+ * Builds a docker compose up shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Up options.
+ * @returns {object} Shell descriptor.
  */
 exports.start = (compose, project, opts = {}) => buildShell('up', project, compose, opts);
 
-/*
- * Run docker compose kill
+/**
+ * Builds a docker compose kill shell descriptor.
+ * @param {string[]} compose Compose files.
+ * @param {string} project Project name.
+ * @param {object} [opts] Kill options.
+ * @returns {object} Shell descriptor.
  */
 exports.stop = (compose, project, opts = {}) => buildShell('kill', project, compose, opts);

package/node_modules/lando/lib/config.js

@@ -9,7 +9,24 @@ const os = require('os');
 const yaml = require('js-yaml');
 const url = require('url');
 
+/**
+ * A plugin directory source.
+ * @typedef {object} PluginDir
+ * @property {string} path Absolute or relative path to the plugin root.
+ * @property {string} [subdir='plugins'] Subdirectory that contains plugins.
+ */
+
+/**
+ * A normalized plugin reference.
+ * @typedef {object} PluginReference
+ * @property {string} name Plugin name.
+ * @property {'local'|'remote'} type How the plugin should be resolved.
+ * @property {string} [path] Local plugin path.
+ * @property {string} [version] Remote plugin version.
+ */
+
 // Default config
+/** @type {object} */
 const defaultConfig = {
   composeBin: env.getComposeExecutable(),
   disablePlugins: [],
@@ -31,8 +48,11 @@ const defaultConfig = {
   userConfRoot: os.tmpdir(),
 };
 
-/*
- * @TODO
+/**
+ * Builds a Docker host URL from hostname and port parts.
+ * @param {string} hostname Hostname or IP address for the Docker daemon.
+ * @param {number} [port] Docker daemon TCP port.
+ * @returns {string} Formatted Docker host URL.
  */
 const setDockerHost = (hostname, port = 2376) => url.format({
   protocol: 'tcp',
@@ -41,8 +61,12 @@ const setDockerHost = (hostname, port = 2376) => url.format({
   port,
 });
 
-/*
- * @TODO
+/**
+ * Normalizes plugin directory definitions into absolute paths and explicit subdirs.
+ * @param {Array<string|PluginDir>} [dirs] Plugin directory definitions.
+ * @param {string} [baseDir] Base directory used to resolve relative paths.
+ * @param {boolean} [isLandoFile] Whether the source came from a Landofile.
+ * @returns {PluginDir[]} Normalized plugin directory definitions.
  */
 const normalizePluginDirs = (dirs = [], baseDir = __dirname, isLandoFile = false) => _(dirs)
     .map(data => {
@@ -64,8 +88,11 @@ const normalizePluginDirs = (dirs = [], baseDir = __dirname, isLandoFile = false
     })
     .value();
 
-/*
- * @TODO
+/**
+ * Resolves plugin declarations into local or remote plugin references.
+ * @param {Record<string, string>} [plugins] Plugin declarations keyed by plugin name.
+ * @param {string} [baseDir] Base directory used to resolve local plugin paths.
+ * @returns {PluginReference[]} Normalized plugin references.
  */
 const normalizePlugins = (plugins = [], baseDir = __dirname) => _(plugins)
 // @NOTE: right now this is very "dumb", if the plugin is a path that exist then we set to local
@@ -85,11 +112,10 @@ const normalizePlugins = (plugins = [], baseDir = __dirname) => _(plugins)
 
 /**
  * Attempt to parse a JSON string to an objects
- *
  * @since 3.0.0
  * @alias lando.utils.config.tryConvertJson
- * @param {String} value The string to convert
- * @return {Object} A parsed object or the inputted value
+ * @param {string} value The string to convert
+ * @returns {object} A parsed object or the inputted value
  */
 exports.tryConvertJson = value => {
   try {
@@ -102,13 +128,12 @@ exports.tryConvertJson = value => {
 /**
  * Uses _.mergeWith to concat arrays, this helps replicate how Docker Compose
  * merges its things
- *
  * @see https://lodash.com/docs#mergeWith
  * @since 3.0.0
  * @alias lando.utils.config.merge
- * @param {Object} old object to be merged
- * @param {Object} fresh object to be merged
- * @return {Object} The new object
+ * @param {object} old object to be merged
+ * @param {object} fresh object to be merged
+ * @returns {object} The new object
  * @example
  * // Take an object and write a docker compose file
  * const newObject = _.mergeWith(a, b, lando.utils.merger);
@@ -121,11 +146,10 @@ exports.merge = (old, ...fresh) => _.mergeWith(old, ...fresh, (s, f) => {
  * Strips process.env of all envvars with PREFIX and returns process.env
  *
  * NOTE: this actually returns process.env not a NEW object cloned from process.env
- *
  * @since 3.0.0
  * @alias lando.utils.config.stripEnv
- * @param {String} prefix - The prefix to strip
- * @return {Object} Updated process.env
+ * @param {string} prefix - The prefix to strip
+ * @returns {object} Updated process.env
  * @example
  * // Reset the process.env without any DOCKER_ prefixed envvars
  * process.env = config.stripEnv('DOCKER_');
@@ -144,10 +168,9 @@ exports.stripEnv = prefix => {
 
 /**
  * Define default config
- *
  * @since 3.0.0
  * @alias lando.utils.config.defaults
- * @return {Object} The default config object.
+ * @returns {object} The default config object.
  */
 exports.defaults = () => {
   // Also add some info to the process so we can use this elsewhere
@@ -156,8 +179,12 @@ exports.defaults = () => {
   return _.merge(defaultConfig, {process: process.lando});
 };
 
-/*
- * @TODO
+/**
+ * Applies engine-specific environment variables and TLS material.
+ * @param {object} [options] Engine settings to normalize.
+ * @param {object} [options.engineConfig] Raw engine configuration.
+ * @param {object} [options.env] Environment object to mutate with Docker vars.
+ * @returns {object} The updated engine configuration.
  */
 exports.getEngineConfig = ({engineConfig = {}, env = {}}) => {
   // Set the docker host if its non-standard
@@ -176,20 +203,12 @@ exports.getEngineConfig = ({engineConfig = {}, env = {}}) => {
   // Return
   return engineConfig;
 };
-
-
-/*
- * @TODO
- */
-exports.getOclifCacheDir = (product = 'hyperdrive') => env.getOclifCacheDir(product);
-
 /**
  * Merge in config file if it exists
- *
  * @since 3.5.0
  * @alias lando.utils.config.loadFiles
- * @param {Array} files - An array of files or objects  to try loading
- * @return {Object} An object of config merged from file sources
+ * @param {Array<string|{file: string, data?: object, landoFile?: boolean}>} files An array of files or source objects to try loading.
+ * @returns {object} An object of config merged from file sources
  */
 exports.loadFiles = files => _(files)
 // Filter the source out if it doesn't exist
@@ -227,11 +246,10 @@ exports.loadFiles = files => _(files)
 
 /**
  * Filter process.env by a given prefix
- *
  * @since 3.0.0
  * @alias lando.utils.config.loadEnvs
- * @param {String} prefix - The prefix by which to filter. Should be without the trailing `_` eg `LANDO` not `LANDO_`
- * @return {Object} Object of things with camelCased keys
+ * @param {string} prefix - The prefix by which to filter. Should be without the trailing `_` eg `LANDO` not `LANDO_`
+ * @returns {object} Object of things with camelCased keys
  */
 exports.loadEnvs = prefix => _(process.env)
 // Only muck with prefix_ variables