@automattic/vip 4.1.5 → 4.1.8

package/node_modules/lando/lib/engine.js

@@ -5,15 +5,114 @@ const LandoDaemon = require('./daemon');
 const Landerode = require('./docker');
 const router = require('./router');
 
-/*
- * @TODO
+/**
+ * Engine initialization config.
+ * @typedef {object} EngineConfig
+ * @property {string|false} [composeBin] Docker Compose binary path or disabled flag.
+ */
+
+/**
+ * Common options passed to engine task descriptors.
+ * @typedef {object} EngineTaskOptions
+ * @property {boolean} [autoRemove] Automatically remove the container after execution.
+ * @property {boolean} [background] Start services in the background.
+ * @property {Array<string|null>} [cstdio] Custom stdio configuration.
+ * @property {boolean} [detach] Run the process in the background.
+ * @property {Record<string, string>} [environment] Additional environment variables.
+ * @property {boolean} [follow] Follow the log stream like `tail -f`.
+ * @property {boolean} [force] Force container removal.
+ * @property {boolean} [hijack] Whether the shell execution should hijack stdio.
+ * @property {string} [id] Target container id.
+ * @property {boolean} [last] Whether this is the final task in a sequence.
+ * @property {string[]} [local] Services that should be treated as local-only.
+ * @property {'collect'|'attach'} [mode] Shell execution mode.
+ * @property {boolean} [noCache] Ignore the build cache.
+ * @property {string|string[]} [pre] Arguments to prepend before the user command.
+ * @property {boolean} [prestart] Whether the task runs before container startup.
+ * @property {boolean} [pull] Try to pull images first.
+ * @property {string[]} [pullable] Services that may be pulled.
+ * @property {boolean} [purge] Also imply volume and force removal.
+ * @property {boolean} [recreate] Recreate services.
+ * @property {boolean} [removeOrphans] Remove orphaned containers.
+ * @property {string[]} [services] Target services.
+ * @property {boolean} [silent] Suppress shell output.
+ * @property {boolean} [timestamps] Show timestamps in output.
+ * @property {string} [user] User, `user:group`, `uid`, or `uid:gid`.
+ * @property {boolean} [volumes] Remove associated volumes.
+ * @property {string} [workdir] Working directory inside the container.
+ */
+
+/**
+ * Generic engine task descriptor.
+ * @typedef {object} EngineTaskData
+ * @property {string|string[]} [cmd] Command string or argv parts.
+ * @property {string[]} [compose] Array of Docker Compose file paths.
+ * @property {string} [id] Docker-recognizable id, name, or cid.
+ * @property {EngineTaskOptions} [opts] Task options.
+ * @property {string} [project] Project name, usually the app name.
+ */
+
+/**
+ * Compose-backed engine task descriptor.
+ * @typedef {object} EngineComposeTaskData
+ * @property {string[]} compose Array of Docker Compose file paths.
+ * @property {EngineTaskOptions} [opts] Task options.
+ * @property {string} project Project name, usually the app name.
+ */
+
+/**
+ * Engine task descriptor for container command execution.
+ * @typedef {object} EngineRunTaskData
+ * @property {string|string[]} cmd Command string or argv parts.
+ * @property {string[]} [compose] Array of Docker Compose file paths.
+ * @property {string} id Container id or name to run against.
+ * @property {EngineTaskOptions} [opts] Command execution options.
+ * @property {string} [project] Project name, usually the app name.
+ */
+
+/**
+ * Options for listing Lando containers.
+ * @typedef {object} EngineListOptions
+ * @property {boolean} [all] Show even stopped containers.
+ * @property {string} [app] Show containers for only one app.
+ * @property {string[]} [filter] Additional `key=value` filters.
+ */
+
+/**
+ * Options passed to Docker network listing.
+ * @typedef {object} DockerNetworkListOptions
+ * @property {object} [filters] Filter options.
+ */
+
+/**
+ * Engine compose command runner.
+ * @typedef {function(string, EngineTaskData): Promise<unknown>} ComposeCommandRunner
+ */
+
+/**
+ * Engine service metadata returned from docker inspection.
+ * @typedef {Record<string, unknown>} EngineServiceMetadata
+ */
+
+/**
+ * Engine wrapper around router, daemon, docker, and compose operations.
  */
 module.exports = class Engine {
   // @TODO: We need to figure out compose a bit better here, there is no default option right now, see similar comments in ./lando.js
+  /**
+   * @param {LandoDaemon} [daemon] Daemon adapter instance.
+   * @param {Landerode} [docker] Docker adapter instance.
+   * @param {ComposeCommandRunner} [compose] Compose command runner.
+   * @param {EngineConfig} [config] Engine config.
+   */
   constructor(daemon = new LandoDaemon(), docker = new Landerode(), compose = () => {}, config = {}) {
+    /** @type {Landerode} */
     this.docker = docker;
+    /** @type {LandoDaemon} */
     this.daemon = daemon;
+    /** @type {ComposeCommandRunner} */
     this.compose = compose;
+    /** @type {function(string, EngineTaskData|EngineTaskData[], function(): (Promise<unknown>|object|void)): Promise} */
     this.engineCmd = (name, data, run = () => router[name](data, this.compose, this.docker)) => router.eventWrapper(
         name,
         daemon,
@@ -22,46 +121,34 @@ module.exports = class Engine {
         run,
     );
     // Determine install status
+    /** @type {boolean} */
     this.composeInstalled = config.composeBin !== false;
+    /** @type {boolean} */
     this.dockerInstalled = this.daemon.docker !== false;
-    // Grab the supported ranges for our things
-    this.supportedVersions = config.dockerSupportedVersions;
   };
 
   /**
    * Event that allows you to do some things before a `compose` object's containers are
    * built
-   *
    * @since 3.0.0
-   * @alias lando.events:pre-engine-build
    * @event pre_engine_build
    */
   /**
    * Event that allows you to do some things after a `compose` object's containers are
    * built
-   *
    * @since 3.0.0
-   * @alias lando.events:post-engine-build
    * @event post_engine_build
    */
   /**
    * Tries to pull the services for a `compose` object, and then tries to build them if they are found
    * locally. This is a wrapper around `docker pull` and `docker build`.
-   *
    * **NOTE:** Generally an instantiated `App` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.build
    * @fires pre_engine_build
    * @fires post_engine_build
-   * @param {Object} data A `compose` Object or an Array of `compose` Objects if you want to build more than one set of services.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} [data.opts] Options on how to build the `compose` objects containers.
-   * @param {Array} [data.opts.services='all services'] The services to build.
-   * @param {Boolean} [data.opts.nocache=true] Ignore the build cache.
-   * @param {Boolean} [data.opts.pull=true] Try to pull first.
-   * @return {Promise} A Promise.
+   * @param {EngineComposeTaskData|import('./app')} data Compose object or array item wrapper.
+   * @returns {Promise} A promise.
    * @example
    * return lando.engine.build(app);
    */
@@ -71,13 +158,12 @@ module.exports = class Engine {
 
   /**
    * Creates a Docker network
-   *
-   * @since 3.0.0.
+   * @since 3.0.0
    * @function
    * @alias lando.engine.createNetwork
    * @see [docker api network docs](https://docs.docker.com/engine/api/v1.35/#operation/NetworkCreate) for info on opts.
-   * @param {String} name The name of the networks
-   * @return {Promise} A Promise with inspect data.
+   * @param {string} name The network name.
+   * @returns {Promise} A promise with inspect data.
    * @example
    * return lando.engine.createNetwork('mynetwork')
    */
@@ -87,47 +173,29 @@ module.exports = class Engine {
 
   /**
    * Event that allows you to do some things before some containers are destroyed.
-   *
    * @since 3.0.0
-   * @alias lando.events:pre-engine-destroy
    * @event pre_engine_destroy
    */
   /**
    * Event that allows you to do some things after some containers are destroyed.
-   *
    * @since 3.0.0
-   * @alias lando.events:post-engine-destroy
    * @event post_engine_destroy
    */
   /**
    * Removes containers for a `compose` object or a particular container.
-   *
    * There are two ways to remove containers:
-   *
    *  1. Using an object with `{id: id}` where `id` is a docker recognizable id
    *  2. Using a `compose` object with `{compose: compose, project: project, opts: opts}`
-   *
    * These are detailed more below.
-   *
    * **NOTE:** Generally an instantiated `App` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.destroy
    * @fires pre_engine_destroy
    * @fires post_engine_destroy
-   * @param {Object} data Remove criteria, Need eithers an ID or a service within a compose context
-   * @param {String} data.id An id that docker can recognize such as a container hash or name. Can also use `data.name` or `data.cid`.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} [data.opts] Options on what services to remove.
-   * @param {Array} [data.opts.services='all services'] An Array of services to remove.
-   * @param {Boolean} [data.opts.volumes=true] Also remove volumes associated with the container(s).
-   * @param {Boolean} [data.opts.force=false] Force remove the containers.
-   * @param {Boolean} [data.opts.purge=false] Implies `volumes` and `force`.
-   * @return {Promise} A Promise.
+   * @param {EngineTaskData|import('./app')} data Remove criteria for a container or compose context.
+   * @returns {Promise} A promise.
    * @example
    * return lando.engine.destroy(app);
-   *
    */
   destroy(data) {
     return this.engineCmd('destroy', data);
@@ -135,25 +203,15 @@ module.exports = class Engine {
 
   /**
    * Checks whether a specific service exists or not.
-   *
    * There are two ways to check whether a container exists:
-   *
    *  1. Using an object with `{id: id}` where `id` is a docker recognizable id
    *  2. Using a `compose` object with `{compose: compose, project: project, opts: opts}`
-   *
    * These are detailed more below.
-   *
    * **NOTE:** Generally an instantiated `app` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.exists
-   * @param {Object} data Search criteria, Need eithers an ID or a service within a compose context
-   * @param {String} data.id An id that docker can recognize such as a container hash or name. Can also use `data.name` or `data.cid`.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} data.opts Options on what service to check
-   * @param {Array} data.opts.services An Array of services to check
-   * @return {Promise} A Promise with a Boolean of whether the service exists or not.
+   * @param {EngineTaskData|import('./app')} data Search criteria for a container or compose context.
+   * @returns {Promise<boolean>} Promise resolving to whether the service exists.
    * @example
    * return lando.engine.exists(compose);
    */
@@ -163,12 +221,11 @@ module.exports = class Engine {
 
   /**
    * Gets a Docker network
-   *
-   * @since 3.0.0.
+   * @since 3.0.0
    * @function
    * @alias lando.engine.getNetwork
-   * @param {String} id The id of the network
-   * @return {Object} A Dockerode Network object .
+   * @param {string} id The network id.
+   * @returns {import('dockerode').Network} Dockerode network object.
    * @example
    * const network = lando.engine.getNetwork('mynetwork')
    */
@@ -178,14 +235,12 @@ module.exports = class Engine {
 
   /**
    * Gets the docker networks.
-   *
    * @since 3.0.0
    * @function
    * @alias lando.engine.getNetworks
    * @see [docker api network docs](https://docs.docker.com/engine/api/v1.27/#operation/NetworkList) for info on filters option.
-   * @param {Object} [opts] Options to pass into the docker networks call
-   * @param {Object} [opts.filters] Filters options
-   * @return {Promise} A Promise with an array of network objects.
+   * @param {DockerNetworkListOptions} [opts] Options for the Docker networks call.
+   * @returns {Promise<object[]>} Promise resolving to network objects.
    */
   getNetworks(opts) {
     return this.docker.listNetworks(opts);
@@ -193,13 +248,11 @@ module.exports = class Engine {
 
   /**
    * Determines whether a container is running or not
-   *
    * @since 3.0.0
    * @alias lando.engine.isRunning
-   * @param {String} data An ID that docker can recognize such as the container id or name.
-   * @return {Promise} A Promise with a boolean of whether the container is running or not
+   * @param {string} data Docker-recognizable container id or name.
+   * @returns {Promise<boolean>} Promise resolving to whether the container is running.
    * @example
-   *
    * // Check to see if our app's web service is running
    * return lando.engine.isRunning('myapp-web-1').then(isRunning) {
    *   lando.log.info('Container %s is running: %s', 'myapp-web-1', isRunning);
@@ -211,14 +264,10 @@ module.exports = class Engine {
 
   /**
    * Lists all the Lando containers. Optionally filter by app name.
-   *
    * @since 3.0.0
    * @alias lando.engine.list
-   * @param {Object} [options] Options to filter the list.
-   * @param {Boolean} [options.all=false] Show even stopped containers
-   * @param {String} [options.app] Show containers for only a certain app
-   * @param {Array} [options.filter] Filter by additional key=value pairs
-   * @return {Promise} A Promise with an Array of container Objects.
+   * @param {EngineListOptions} [options] Options to filter the list.
+   * @returns {Promise<object[]>} Promise resolving to container objects.
    * @example
    * return lando.engine.list().each(function(container) {
    *   lando.log.info(container);
@@ -230,20 +279,12 @@ module.exports = class Engine {
 
   /**
    * Returns logs for a given `compose` object
-   *
    * **NOTE:** Generally an instantiated `app` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.logs
-   * @param {Object} data A `compose` Object or an Array of `compose` Objects if you want to get logs for more than one set of services.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} [data.opts] Options on how to build the `compose` objects containers.
-   * @param {Boolean} [data.opts.follow=false] Whether to follow the log. Works like `tail -f`.
-   * @param {Boolean} [data.opts.timestamps=true] Show timestamps in log.
-   * @return {Promise} A Promise.
+   * @param {EngineComposeTaskData|import('./app')} data Compose object or array item wrapper.
+   * @returns {Promise} A promise.
    * @example
-   *
    * // Get logs for an app
    * return lando.engine.logs(app);
    */
@@ -254,46 +295,29 @@ module.exports = class Engine {
   /**
    * Event that allows you to do some things before a command is run on a particular
    * container.
-   *
    * @since 3.0.0
-   * @alias lando.events:pre-engine-run
    * @event pre_engine_run
    */
   /**
    * Event that allows you to do some things after a command is run on a particular
    * container.
-   *
    * @since 3.0.0
-   * @alias lando.events:post-engine-run
    * @event post_engine_run
    */
   /**
    * Runs a command on a given service/container. This is a wrapper around `docker exec`.
-   *
    * UNTIL the resolution of https://github.com/apocas/docker-modem/issues/83 data needs to also be or be an
    * array of compose objects for this to work correctly on Windows as well. See some of the other engine
    * documentation for what a compose object looks like.
-   *
    * @since 3.0.0
    * @alias lando.engine.run
    * @fires pre_engine_run
    * @fires post_engine_run
-   * @param {Object} data A run Object or an Array of run Objects if you want to run more than one command.
-   * @param {String} data.id The container to run the command on. Must be an id that docker can recognize such as a container hash or name.
-   * @param {String} data.cmd A String of a command or an Array whose elements are the parts of the command.
-   * @param {Object} [data.opts] Options on how to run the command.
-   * @param {String} [data.opts.mode='collect'] Either `collect` or `attach`. Attach will connect to the run `stdin`.
-   * @param {String} [data.opts.pre] A String or Array of additional arguments or options to append to the `cmd` before the user specified args and options are added.
-   * @param {Array} [data.opts.env=[]] Additional environmental variables to set for the cmd. Must be in the form `KEY=VALUE`.
-   * @param {String} [data.opts.user='root'] The user to run the command as. Can also be `user:group` or `uid` or `uid:gid`.
-   * @param {String} [data.opts.detach=false] Run the process in the background
-   * @param {String} [data.opts.autoRemove=false] Automatically removes the container
-   * @return {Promise} A Promise with a string containing the command's output.
+   * @param {EngineRunTaskData} data Run object or array item wrapper.
+   * @returns {Promise} Promise resolving with command output.
    * @example
-   *
    * // Run composer install on the appserver container for an app called myapp
    * return lando.engine.run({id: 'myapp-appserver-1', cmd: ['composer', 'install']});
-   *
    * // Drop into an interactive bash shell on the database continer for an app called myapp
    * return lando.engine.run({
    *   id: 'myapp-database-1',
@@ -309,25 +333,15 @@ module.exports = class Engine {
 
   /**
    * Returns comprehensive service metadata. This is a wrapper around `docker inspect`.
-   *
    * There are two ways to get container metadata:
-   *
    *  1. Using an object with `{id: id}` where `id` is a docker recognizable id
    *  2. Using a `compose` object with `{compose: compose, project: project, opts: opts}`
-   *
    * These are detailed more below.
-   *
    * **NOTE:** Generally an instantiated `app` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.scan
-   * @param {Object} data Search criteria, Need eithers an ID or a service within a compose context
-   * @param {String} data.id An id that docker can recognize such as a container hash or name. Can also use `data.name` or `data.cid`.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} data.opts Options on what service to scan
-   * @param {Array} data.opts.services An Array of services to scan.
-   * @return {Promise} A Promise with an Object of service metadata.
+   * @param {EngineTaskData|import('./app')} data Search criteria for a container or compose context.
+   * @returns {Promise<EngineServiceMetadata>} Promise resolving to service metadata.
    * @example
    * // Log scan data using an id
    * return lando.engine.scan({id: '146d321f212d'}).then(function(data) {
@@ -341,37 +355,24 @@ module.exports = class Engine {
   /**
    * Event that allows you to do some things before a `compose` Objects containers are
    * started
-   *
    * @since 3.0.0
-   * @alias lando.events:pre-engine-start
    * @event pre_engine_start
    */
   /**
    * Event that allows you to do some things after a `compose` Objects containers are
    * started
-   *
    * @since 3.0.0
-   * @alias lando.events:post-engine-start
    * @event post_engine_start
    */
   /**
    * Starts the containers/services for the specified `compose` object.
-   *
    * **NOTE:** Generally an instantiated `app` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.start
    * @fires pre_engine_start
    * @fires post_engine_start
-   * @param {Object} data A `compose` Object or an Array of `compose` Objects if you want to start more than one set of services.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} [data.opts] Options on how to start the `compose` Objects containers.
-   * @param {Array} [data.opts.services='all services'] The services to start.
-   * @param {Boolean} [data.opts.background=true] Start the services in the background.
-   * @param {Boolean} [data.opts.recreate=false] Recreate the services.
-   * @param {Boolean} [data.opts.removeOrphans=true] Remove orphaned containers.
-   * @return {Promise} A Promise.
+   * @param {EngineComposeTaskData|import('./app')} data Compose object or array item wrapper.
+   * @returns {Promise} A promise.
    * @example
    * return lando.engine.start(app);
    */
@@ -381,41 +382,27 @@ module.exports = class Engine {
 
   /**
    * Event that allows you to do some things before some containers are stopped.
-   *
    * @since 3.0.0
-   * @alias lando.events:pre-engine-stop
    * @event pre_engine_stop
    */
   /**
    * Event that allows you to do some things after some containers are stopped.
-   *
    * @since 3.0.0
-   * @alias lando.events:post-engine-stop
    * @event post_engine_stop
    */
   /**
    * Stops containers for a `compose` object or a particular container.
-   *
    * There are two ways to stop containers:
-   *
    *  1. Using an object with `{id: id}` where `id` is a docker recognizable id
    *  2. Using a `compose` object with `{compose: compose, project: project, opts: opts}`
-   *
    * These are detailed more below.
-   *
    * **NOTE:** Generally an instantiated `app` instance is a valid `compose` object
-   *
    * @since 3.0.0
    * @alias lando.engine.stop
    * @fires pre_engine_stop
    * @fires post_engine_stop
-   * @param {Object} data Stop criteria, Need eithers an ID or a service within a compose context
-   * @param {String} data.id An id that docker can recognize such as a container hash or name. Can also use `data.name` or `data.cid`.
-   * @param {Array} data.compose An Array of paths to Docker compose files
-   * @param {String} data.project A String of the project name (Usually this is the same as the app name)
-   * @param {Object} [data.opts] Options on what services to setop
-   * @param {Array} [data.opts.services='all services'] An Array of services to stop.
-   * @return {Promise} A Promise.
+   * @param {EngineTaskData|import('./app')} data Stop criteria for a container or compose context.
+   * @returns {Promise} A promise.
    * @example
    * return lando.engine.stop(app);
    */

package/node_modules/lando/lib/env.js

@@ -2,10 +2,15 @@
 
 // Modules
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const shell = require('shelljs');
 
+/**
+ * Searches known directories and the current PATH for an executable.
+ * @param {string} file Executable filename.
+ * @param {string[]} paths Directories to inspect before PATH lookup.
+ * @returns {string|false} Absolute executable path or false.
+ */
 const findFileInPath = (file, paths) => {
   const join = (process.platform === 'win32') ? path.win32.join : path.posix.join;
   const normalize = (process.platform === 'win32') ? path.win32.normalize : path.posix.normalize;
@@ -25,8 +30,10 @@ const findFileInPath = (file, paths) => {
   return (possiblePath !== null) ? normalize(possiblePath.toString()) : false;
 };
 
-/*
- * Helper to get location of docker bin directory
+/**
+ * Gets the directory that contains the docker executable.
+ * @param {boolean} [fresh] Whether to bypass the cached executable path.
+ * @returns {string|false} Directory path or false.
  */
 exports.getDockerBinPath = (fresh = false) => {
   const dirname = (process.platform === 'win32') ? path.win32.dirname : path.posix.dirname;
@@ -34,8 +41,10 @@ exports.getDockerBinPath = (fresh = false) => {
   return fullPath ? dirname(fullPath) : false;
 };
 
-/*
- * Helper to get location of docker bin directory
+/**
+ * Gets the directory that contains the docker compose executable.
+ * @param {boolean} [fresh] Whether to bypass the cached executable path.
+ * @returns {string|false} Directory path or false.
  */
 exports.getDockerComposeBinPath = (fresh = false) => {
   const dirname = (process.platform === 'win32') ? path.win32.dirname : path.posix.dirname;
@@ -43,10 +52,13 @@ exports.getDockerComposeBinPath = (fresh = false) => {
   return fullPath ? dirname(fullPath) : false;
 };
 
+/** @type {string|false|undefined} */
 let cachedComposeExecutable;
 
-/*
- * Get docker compose binary path
+/**
+ * Locates the docker compose executable for the current platform.
+ * @param {boolean} [fresh] Whether to bypass the cached executable path.
+ * @returns {string|false} Absolute executable path or false.
  */
 exports.getComposeExecutable = (fresh = false) => {
   if (cachedComposeExecutable && !fresh) {
@@ -82,8 +94,14 @@ exports.getComposeExecutable = (fresh = false) => {
   return cachedComposeExecutable;
 };
 
+/** @type {string|false|undefined} */
 let cachedDockerExecutable;
 
+/**
+ * Locates the docker executable for the current platform.
+ * @param {boolean} [fresh] Whether to bypass the cached executable path.
+ * @returns {string|false} Absolute executable path or false.
+ */
 exports.getDockerExecutable = (fresh = false) => {
   if (cachedDockerExecutable && !fresh) {
     return cachedDockerExecutable;
@@ -123,42 +141,3 @@ exports.getDockerExecutable = (fresh = false) => {
   return cachedDockerExecutable;
 };
 
-/*
- * Get oclif home dir based on platform
- */
-const getOClifHome = () => {
-  switch (process.platform) {
-    case 'darwin':
-    case 'linux':
-      return process.env.HOME || os.homedir() || os.tmpdir();
-    case 'win32':
-      return process.env.HOME ||
-        (process.env.HOMEDRIVE && process.env.HOMEPATH && path.join(process.env.HOMEDRIVE, process.env.HOMEPATH)) ||
-        process.env.USERPROFILE ||
-        os.homedir() ||
-        os.tmpdir();
-  }
-};
-
-/*
- * Get oclif base dir based on platform
- */
-const getOClifBase= product => {
-  const base = process.env['XDG_CACHE_HOME'] ||
-    (process.platform === 'win32' && process.env.LOCALAPPDATA) ||
-    path.join(getOClifHome(), '.cache');
-  return path.join(base, product);
-};
-
-const macosCacheDir = product => {
-  return process.platform === 'darwin' ? path.join(getOClifHome(), 'Library', 'Caches', product) : undefined;
-};
-
-/*
- * This should only be needed for linux
- */
-exports.getOclifCacheDir = product => {
-  return process.env[`${product.toUpperCase()}_CACHE_DIR`] ||
-    macosCacheDir(product) ||
-    getOClifBase(product);
-};

package/node_modules/lando/lib/error.js

@@ -3,20 +3,29 @@
 // Modules
 const Log = require('./logger');
 
+/**
+ * Error handler wrapper for logging and exit-code resolution.
+ */
 module.exports = class ErrorHandler {
+  /**
+   * @param {Log} [log] Logger instance.
+   */
   constructor(log = new Log()) {
+    /** @type {Log} */
     this.log = log;
   };
 
   /**
-   * Returns the lando options
-   *
-   * This means all the options passed in before the `--` flag.
-   *
+   * Handles a runtime error and resolves the exit code to use.
    * @since 3.0.0
    * @alias lando.error.handle
-   * @param {Object} error Error object
-   * @return {Promise<number>} the error code
+   * @param {object} [error] Error payload.
+   * @param {string} [error.message] Error message to log.
+   * @param {string} [error.stack] Full error stack.
+   * @param {number} [error.code] Process exit code.
+   * @param {boolean} [error.hide] Whether logging should be suppressed.
+   * @param {number} [error.verbose] Verbosity level.
+   * @returns {Promise<number>} Promise resolving to the error code.
    * @todo make this static and then fix all call sites
    */
   handle({message, stack, code = 1, hide = false, verbose = 0} = {}) {

package/node_modules/lando/lib/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/node_modules/lando/lib/esm/string-argv.js

@@ -0,0 +1,2 @@
+// Node 22 can load this bridge synchronously while selecting the package's import entry.
+export {parseArgsStringToArgv} from 'string-argv';

package/node_modules/lando/lib/esm/yargs.js

@@ -0,0 +1,2 @@
+// Expose the same factory to CommonJS callers and pkg-transformed modules.
+export {default} from 'yargs';