@automattic/vip 4.1.4 → 4.1.6

package/node_modules/lando/lib/art.js

@@ -5,18 +5,33 @@ const _ = require('lodash');
 const chalk = require('chalk');
 const os = require('os');
 
-/*
- * Helper to stylize code or a command
+/**
+ * Warning payload used by start and rebuild status messages.
+ * @typedef {object} ArtWarning
+ * @property {string} title Warning title.
+ * @property {string[]} [detail] Additional warning detail lines.
+ * @property {string} [command] Suggested command to run.
+ * @property {string} [url] Optional help URL.
+ */
+
+/**
+ * Stylizes code or shell commands in terminal output.
+ * @param {string} text Text to stylize.
+ * @returns {string} Styled text.
  */
 const codeMe = text => chalk.italic(text);
 
-/*
- * Helper to stylize an italicize
+/**
+ * Stylizes app names and emphasis text.
+ * @param {string} name Text to stylize.
+ * @returns {string} Styled text.
  */
 const italicize = name => chalk.italic(name);
 
-/*
- * Helper to stylize a warning message
+/**
+ * Formats a warning block for terminal output.
+ * @param {ArtWarning} [warning] Warning payload.
+ * @returns {string} Formatted warning block.
  */
 const warningMessage = ({title, detail = [], command = '', url = ''} = {}) => `
  ${chalk.yellow(`■ ${title}`)}
@@ -24,8 +39,12 @@ const warningMessage = ({title, detail = [], command = '', url = ''} = {}) => `
    ${(url) ? chalk.green(url) : codeMe(command)}
 `;
 
-/*
- * Helper to show that an app has started
+/**
+ * Builds destroy lifecycle messaging.
+ * @param {object} [options] Destroy message options.
+ * @param {string} [options.name] App name.
+ * @param {'abort'|'pre'|'post'} [options.phase] Lifecycle phase.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.appDestroy = ({name, phase = 'pre'} = {}) => {
   switch (phase) {
@@ -40,8 +59,13 @@ exports.appDestroy = ({name, phase = 'pre'} = {}) => {
   }
 };
 
-/*
- * Helper to show that an app has restarted
+/**
+ * Builds rebuild lifecycle messaging.
+ * @param {object} [options] Rebuild message options.
+ * @param {string} [options.name] App name.
+ * @param {'abort'|'error'|'pre'|'post'|'report'} [options.phase] Lifecycle phase.
+ * @param {ArtWarning[]|object[]} [options.warnings] Collected warnings.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.appRebuild = ({name, phase = 'pre', warnings = {}} = {}) => {
   switch (phase) {
@@ -58,8 +82,13 @@ exports.appRebuild = ({name, phase = 'pre', warnings = {}} = {}) => {
   }
 };
 
-/*
- * Helper to show that an app has restarted
+/**
+ * Builds restart lifecycle messaging.
+ * @param {object} [options] Restart message options.
+ * @param {string} [options.name] App name.
+ * @param {'error'|'pre'|'post'|'report'} [options.phase] Lifecycle phase.
+ * @param {ArtWarning[]|object[]} [options.warnings] Collected warnings.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.appRestart = ({name, phase = 'pre', warnings = {}} = {}) => {
   switch (phase) {
@@ -74,8 +103,13 @@ exports.appRestart = ({name, phase = 'pre', warnings = {}} = {}) => {
   }
 };
 
-/*
- * Helper to show that an app has started
+/**
+ * Builds start lifecycle messaging.
+ * @param {object} [options] Start message options.
+ * @param {string} [options.name] App name.
+ * @param {'error'|'pre'|'post'|'report'} [options.phase] Lifecycle phase.
+ * @param {ArtWarning[]|object[]} [options.warnings] Collected warnings.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.appStart = ({name, phase = 'pre', warnings = {}} = {}) => {
   switch (phase) {
@@ -136,8 +170,12 @@ exports.appStart = ({name, phase = 'pre', warnings = {}} = {}) => {
   }
 };
 
-/*
- * Helper to show that an app has stopped
+/**
+ * Builds stop lifecycle messaging.
+ * @param {object} [options] Stop message options.
+ * @param {string} [options.name] App name.
+ * @param {'pre'|'post'} [options.phase] Lifecycle phase.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.appStop = ({name, phase = 'pre'} = {}) => {
   switch (phase) {
@@ -148,8 +186,9 @@ exports.appStop = ({name, phase = 'pre'} = {}) => {
   }
 };
 
-/*
- * Helper to show that a first error has occurred
+/**
+ * Builds the crash reporting prompt.
+ * @returns {string} Crash prompt.
  */
 exports.crash = () => [
   '',
@@ -161,8 +200,9 @@ exports.crash = () => [
   chalk.green('For more details check out https://docs.lando.dev/privacy/'),
 ].join(os.EOL);
 
-/*
- * Helper to show init header
+/**
+ * Builds the initialization success banner.
+ * @returns {string} Initialization banner.
  */
 exports.init = () => [
   '',
@@ -177,8 +217,10 @@ exports.init = () => [
   '',
 ].join(os.EOL);
 
-/*
- * Helper to show new content
+/**
+ * Builds the new-content banner.
+ * @param {string} [type] Content type label.
+ * @returns {string} New-content banner.
  */
 exports.newContent = (type = 'guide') => [
   '',
@@ -191,8 +233,10 @@ exports.newContent = (type = 'guide') => [
   '',
 ].join(os.EOL);
 
-/*
- * Helper to show NO DOCKER error message
+/**
+ * Builds the missing dependency message.
+ * @param {string} [dep] Missing dependency name.
+ * @returns {string} Missing dependency message.
  */
 exports.noDockerDep = (dep = 'Docker') => [
   '',
@@ -218,8 +262,11 @@ exports.noDockerDep = (dep = 'Docker') => [
   '',
 ].join(os.EOL);
 
-/*
- * Helper to show status of secret toggle
+/**
+ * Builds the poweroff lifecycle message.
+ * @param {object} [options] Poweroff message options.
+ * @param {'pre'|'post'} [options.phase] Lifecycle phase.
+ * @returns {string|undefined} Rendered message for the selected phase.
  */
 exports.poweroff = ({phase = 'pre'} = {}) => {
   switch (phase) {
@@ -235,15 +282,24 @@ exports.poweroff = ({phase = 'pre'} = {}) => {
   }
 };
 
-/*
- * Helper to show status of secret toggle
+/**
+ * Prints colored terminal text.
+ * @param {object} [options] Print options.
+ * @param {string} [options.text] Text to print.
+ * @param {string} [options.color] Chalk color name.
+ * @returns {string} Styled text.
  */
 exports.print = ({text, color = 'white'} = {}) => {
   return chalk[color](text);
 };
 
-/*
- * Helper to show status of secret toggle
+/**
+ * Prints stylized banner text.
+ * @param {object} [options] Print options.
+ * @param {string} [options.text] Text to print.
+ * @param {string} [options.color] Chalk color name.
+ * @param {string} [options.font] Unused font hint kept for API compatibility.
+ * @returns {string} Styled text.
  */
 exports.printFont = ({text, color = 'magenta', font = 'Small Slant'} = {}) => {
   return chalk[color](text);

package/node_modules/lando/lib/bootstrap.js

@@ -8,16 +8,92 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 
-/*
- * Helper to determine bootstrap level
+/**
+ * Docker and Compose version metadata.
+ * @typedef {object} ComposeVersionInfo
+ * @property {string} [engine] Docker engine version.
+ * @property {string} [compose] Docker Compose version.
+ * @property {string} [composePlugin] Docker Compose plugin version.
+ */
+
+/**
+ * Config source entry used during bootstrap.
+ * @typedef {object} ConfigSourceEntry
+ * @property {object} data Config data to merge.
+ * @property {string} file Source file path.
+ * @property {boolean} [landoFile] Whether the source came from a Landofile.
+ */
+
+/**
+ * Bootstrap options used to assemble runtime config.
+ * @typedef {object} BootstrapOptions
+ * @property {Array<ConfigSourceEntry>} [configSources] Bootstrap config sources.
+ * @property {string} [envPrefix] Environment variable prefix.
+ * @property {object} [engineConfig] Raw engine configuration.
+ * @property {object} [landoFileConfig] Landofile config overrides.
+ * @property {string} [userConfRoot] User config root.
+ */
+
+/**
+ * Runtime config shape used during bootstrap.
+ * @typedef {object} RuntimeConfig
+ * @property {string|false} [composeBin] Docker Compose binary path.
+ * @property {string} [composeCache] Compose cache file path.
+ * @property {Array<ConfigSourceEntry>} [configSources] Bootstrap config sources.
+ * @property {string|false} [dockerBin] Docker binary path.
+ * @property {object} [engineConfig] Raw engine configuration.
+ * @property {Record<string, unknown>} [env] Runtime environment variables.
+ * @property {string} [envPrefix] Environment variable prefix.
+ * @property {string} [home] User home directory.
+ * @property {string} [id] Runtime user identifier.
+ * @property {string} [instance] Runtime instance id.
+ * @property {object} [landoFileConfig] Landofile config overrides.
+ * @property {string} [process] Runtime process label.
+ * @property {string} [recipe] Active recipe name.
+ * @property {Record<string, unknown>} [tooling] Tooling definitions.
+ * @property {string} [toolingCache] Tooling cache file path.
+ * @property {string} [toolingRouter] Tooling router cache file path.
+ * @property {string} [user] Runtime user id.
+ * @property {string} userConfRoot User config root.
+ * @property {ComposeVersionInfo} [versions] Docker and Compose version metadata.
+ */
+
+/**
+ * Minimal app-like object loaded from Landofiles.
+ * @typedef {object} MinimalAppData
+ * @property {string[]} compose Array of Docker Compose file paths.
+ * @property {string} composeCache Compose cache file path.
+ * @property {string[]} configFiles Source config files.
+ * @property {string} metaCache Metadata cache key.
+ * @property {string} name App name.
+ * @property {string} project Docker Compose project name.
+ * @property {string} root App root directory.
+ * @property {string} toolingCache Tooling cache file path.
+ * @property {string} toolingRouter Tooling router cache file path.
+ */
+
+/**
+ * Parsed CLI argv used during task bootstrap.
+ * @typedef {object} ParsedArgv
+ * @property {string[]} [_] Positional command arguments.
+ * @property {{root: string}} [_app] Active app metadata.
+ */
+
+/**
+ * Determines whether a tooling command can run at app or engine bootstrap level.
+ * @param {RuntimeConfig} config App config.
+ * @param {string} command Tooling command name.
+ * @returns {'app'|'engine'} Bootstrap level.
  */
 const getBsLevel = (config, command) => {
   if (_.has(config, `tooling.${command}.level`)) return config.tooling[command].level;
   else return (!fs.existsSync(config.composeCache)) ? 'app' : 'engine';
 };
 
-/*
- * Helper to load cached file without cache module
+/**
+ * Loads a cached JSON payload without going through the cache module.
+ * @param {string} file Cache file path.
+ * @returns {Record<string, unknown>} Parsed cached data.
  */
 const loadCacheFile = file => {
   try {
@@ -27,8 +103,10 @@ const loadCacheFile = file => {
   }
 };
 
-/*
- * Helper to load landofile
+/**
+ * Loads a Landofile from disk.
+ * @param {string} file Landofile path.
+ * @returns {Record<string, unknown>} Parsed YAML payload.
  */
 const loadLandoFile = file => {
   try {
@@ -38,8 +116,10 @@ const loadLandoFile = file => {
   }
 };
 
-/*
- * Helper to run the app task runner
+/**
+ * Builds an app-level task runner for a tooling command.
+ * @param {string} command Tooling command name.
+ * @returns {function(object, import('./lando')): Promise} Task runner.
  */
 const appRunner = command => (argv, lando) => {
   const app = lando.getApp(argv._app.root);
@@ -48,8 +128,11 @@ const appRunner = command => (argv, lando) => {
       .then(() => app.init().then(() => _.find(app.tasks, {command}).run(argv)));
 };
 
-/*
- * Helper to return the engine task runner
+/**
+ * Builds an engine-level task runner for a tooling command.
+ * @param {RuntimeConfig} config App config.
+ * @param {string} command Tooling command name.
+ * @returns {function(object, import('./lando')): Promise} Task runner.
  */
 const engineRunner = (config, command) => (argv, lando) => {
   const AsyncEvents = require('./events');
@@ -70,16 +153,20 @@ const engineRunner = (config, command) => (argv, lando) => {
       .then(() => buildTask(_.find(app.config.tooling, task => task.name === command), lando).run(argv));
 };
 
-/*
- * Helper to traverse up directories from a start point
+/**
+ * Builds candidate file locations while traversing upward from a start path.
+ * @param {string} file File path to traverse from.
+ * @returns {string[]} Candidate file paths.
  */
 const traverseUp = file => _(_.range(path.dirname(file).split(path.sep).length))
     .map(end => _.dropRight(path.dirname(file).split(path.sep), end).join(path.sep))
     .map(dir => path.join(dir, path.basename(file)))
     .value();
 
-/*
- * Paths to /
+/**
+ * Returns directory paths from a starting point up to the filesystem root.
+ * @param {string} [startFrom] Starting directory.
+ * @returns {string[]} Directory paths ordered from nearest to farthest.
  */
 const pathsToRoot = (startFrom = process.cwd()) => {
   return _(_.range(path.dirname(startFrom).split(path.sep).length))
@@ -89,8 +176,10 @@ const pathsToRoot = (startFrom = process.cwd()) => {
       .value();
 };
 
-/*
- * Converts landofile things into a configsource
+/**
+ * Converts Landofile-derived plugin config into a config source entry.
+ * @param {RuntimeConfig} [config] App config.
+ * @returns {ConfigSourceEntry} Config source entry.
  */
 const parseLandofileConfig = (config = {}) => ({
   data: _.pickBy(config, (value, key) => {
@@ -100,8 +189,10 @@ const parseLandofileConfig = (config = {}) => ({
   landoFile: true,
 });
 
-/*
- * Helper to build config
+/**
+ * Builds the final runtime config from defaults, files, env, and computed values.
+ * @param {BootstrapOptions} options Bootstrap options.
+ * @returns {RuntimeConfig} Final runtime config.
  */
 exports.buildConfig = options => {
   // Modules
@@ -130,26 +221,21 @@ exports.buildConfig = options => {
   if (process.platform === 'win32') config.env.COMPOSE_CONVERT_WINDOWS_PATHS = 1;
   // Extend the dockercompose timeout limit for future mutagen things
   config.env.COMPOSE_HTTP_TIMEOUT = 300;
-  // Get hyperdrive lando config file location
-  config.hconf = path.join(helpers.getOclifCacheDir(config.hyperdrive), `${config.product}.json`);
   // Return the config
   return config;
 };
 
 /**
  * Helper for docker compose
- * @TODO: eventually this needs to live somewhere else so we can have a better
- * default engine instantiation
- * @param {Shell} shell
- * @param {string} bin
- * @param {string} cmd
- * @param {object} datum
- * @param datum.opts
- * @param datum.project
- * @param datum.compose
- * @param {string} dockerBin
- * @param {object} versions
- * @returns {Promise<string>}
+ * TODO: eventually this needs to live somewhere else so we can have a better
+ * default engine instantiation.
+ * @param {import('./shell')} shell Shell helper.
+ * @param {string} bin Docker compose binary.
+ * @param {string} cmd Compose command name.
+ * @param {import('./engine').EngineComposeTaskData} datum Compose run descriptor.
+ * @param {string} dockerBin Docker binary.
+ * @param {ComposeVersionInfo} versions Docker and compose version metadata.
+ * @returns {Promise<string>} Command output.
  */
 exports.dc = (shell, bin, cmd, {compose, project, opts = {}}, dockerBin, versions) => {
   const dockerCompose = require('./compose');
@@ -160,8 +246,11 @@ exports.dc = (shell, bin, cmd, {compose, project, opts = {}}, dockerBin, version
   return shell.sh([bin].concat(run.cmd), run.opts);
 };
 
-/*
- * Helper to load a very basic app
+/**
+ * Loads a minimal app-like object from a set of Landofiles.
+ * @param {string[]} files Landofile paths.
+ * @param {string} userConfRoot User config root.
+ * @returns {MinimalAppData} Minimal app data.
  */
 exports.getApp = (files, userConfRoot) => {
   const config = merger({}, ..._.map(files, file => loadLandoFile(file)));
@@ -176,8 +265,11 @@ exports.getApp = (files, userConfRoot) => {
   });
 };
 
-/*
- * Helper to find lando files we can use
+/**
+ * Finds Landofile candidates by walking upward from a starting directory.
+ * @param {string[]} [files] Candidate file basenames.
+ * @param {string} [startFrom] Starting directory.
+ * @returns {string[]} Existing Landofile paths.
  */
 exports.getLandoFiles = (files = [], startFrom = process.cwd()) => _(files)
     .flatMap(file => traverseUp(path.resolve(startFrom, file)))
@@ -188,11 +280,12 @@ exports.getLandoFiles = (files = [], startFrom = process.cwd()) => _(files)
     .filter(file => fs.existsSync(file))
     .value();
 
-/*
- * Helper to parse tasks
- * @NOTE: if this is being run we assume the existence of cacheTasksFile
- * @NOTE: i guess we are not really factoring in whether lando-tooling is disabled or not?
- * @TODO: do we need some validation of the dumped tasks here?
+/**
+ * Builds tooling task metadata from cached and in-config tooling definitions.
+ * @param {RuntimeConfig} [config] App config.
+ * @param {ParsedArgv} [argv] Parsed argv.
+ * @param {object[]} [tasks] Existing task list.
+ * @returns {object[]} Tooling task metadata.
  */
 exports.getTasks = (config = {}, argv = {}, tasks = []) => {
   // If we have a tooling router lets rebase on that
@@ -236,8 +329,11 @@ exports.getTasks = (config = {}, argv = {}, tasks = []) => {
   return tasks.concat(loadCacheFile(process.landoTaskCacheFile));
 };
 
-/*
- * Helper to setup cache
+/**
+ * Creates the runtime cache and ensures a persistent user id exists.
+ * @param {import('./logger')} log Logger instance.
+ * @param {RuntimeConfig} config Runtime config.
+ * @returns {import('./cache')} Cache instance.
  */
 exports.setupCache = (log, config) => {
   const Cache = require('./cache');
@@ -248,8 +344,15 @@ exports.setupCache = (log, config) => {
   return cache;
 };
 
-/*
- * Helper to setup engine
+/**
+ * Creates the engine abstraction used for docker and compose operations.
+ * @param {RuntimeConfig} config Runtime config.
+ * @param {import('./cache')} cache Cache instance.
+ * @param {import('./events')} events Event emitter.
+ * @param {import('./logger')} log Logger instance.
+ * @param {import('./shell')} shell Shell helper.
+ * @param {string} id Runtime instance id.
+ * @returns {import('./engine')} Engine instance.
  */
 exports.setupEngine = (config, cache, events, log, shell, id) => {
   const Engine = require('./engine');

package/node_modules/lando/lib/cache.js

@@ -10,21 +10,22 @@ const {join} = require('node:path');
 
 /**
  * Creates a new Cache instance.
- *
- * @property {Log} log A log instance
- * @property {string} cacheDir The directory to store cache files in
+ * @property {Log} log Logger instance.
+ * @property {string} cacheDir Directory used for file-backed cache entries.
  */
 module.exports = class Cache extends NodeCache {
   /**
-   * @param {Object} [opts] Options to pass into the cache
-   * @param {Log} [opts.log] A log instance
-   * @param {string} [opts.cacheDir] The directory to store cache files in
+   * @param {object} [opts] Options to pass into the cache.
+  * @param {Log} [opts.log] Logger instance.
+   * @param {string} [opts.cacheDir] Directory used for file-backed cache entries.
    */
   constructor({log = new Log(), cacheDir = join(tmpdir(), '.cache')} = {}) {
     // Get the nodecache opts
     super();
     // Set some things
+    /** @type {Log} */
     this.log = log;
+    /** @type {string} */
     this.cacheDir = cacheDir;
     // Ensure the cache dir exists
     mkdirSync(this.cacheDir, {recursive: true});
@@ -32,14 +33,13 @@ module.exports = class Cache extends NodeCache {
 
   /**
    * Sets an item in the cache
-   *
    * @since 3.0.0
    * @alias lando.cache.set
    * @param {string} key The name of the key to store the data with.
-   * @param {any} data The data to store in the cache.
-   * @param {Object} [opts] Options to pass into the cache
-   * @param {boolean} [opts.persist=false] Whether this cache data should persist between processes. Eg in a file instead of memory
-   * @param {number} [opts.ttl=0] Seconds the cache should live. 0 mean forever.
+   * @param {unknown} data The data to store in the cache.
+   * @param {object} [opts] Options to pass into the cache.
+   * @param {boolean} [opts.persist] Whether this cache data should persist between processes.
+   * @param {number} [opts.ttl] Seconds the cache should live; `0` means forever.
    * @example
    * // Add a string to the cache
    * lando.cache.set('mykey', 'mystring');
@@ -80,11 +80,10 @@ module.exports = class Cache extends NodeCache {
 
   /**
    * Gets an item in the cache
-   *
    * @since 3.0.0
    * @alias lando.cache.get
    * @param {string} key The name of the key to retrieve the data.
-   * @return {any} The data stored in the cache if applicable.
+   * @returns {unknown} The data stored in the cache if applicable.
    * @example
    * // Get the data stored with key mykey
    * const data = lando.cache.get('mykey');
@@ -103,16 +102,16 @@ module.exports = class Cache extends NodeCache {
         return readFileSync(join(this.cacheDir, key));
       } catch {
         this.log.debug('File cache miss with key %s', key);
+        return undefined;
       }
     }
   }
 
   /**
    * Manually remove an item from the cache.
-   *
    * @since 3.0.0
    * @alias lando.cache.remove
-   * @param {String} key The name of the key to remove the data.
+   * @param {string} key The name of the key to remove the data.
    * @example
    * // Remove the data stored with key mykey
    * lando.cache.remove('mykey');