@percy/cli-command 1.0.0-beta.76 → 1.0.0

package/README.md

@@ -14,7 +14,7 @@ The `command` function accepts a name, definition, and callback and returns a ru
 accepts an array of command-line arguments.
 
 ``` js
-const { command } = require('@percy/cli-command');
+import command from '@percy/cli-command';
 
 // example command runner
 const example = command('example', {

package/bin/readme

@@ -1,23 +1,21 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const { formatHelp } = require('@percy/cli-command/dist/help');
-
-const CWD = process.cwd();
-const README = path.join(CWD, 'README.md');
-
-const HELP_USAGE = /^(.*)?(usage:.*)$/gis;
-const CMDS_TMPL = /(<!-- commands -->)(.*)(<!-- commandsstop -->)/is;
-
-async function generateReadmeCommands(pkg) {
-  if (!pkg['@percy/cli']?.commands) return '';
+const fs = await import('fs');
+const path = await import('path');
+const { formatHelp } = await import('../dist/help');
 
+async function updateReadmeCommands(cwd = process.cwd()) {
+  let readmePath = path.join(cwd, 'README.md');
+  let pkgPath = path.join(cwd, 'package.json');
   let sections = [];
   let toc = [];
 
+  let pkg = JSON.parse(fs.readFileSync(pkgPath));
+  if (!pkg['@percy/cli']?.commands) return '';
+
   for (let cmdPath of pkg['@percy/cli'].commands) {
-    let { default: command } = require(path.join(CWD, cmdPath));
+    let cmdURL = url.pathToFileURL(path.join(CWD, cmdPath));
+    let { default: command } = await import(cmdURL.href);
     command = { ...command, parent: { name: 'percy' } };
 
     for (let cmd of [command, ...(command.definition.commands || [])]) {
@@ -30,22 +28,15 @@ async function generateReadmeCommands(pkg) {
       toc.push(`* [${title}](#${slug})`);
 
       let help = await formatHelp(cmd);
-      help = help.replace(HELP_USAGE, '$1```\n$2```');
+      help = help.replace(/^(.*)?(usage:.*)$/gis, '$1```\n$2```');
       sections.push(`### ${title}\n\n${help}\n`);
     }
   }
 
-  return [
-    toc.join('\n'),
-    sections.join('\n')
-  ].join('\n\n');
-}
-
-async function updatePackageReadme() {
-  let pkg = require(path.join(CWD, 'package.json'));
-  let content = fs.readFileSync(README, 'utf8')
-    .replace(CMDS_TMPL, `$1\n${await generateReadmeCommands(pkg)}$3`)
-  fs.writeFileSync(README, content);
+  fs.writeFileSync(readmePath, fs.readFileSync(readmePath, 'utf-8').replace(
+    /(<!-- commands -->)(.*)(<!-- commandsstop -->)/is,
+    `$1\n${[toc.join('\n'), sections.join('\n')].join('\n\n')}$3`
+  ));
 }
 
-updatePackageReadme();
+updateReadmeCommands();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/cli-command",
-  "version": "1.0.0-beta.76",
+  "version": "1.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,15 +10,21 @@
   "publishConfig": {
     "access": "public"
   },
-  "main": "dist/index.js",
-  "bin": {
-    "percy-cli-readme": "bin/readme"
-  },
   "files": [
-    "dist"
+    "./dist"
   ],
   "engines": {
-    "node": ">=12"
+    "node": ">=14"
+  },
+  "bin": {
+    "percy-cli-readme": "./bin/readme"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils": "./dist/utils.js",
+    "./test/helpers": "./test/helpers.js"
   },
   "scripts": {
     "build": "node ../../scripts/build",
@@ -27,9 +33,9 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/config": "1.0.0-beta.76",
-    "@percy/core": "1.0.0-beta.76",
-    "@percy/logger": "1.0.0-beta.76"
+    "@percy/config": "1.0.0",
+    "@percy/core": "1.0.0",
+    "@percy/logger": "1.0.0"
   },
-  "gitHead": "445af68d8e270e2a35fc74e26422ed5d3c91d2ae"
+  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
 }

package/dist/command.js

@@ -1,240 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.command = command;
-exports.default = void 0;
-
-var _logger = _interopRequireDefault(require("@percy/logger"));
-
-var _config = _interopRequireDefault(require("@percy/config"));
-
-var _utils = require("@percy/config/dist/utils");
-
-var CoreConfig = _interopRequireWildcard(require("@percy/core/dist/config"));
-
-var builtInFlags = _interopRequireWildcard(require("./flags"));
-
-var _help = _interopRequireDefault(require("./help"));
-
-var _parse = _interopRequireDefault(require("./parse"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
-
-function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
-
-// Copies a command definition and adds built-in flags and config options.
-function withBuiltIns(definition) {
-  var _def$flags, _def$config$schemas, _def$config$migration;
-
-  let def = { ...definition
-  };
-  def.flags = [...((_def$flags = def.flags) !== null && _def$flags !== void 0 ? _def$flags : [])]; // ensure built-ins aren't already overridden
-
-  let addDedupedFlag = flag => {
-    if (!def.flags.find(f => f.name === flag.name)) {
-      let short = def.flags.find(f => f.short === flag.short);
-      def.flags.push(short ? (0, _utils.del)({ ...flag
-      }, 'short') : flag);
-    }
-  }; // add percy specific built-in flags
-
-
-  if (def.percy && def.percy !== true) {
-    builtInFlags.PERCY.forEach(addDedupedFlag); // maybe include percy discovery flags
-
-    if (def.percy.discoveryFlags !== false) {
-      builtInFlags.DISCOVERY.forEach(addDedupedFlag);
-    }
-  } // always add global built-in flags
-
-
-  builtInFlags.GLOBAL.forEach(addDedupedFlag); // copy any existing config before adding to it
-
-  def.config = { ...def.config
-  };
-  def.config.schemas = [...((_def$config$schemas = def.config.schemas) !== null && _def$config$schemas !== void 0 ? _def$config$schemas : [])];
-  def.config.migrations = [...((_def$config$migration = def.config.migrations) !== null && _def$config$migration !== void 0 ? _def$config$migration : [])]; // add percy specific built-in config options
-
-  if (def.percy) {
-    def.config.schemas.unshift(...CoreConfig.schemas);
-    def.config.migrations.unshift(...CoreConfig.migrations);
-  }
-
-  return def;
-} // Calls the provided callback and handles callback cancelation when process signals are
-// triggered. If the provided callback returns a generator, it will automatically run and throw
-// an error when canceled to be able to gracefully handle it's own cancelation.
-
-
-async function handleProcessSignals(callback) {
-  let signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP'];
-  let signalError; // keep track of signal handlers for cleanup
-
-  let signalHandlers = signals.map(signal => {
-    let handler = () => {
-      signalError = Object.assign(new Error(signal), {
-        canceled: true,
-        exitCode: 0,
-        signal
-      });
-    };
-
-    process.on(signal, handler);
-    return [signal, handler];
-  });
-
-  try {
-    // maybe async function
-    let gen = await callback(); // run any returned generator
-
-    if (typeof (gen === null || gen === void 0 ? void 0 : gen.next) === 'function' && (typeof gen[Symbol.iterator] === 'function' || typeof gen[Symbol.asyncIterator] === 'function')) {
-      let result = await gen.next();
-
-      while (!result.done) {
-        result = signalError ? await gen.throw(signalError) : await gen.next(result.value);
-      }
-    }
-  } finally {
-    // always cleanup
-    for (let [signal, handler] of signalHandlers) {
-      process.off(signal, handler);
-    }
-  }
-} // Helper to throw an error with an exit code and optional reason message
-
-
-function exit(exitCode, reason = '') {
-  let err = reason instanceof Error ? reason : new Error(reason);
-  throw Object.assign(err, {
-    exitCode
-  });
-} // Runs the parsed command callback with a contextual argument consisting of specific parsed input
-// and other common command helpers and properties.
-
-
-async function runCommandWithContext(parsed) {
-  let {
-    command,
-    flags,
-    args,
-    argv,
-    log
-  } = parsed; // include flags, args, argv, logger, exit helper, and env info
-
-  let context = {
-    flags,
-    args,
-    argv,
-    log,
-    exit
-  };
-  let env = context.env = process.env;
-  let def = command.definition; // automatically include a preconfigured percy instance
-
-  if (def.percy) {
-    let {
-      Percy
-    } = await Promise.resolve().then(() => _interopRequireWildcard(require('@percy/core'))); // set defaults and prune preconfiguraton options
-
-    let conf = (0, _utils.del)({
-      server: false,
-      ...def.percy
-    }, 'discoveryFlags');
-    Object.defineProperty(context, 'percy', {
-      configurable: true,
-
-      get() {
-        // percy is disabled, do not return an instance
-        if (env.PERCY_ENABLE === '0') return; // redefine the context property once configured
-
-        Object.defineProperty(context, 'percy', {
-          // map and merge percy arguments with config options
-          value: new Percy([...parsed.operators.entries()].reduce((conf, [opt, value]) => opt.percyrc ? (0, _utils.set)(conf, opt.percyrc, value) : conf, conf))
-        });
-        return context.percy;
-      }
-
-    });
-  } // wrap and bind the parsed command callback
-
-
-  await handleProcessSignals(command.callback.bind(null, context));
-} // Returns a command runner function that when run will parse provided command-line options and run
-// the parsed command callback. The returned runner will automatically output version and help
-// information when requested, and handle any thrown errors exiting when appropriate.
-
-
-function command(name, definition, callback) {
-  definition = withBuiltIns(definition); // auto register config schemas and migrations
-
-  _config.default.addSchema(definition.config.schemas);
-
-  _config.default.addMigration(definition.config.migrations);
-
-  async function runner(argv = []) {
-    // reset loglevel for testing
-    _logger.default.loglevel('info');
-
-    let log = (0, _logger.default)('cli');
-
-    try {
-      // parse input
-      let parsed = await (0, _parse.default)(runner, argv);
-
-      if (parsed.version) {
-        // version requested
-        log.stdout.write(parsed.command.definition.version + '\n');
-      } else if (parsed.help || !parsed.command.callback) {
-        // command help requested
-        log.stdout.write((await (0, _help.default)(parsed.command)) + '\n');
-      } else {
-        // run command callback
-        await runCommandWithContext(parsed);
-      }
-    } catch (err) {
-      // auto log unhandled error messages
-      if (err.message && !err.signal) {
-        if (err.exitCode === 0) log.warn(err.message);else log.error(err);
-      } // exit when appropriate
-
-
-      if (err.exitCode !== 0) {
-        var _err$exitCode;
-
-        (_err$exitCode = err.exitCode) !== null && _err$exitCode !== void 0 ? _err$exitCode : err.exitCode = 1;
-        err.message || (err.message = `EEXIT: ${err.exitCode}`);
-
-        if (definition.exitOnError) {
-          process.exit(err.exitCode);
-        } // re-throw when not exiting
-
-
-        throw err;
-      }
-    }
-  } // define command meta information
-
-
-  Object.defineProperties(runner, {
-    name: {
-      enumerable: true,
-      value: name
-    },
-    definition: {
-      enumerable: true,
-      value: definition
-    },
-    callback: {
-      enumerable: true,
-      value: callback
-    }
-  });
-  return runner;
-}
-
-var _default = command;
-exports.default = _default;

package/dist/flags.js

@@ -1,99 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.verbose = exports.silent = exports.quiet = exports.networkIdleTimeout = exports.dryRun = exports.disableCache = exports.debug = exports.config = exports.allowedHostnames = exports.PERCY = exports.GLOBAL = exports.DISCOVERY = void 0;
-
-var _logger = _interopRequireDefault(require("@percy/logger"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// Global CLI flags
-const verbose = {
-  name: 'verbose',
-  description: 'Log everything',
-  exclusive: ['quiet', 'silent'],
-  parse: () => !!_logger.default.loglevel('debug'),
-  group: 'Global',
-  short: 'v'
-};
-exports.verbose = verbose;
-const quiet = {
-  name: 'quiet',
-  description: 'Log errors only',
-  exclusive: ['verbose', 'silent'],
-  parse: () => !!_logger.default.loglevel('warn'),
-  group: 'Global',
-  short: 'q'
-};
-exports.quiet = quiet;
-const silent = {
-  name: 'silent',
-  description: 'Log nothing',
-  exclusive: ['verbose', 'quiet'],
-  parse: () => !!_logger.default.loglevel('silent'),
-  group: 'Global',
-  short: 's'
-}; // Common percy and asset discovery flags
-
-exports.silent = silent;
-const config = {
-  name: 'config',
-  description: 'Config file path',
-  percyrc: 'config',
-  type: 'file',
-  group: 'Percy',
-  short: 'c'
-};
-exports.config = config;
-const dryRun = {
-  name: 'dry-run',
-  description: 'Print snapshot names only',
-  percyrc: 'dryRun',
-  group: 'Percy',
-  short: 'd'
-};
-exports.dryRun = dryRun;
-const allowedHostnames = {
-  name: 'allowed-hostname',
-  description: 'Allowed hostnames to capture in asset discovery',
-  percyrc: 'discovery.allowedHostnames',
-  type: 'hostname',
-  multiple: true,
-  group: 'Percy',
-  short: 'h'
-};
-exports.allowedHostnames = allowedHostnames;
-const networkIdleTimeout = {
-  name: 'network-idle-timeout',
-  description: 'Asset discovery network idle timeout',
-  percyrc: 'discovery.networkIdleTimeout',
-  type: 'ms',
-  parse: Number,
-  group: 'Percy',
-  short: 't'
-};
-exports.networkIdleTimeout = networkIdleTimeout;
-const disableCache = {
-  name: 'disable-cache',
-  description: 'Disable asset discovery caches',
-  percyrc: 'discovery.disableCache',
-  group: 'Percy'
-};
-exports.disableCache = disableCache;
-const debug = {
-  name: 'debug',
-  description: 'Debug asset discovery and do not upload snapshots',
-  parse: () => !!_logger.default.loglevel('debug'),
-  percyrc: 'skipUploads',
-  group: 'Percy'
-}; // Group constants
-
-exports.debug = debug;
-const GLOBAL = [verbose, quiet, silent];
-exports.GLOBAL = GLOBAL;
-const PERCY = [config, dryRun];
-exports.PERCY = PERCY;
-const DISCOVERY = [allowedHostnames, networkIdleTimeout, disableCache, debug];
-exports.DISCOVERY = DISCOVERY;

package/dist/help.js

@@ -1,262 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-exports.flagUsage = flagUsage;
-exports.formatHelp = formatHelp;
-
-var _logger = _interopRequireDefault(require("@percy/logger"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// Helper to return an argument's description including it's default value.
-function argumentDescription(arg) {
-  let desc = arg.description || '';
-
-  if (arg.default != null) {
-    desc += ` (default: ${JSON.stringify(arg.default)})`;
-  }
-
-  return desc.trim();
-} // Helper to return an array of visible argument usage-description pairs.
-
-
-async function visibleArguments(command) {
-  var _command$definition$a;
-
-  let args = (_command$definition$a = command.definition.args) !== null && _command$definition$a !== void 0 ? _command$definition$a : []; // not hidden and not deprecated
-
-  let visible = args.reduce((visible, arg) => {
-    if (arg.hidden || arg.deprecated) return visible;
-    visible.push([arg.name, argumentDescription(arg)]);
-    return visible;
-  }, []); // do not return any arguments if none have descriptions
-
-  if (!visible.some(([, desc]) => !!desc)) return [];
-  return visible;
-} // Helper to return a command's usage string.
-
-
-function commandUsage(command) {
-  let {
-    name,
-    definition
-  } = command;
-  let {
-    usage,
-    args,
-    commands
-  } = definition;
-
-  if (!command.callback && commands !== null && commands !== void 0 && commands.length) {
-    // if there are subcommands but no callback show subcommand usage
-    usage || (usage = '<command>');
-  } else {
-    var _args, _args2;
-
-    // show options followed by arguments
-    args = (_args = args) === null || _args === void 0 ? void 0 : _args.filter(a => !a.hidden && !a.deprecated).map(a => a.required ? `<${a.name}>` : `[${a.name}]`);
-    usage || (usage = `[options] ${((_args2 = args) === null || _args2 === void 0 ? void 0 : _args2.join(' ')) || ''}`);
-  }
-
-  return `${name} ${usage}`.trim();
-} // Helper to return an array of visible command usage-description pairs.
-
-
-async function visibleCommands(command, help) {
-  var _command$definition$c;
-
-  let commands = (_command$definition$c = command.definition.commands) !== null && _command$definition$c !== void 0 ? _command$definition$c : [];
-  if (typeof commands === 'function') commands = await commands();
-  let visible = [];
-
-  for (let cmd of commands) {
-    // create parent references and format subcommand names
-    let name = command.parent ? `${command.name}:${cmd.name}` : cmd.name;
-    cmd = { ...cmd,
-      name,
-      parent: command
-    }; // commands without callbacks are not visible themselves
-
-    if (cmd.callback) {
-      let {
-        description
-      } = cmd.definition;
-      visible.push([commandUsage(cmd), description]);
-    } // include visible subcommands without their implicit help
-
-
-    if (cmd.definition.commands) {
-      visible.push(...(await visibleCommands(cmd, false)));
-    }
-  } // include implicit help if there are visible commands
-
-
-  if (help !== false && visible.length) {
-    visible.push(['help [command]', 'Display command help']);
-  }
-
-  return visible;
-} // Helper to return an flags's description including it's default value.
-
-
-function flagDescription(flag) {
-  let desc = flag.description || ''; // a boolean that defaults to false will be displayed with a --no prefix
-
-  if (flag.type && flag.type !== 'boolean' && flag.default != null) {
-    desc += ` (default: ${JSON.stringify(flag.default)})`;
-  }
-
-  return desc.trim();
-} // Helper to return a flag's usage string.
-
-
-function flagUsage(flag) {
-  let {
-    short,
-    usage,
-    type
-  } = flag;
-  let term = flag.name ? `--${flag.name}` : '';
-
-  if (type && type !== 'boolean') {
-    // if there is a default it is not required
-    usage || (usage = flag.default != null ? `[${type}]` : `<${type}>`);
-  } else if (flag.default === true) {
-    // negated booleans have a prefix
-    term && (term = `--no-${flag.name}`);
-  } // add short flag usage
-
-
-  if (short) term = `-${short}${term ? `, ${term}` : ''}`;
-  return `${term} ${usage || ''}`.trim();
-} // Helper to return an array of visible flag usage-description pairs. A third entry is also included
-// with the returned pair representing any group the flag should belong to.
-
-
-async function visibleFlags(command) {
-  let flags = command.definition.flags; // not hidden and not deprecated
-
-  let visible = flags.reduce((visible, flag) => {
-    if (flag.hidden || flag.deprecated) return visible;
-    visible.push([flagUsage(flag), flagDescription(flag), flag.group]);
-    return visible;
-  }, []); // maybe hide the implicit help long or short flag (or both)
-
-  let showLongHelpFlag = !flags.some(f => f.name === 'help');
-  let showShortHelpFlag = !flags.some(f => f.short === 'h');
-
-  if (showLongHelpFlag || showShortHelpFlag) {
-    let help = {
-      name: 'help',
-      short: 'h'
-    };
-    if (!showLongHelpFlag) delete help.name;
-    if (!showShortHelpFlag) delete help.short;
-    visible.push([flagUsage(help), 'Display command help', 'Global']);
-  }
-
-  if (command.definition.version) {
-    // maybe hide the implicit version long or short flag (or both)
-    let showLongVerFlag = !flags.some(f => f.name === 'version');
-    let showShortVerFlag = !flags.some(f => f.short === 'V');
-
-    if (showLongVerFlag || showShortVerFlag) {
-      let ver = {
-        name: 'version',
-        short: 'V'
-      };
-      if (!showLongVerFlag) delete ver.name;
-      if (!showShortVerFlag) delete ver.short;
-      visible.push([flagUsage(ver), 'Display version', 'Global']);
-    }
-  }
-
-  return visible;
-} // Helper to wrap a string at a length by inserting a newline between every segment.
-
-
-function wrapString(str, len) {
-  let regex = new RegExp(`.{1,${len - 1}}(\\s|$)|\\S+?(\\s|$)`, 'g');
-  return str.replace(regex, s => s.replace(/\s*\n?$/, str.endsWith(s) ? '' : '\n'));
-} // Helper to format an option usage-description pair into a single string where the description
-// wraps within the available space beside the usage string.
-
-
-function formatOptionHelp(option, usageWidth, maxWidth) {
-  if (!option[1]) return option[0]; // calculate the available description width, at minimum 40
-
-  let descWidth = Math.max(maxWidth - usageWidth, 40); // pad usage up to the description and indent the description
-
-  return option[0].padEnd(usageWidth) + wrapString(option[1], descWidth).replace(/\n+/gm, `$&${' '.repeat(usageWidth)}`);
-} // Returns a formatted string displaying help output for the specified command. The help output
-// total width is determined by the logger's stdout TTY columns. Help output includes the command
-// description, usage, arguments, subcommand usage and descriptions, flag and flag group usage and
-// descriptions, and any command examples.
-
-
-async function formatHelp(command) {
-  var _examples, _examples2;
-
-  let {
-    name,
-    parent: top,
-    definition
-  } = command;
-  let {
-    description,
-    examples
-  } = definition;
-  let output = []; // collect visible items first to determine max usage width
-
-  let args = await visibleArguments(command);
-  let commands = await visibleCommands(command);
-  let flags = await visibleFlags(command); // maximum help output total width
-
-  let maxWidth = _logger.default.stdout.columns || 100; // calculate the longest usage width
-
-  let usageWidth = Math.max(args.reduce((max, [usage]) => Math.max(max, usage.length), 0), commands.reduce((max, [usage]) => Math.max(max, usage.length), 0), flags.reduce((max, [usage]) => Math.max(max, usage.length), 0)); // format lists of options and add appropriate indentation
-
-  let formatList = items => items.map(item => Array.isArray(item) ? // indent items and separate columns by 2 spaces each
-  formatOptionHelp(item, usageWidth + 2, maxWidth - 2) : item).join('\n').replace(/^(?!$)/gm, ' '.repeat(2)); // format the command name to include the topmost command name
-
-
-  while ((_top = top) !== null && _top !== void 0 && _top.parent) {
-    var _top;
-
-    top = top.parent;
-  }
-
-  if (top) name = `${top.name} ${name}`;
-  command = { ...command,
-    name
-  }; // include command description and own usage
-
-  if (description) output.push(wrapString(description, maxWidth), '');
-  output.push('Usage:', formatList([`$ ${commandUsage(command)}`]), ''); // include command arguments
-
-  if (args.length) output.push('Arguments:', formatList(args), ''); // include command subcommands
-
-  let commandGroupName = command.parent ? 'Subcommands:' : 'Commands:';
-  if (commands.length) output.push(commandGroupName, formatList(commands), ''); // separate flags into groups
-
-  let groups = flags.reduce((all, option) => {
-    let group = option[2] ? `${option[2]} options` : 'Options';
-    return all.set(group, [...(all.get(group) || []), option]);
-  }, new Map([['Options', []]])); // include each group of command flags
-
-  for (let [group, flags] of groups.entries()) {
-    if (flags.length) output.push(`${group}:`, formatList(flags), '');
-  } // include command examples and replace '$0' with the command name
-
-
-  examples = (_examples = examples) === null || _examples === void 0 ? void 0 : _examples.map(ex => ex.replace('$0', `$ ${name}`));
-  if ((_examples2 = examples) !== null && _examples2 !== void 0 && _examples2.length) output.push('Examples:', formatList(examples), ''); // join each line of output
-
-  return output.join('\n');
-}
-
-var _default = formatHelp;
-exports.default = _default;

package/dist/index.js

@@ -1,37 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "command", {
-  enumerable: true,
-  get: function () {
-    return _command.command;
-  }
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _command.default;
-  }
-});
-Object.defineProperty(exports, "flags", {
-  enumerable: true,
-  get: function () {
-    return _legacy.legacyFlags;
-  }
-});
-Object.defineProperty(exports, "legacyCommand", {
-  enumerable: true,
-  get: function () {
-    return _legacy.legacyCommand;
-  }
-});
-
-var _command = _interopRequireWildcard(require("./command"));
-
-var _legacy = require("./legacy");
-
-function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
-
-function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }

package/dist/legacy.js

@@ -1,176 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-exports.legacyCommand = legacyCommand;
-exports.legacyFlags = void 0;
-
-var _command = require("./command");
-
-var _utils = require("@percy/config/dist/utils");
-
-// Legacy flags for older commands that inadvertently import a newer @percy/cli-command
-const legacyFlags = {
-  config: {},
-  logging: {},
-  discovery: {
-    __percy__: {}
-  },
-  string: def => ({
-    type: 'string',
-    ...def
-  }),
-  boolean: def => ({
-    type: 'boolean',
-    ...def
-  }),
-  integer: def => ({
-    type: 'integer',
-    ...def
-  })
-}; // Maps a legacy arg that might have alternate properties
-
-exports.legacyFlags = legacyFlags;
-
-function legacyArg(legacy) {
-  let {
-    name,
-    ...def
-  } = legacy; // do not camelcase legacy attribute names
-
-  def.attribute = name; // add name back to mapped options
-
-  return {
-    name,
-    ...def
-  };
-} // Maps a legacy flag that might have alternate properties
-
-
-function legacyFlag(name, legacy) {
-  let {
-    char: short,
-    deprecated,
-    ...def
-  } = legacy; // generic legacy type looks odd in help output
-
-  if (def.type === 'option') def.type = 'value'; // do not camelcase legacy attribute names
-
-  def.attribute = name; // transform legacy deprecated syntax
-
-  if (deprecated) {
-    let {
-      until,
-      map,
-      alt
-    } = deprecated !== true ? deprecated : {};
-    def.deprecated = [until, map ? `--${map}` : alt];
-  } // add name and mapped short option
-
-
-  return {
-    name,
-    short,
-    ...def
-  };
-} // Maps a legacy class-based command to the new functional syntax
-
-
-function legacyCommand(name, constructor) {
-  var _constructor$args, _constructor$flags, _constructor$flags$__, _constructor$flags2;
-
-  let runner = (0, _command.command)(name, {
-    description: constructor.description,
-    examples: constructor.examples,
-    // map legacy args and flags
-    args: (_constructor$args = constructor.args) === null || _constructor$args === void 0 ? void 0 : _constructor$args.map(legacyArg),
-    flags: Object.entries((_constructor$flags = constructor.flags) !== null && _constructor$flags !== void 0 ? _constructor$flags : []).map(([name, def]) => legacyFlag(name, def)).filter(({
-      name
-    }) => name !== '__percy__'),
-    percy: (_constructor$flags$__ = (_constructor$flags2 = constructor.flags) === null || _constructor$flags2 === void 0 ? void 0 : _constructor$flags2.__percy__) !== null && _constructor$flags$__ !== void 0 ? _constructor$flags$__ : true,
-    loose: constructor.strict === false,
-    legacy: true
-  }, async function* (ctx) {
-    let instance = new constructor();
-    let error; // not an instance of the constructor, create one ourself
-
-    if (!(instance instanceof constructor)) {
-      instance = Object.create(constructor.prototype);
-    } // alias legacy global flags attribute names when necessary
-
-
-    if (ctx.flags.dryRun) ctx.flags['dry-run'] = ctx.flags.dryRun; // legacy percyrc value
-
-    let percyrc = overrides => (0, _utils.merge)([ctx.percy.config, overrides, {
-      skipUploads: ctx.flags.debug,
-      dryRun: ctx.flags['dry-run'],
-      config: false
-    }], (path, prev, next) => // do not merge arrays
-    Array.isArray(next) && [path, next]); // augment legacy instance properties
-
-
-    Object.defineProperties(instance, {
-      isPercyEnabled: {
-        value: () => !!ctx.percy
-      },
-      error: {
-        value: msg => ctx.exit(1, msg)
-      },
-      parse: {
-        value: () => ctx
-      },
-      percyrc: {
-        value: percyrc
-      },
-      flags: {
-        value: ctx.flags
-      },
-      args: {
-        value: ctx.args
-      },
-      exit: {
-        value: ctx.exit
-      },
-      log: {
-        value: ctx.log
-      }
-    }); // legacy signal handling
-
-    let signals = ['SIGHUP', 'SIGINT', 'SIGTERM'];
-
-    let cleanup = () => {
-      var _instance$finally, _instance;
-
-      return (_instance$finally = (_instance = instance).finally) === null || _instance$finally === void 0 ? void 0 : _instance$finally.call(_instance, new Error('SIGTERM'));
-    };
-
-    for (let e of signals) process.on(e, cleanup); // run and handle legacy command
-
-
-    try {
-      yield instance.run();
-    } catch (err) {
-      throw error = err;
-    } finally {
-      var _instance$finally2, _instance2;
-
-      await ((_instance$finally2 = (_instance2 = instance).finally) === null || _instance$finally2 === void 0 ? void 0 : _instance$finally2.call(_instance2, error));
-
-      for (let e of signals) process.off(e, cleanup);
-    }
-  }); // throw legacy errors for test compatibility
-
-  return Object.defineProperties(args => runner(args).catch(e => {
-    throw new Error(`EEXIT: ${e.exitCode}`);
-  }), Object.getOwnPropertyDescriptors(runner));
-} // Support the legacy static run method
-
-
-_command.command.run = function run(args) {
-  return legacyCommand('legacy', this)(args);
-};
-
-var _default = legacyCommand;
-exports.default = _default;

package/dist/parse.js

@@ -1,426 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.ParseError = void 0;
-exports.parse = parse;
-
-var _logger = _interopRequireDefault(require("@percy/logger"));
-
-var _normalize = require("@percy/config/dist/normalize");
-
-var _help = require("./help");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
-
-// Make it possible to identify parse errors.
-class ParseError extends Error {
-  constructor(...args) {
-    super(...args);
-
-    _defineProperty(this, "name", this.constructor.name);
-  }
-
-} // Helper that makes it possible to throw parse errors without throw or new keywords.
-
-
-exports.ParseError = ParseError;
-
-function parseError(msg) {
-  throw new ParseError(msg);
-} // Helper to identify a potential command-line option as a flag.
-
-
-function isFlag(option) {
-  // not a flag if it doesn't start with a dash
-  if (!option.startsWith('-')) return false; // safe to say it's a flag without a space
-
-  if (!option.includes(' ')) return true; // containing a space with no operator is not a proper flag
-
-  if (!option.includes('=')) return false; // as long as the operator precedes the space, it is a flag
-
-  return option.indexOf('=') < option.indexOf(' ');
-} // Parses input to identify a command. Consumes input and adds to parsed output as needed, returning
-// true if any defined command was found. A command is only identified via leading unparsed input
-// options. If a command is found, parsed output is updated accordingly and the current input option
-// is removed from further processing. An implicit help command is also supported.
-
-
-async function maybeParseCommand(input, parsed) {
-  var _input$0$split, _input$;
-
-  // a flag, no defined commands, or already parsed other options
-  if (isFlag(input[0]) || !parsed.command.definition.commands || parsed.operators.size || parsed.argv.length) {
-    return;
-  } // implicit help
-
-
-  if (input[0] === 'help') {
-    parsed.help = true;
-    input.shift();
-  } // nested commands can be a single argument with command names separated by colons (:)
-
-
-  let names = (_input$0$split = (_input$ = input[0]) === null || _input$ === void 0 ? void 0 : _input$.split(':')) !== null && _input$0$split !== void 0 ? _input$0$split : [];
-  let command;
-
-  for (let name of names) {
-    var _parent$definition$co;
-
-    let parent = command || parsed.command; // find any nested command by name
-
-    command = (_parent$definition$co = parent.definition.commands) === null || _parent$definition$co === void 0 ? void 0 : _parent$definition$co.find(cmd => cmd.name === name);
-    if (!command) break; // maintain nested names and parent relationships
-
-    name = parent.parent ? `${parent.name}:${command.name}` : command.name;
-    command = await normalizeCommand(command, {
-      name,
-      parent
-    });
-  }
-
-  if (command) {
-    // update parsed properties and discard current input
-    parsed.log = (0, _logger.default)(`cli:${command.name}`);
-    parsed.command = command;
-    input.shift();
-  } // help was requested, drain remaining input
-
-
-  if (parsed.help) {
-    input.splice(0, input.length);
-  }
-
-  return parsed.help || !!command;
-} // Parses input to identify a flag option. Consumes input and adds to parsed output as needed,
-// returning true if any defined flag was found. If a found flag is missing a required argument, the
-// next input option will be consumed as that argument. Boolean flags support negation if their
-// default value is true, integer flags are automaticaly parsed, and flags that can be provided
-// multiple times will be concatenated together. Implicit help and version flags are also supported.
-
-
-async function maybeParseFlag(input, parsed) {
-  var _value;
-
-  if (!isFlag(input[0])) return; // end of options and arguments, consume remaining input
-
-  if (input[0] === '--') {
-    let [, ...argv] = input.splice(0, input.length);
-    parsed.argv.push(...argv);
-    return true;
-  } // a short flag was provided
-
-
-  let short = input[0][1] !== '-' && input[0][1]; // get any value set with `=` and remove any `=` from short values
-
-  let [name, value] = short ? ['', input[0].substr(2) || null] : input[0].split('=');
-  value = short && (_value = value) !== null && _value !== void 0 && _value.startsWith('=') ? value.substr(1) : value; // the flag was negated
-
-  let negated = name.startsWith('--no-');
-  name = name.replace(/^--(no-)?/, ''); // search for the provided short or long flag
-
-  let flag = parsed.command.definition.flags.find(f => {
-    return short ? f.short === short : f.name === name;
-  });
-
-  if (flag) {
-    // discard current input
-    input.shift();
-
-    if (!flag.type || flag.type === 'boolean') {
-      // short boolean flags can be provided with other short flags
-      if (short && value) input.unshift(`-${value}`); // a value was provided to a boolean flag
-
-      if (!short && value) {
-        parseError(`Unexpected option argument for '${(0, _help.flagUsage)(flag)}'`);
-      } // a boolean value is based on if it was negated
-
-
-      value = !negated;
-    } else if (value == null) {
-      // expected a value for a non-boolean flag
-      if (!input.length || isFlag(input[0])) {
-        parseError(`Missing option argument for '${(0, _help.flagUsage)(flag)}'`);
-      } // the value is actually the next input option
-
-
-      value = input.shift();
-    } // parse the value according to flag properties
-
-
-    if (flag.type === 'integer') value = parseInt(value, 10);
-    if (flag.parse) value = await flag.parse(value);
-
-    if (flag.multiple) {
-      var _parsed$operators$get;
-
-      value = ((_parsed$operators$get = parsed.operators.get(flag)) !== null && _parsed$operators$get !== void 0 ? _parsed$operators$get : []).concat(value);
-    } // add this flag to the set of parsed operators
-
-
-    parsed.operators.set(flag, value);
-    return true;
-  } // implicit version and help support
-
-
-  if (parsed.command.definition.version && (name === 'version' || short === 'V')) {
-    parsed.version = true;
-  } else if (name === 'help' || short === 'h') {
-    parsed.help = true;
-  } // help or version was requested, drain remaining input
-
-
-  if (parsed.help || parsed.version) {
-    input.splice(0, input.length);
-    return true;
-  }
-} // Parses input to identify an argument option. Consumes input and adds to parsed output as needed,
-// returning true if any defined argument was found. Arguments are matched according to their
-// respective index and command-line position.
-
-
-async function maybeParseArg(input, parsed) {
-  var _parsed$__args_index_, _parsed$command$defin;
-
-  if (isFlag(input[0])) return; // the argument index needs to be tracked since flag options can precede argument options
-
-  let index = (_parsed$__args_index_ = parsed.__args_index__) !== null && _parsed$__args_index_ !== void 0 ? _parsed$__args_index_ : parsed.__args_index__ = 0; // there are arguments left to parse
-
-  if (index < ((_parsed$command$defin = parsed.command.definition.args) === null || _parsed$command$defin === void 0 ? void 0 : _parsed$command$defin.length)) {
-    parsed.__args_index__ += 1;
-    let value = input.shift();
-    let arg = parsed.command.definition.args[index];
-    if (arg.parse) value = await arg.parse(value); // add this arg to the set of parsed operators
-
-    parsed.operators.set(arg, value);
-    return true;
-  }
-} // Parses input to identify unknown options. Consumes input and adds to parsed output as needed,
-// returning true when unknown options are found. By default, unknown options result in an error
-// unless the command is defined to accept loose options. If `loose` is a string, it will be logged
-// as a warning when unknown options are found. When the first unknown option is found, all
-// remaining options are also considered unknown.
-
-
-async function maybeParseUnknown(input, parsed) {
-  let {
-    loose
-  } = parsed.command.definition;
-
-  if (!loose) {
-    // throw a more descriptive error message
-    let reason = isFlag(input[0]) ? 'Unknown option' : 'Unexpected argument';
-    parseError(`${reason} '${input[0]}'`);
-  } else if (typeof loose === 'string') {
-    // warn when loose is a string
-    parsed.log.warn(loose);
-  } // consume all remaining unknown input options
-
-
-  let unknown = input.splice(0, input.length);
-  parsed.argv.push(...unknown);
-  return true;
-} // Parses an option's value defined by an environment variable. Adds to parsed output as needed,
-// returning true when the option's value was parsed from the environment. Boolean environment
-// variables will be interpreted as true unless "false" or "0", and integer environment variables
-// will be parsed automatically.
-
-
-async function maybeParseEnv(option, parsed) {
-  // no env option, already provided, or no defined env var
-  if (!option.env || parsed.operators.has(option) || !(option.env in process.env)) {
-    return;
-  } // get the value from the process env
-
-
-  let value = process.env[option.env];
-  let flag = parsed.command.definition.flags.includes(option);
-
-  if (flag && (!option.type || option.type === 'boolean')) {
-    // parse booleans as not "false" or not "0"
-    value = value !== 'false' && value !== '0';
-  } else if (option.type === 'integer') {
-    // parse integer option values
-    value = parseInt(value, 10);
-  } // custom parse and add this option to the set of parsed operators
-
-
-  if (option.parse) value = await option.parse(value);
-  parsed.operators.set(option, value);
-  return true;
-} // Helper to find and return a matching flag by name.
-
-
-function findFlag(name, parsed, map) {
-  if (name.startsWith('--')) name = name.substr(2);
-  let {
-    flags
-  } = parsed.command.definition;
-  let match = flags.find(f => f.name === name);
-  return map ? map(match) : match;
-} // Throws an error if the provided flag is inclusive of any missing flags.
-
-
-function validateInclusiveFlag(flag, parsed) {
-  if (!flag.inclusive) return;
-  let invalid = flag.inclusive.reduce((invalid, name) => findFlag(name, parsed, flag => // invalid options are options that have _not_ been provided
-  !parsed.operators.has(flag) ? invalid.concat(flag) : invalid), []);
-
-  if (invalid.length) {
-    // show full flag usage for invalid options
-    invalid = [flag, ...invalid].map(f => (0, _help.flagUsage)(f)).join("', '");
-    parseError(`Options must be used together: '${invalid}'`);
-  }
-} // Throws an error if the provided flag is exclusive of other provided flags.
-
-
-function validateExclusiveFlag(flag, parsed) {
-  if (!flag.exclusive) return;
-  let invalid = flag.exclusive.reduce((invalid, name) => findFlag(name, parsed, flag => // invalid options are options that _have_ been provided
-  parsed.operators.has(flag) ? invalid.concat(flag) : invalid), []);
-
-  if (invalid.length) {
-    // show full flag usage for invalid options
-    invalid = [flag, ...invalid].map(f => (0, _help.flagUsage)(f)).join("', '");
-    parseError(`Options cannot be used together: '${invalid}'`);
-  }
-} // Returns the attribute name of an option, which may be contingent on it's parsed value. If an
-// option is deprecated and is recommended to be replaced with flag, the attribute name will be
-// mapped to the replacement flag's attribute name. If a deprecated option is found in the provided
-// operators, a deprecation warning will be logged with any recommendation message.
-
-
-function attributeName(option, parsed) {
-  var _parsed$operators$get2;
-
-  let {
-    attribute,
-    deprecated
-  } = option;
-  let value = (_parsed$operators$get2 = parsed.operators.get(option)) !== null && _parsed$operators$get2 !== void 0 ? _parsed$operators$get2 : option.default; // the option's attribute name might be contingent on it's value
-
-  let name = typeof attribute === 'function' ? attribute(value) : attribute; // default the attribute name to the camelcase name or short character
-
-  name || (name = option.name ? (0, _normalize.camelcase)(option.name) : option.short); // deprecated options can be mapped to other options
-
-  if (deprecated) {
-    var _recommend;
-
-    let [until, recommend] = Array.isArray(deprecated) ? deprecated : [typeof deprecated === 'string' ? deprecated : '']; // recommended replacement flag
-
-    if ((_recommend = recommend) !== null && _recommend !== void 0 && _recommend.startsWith('--')) {
-      let opt = findFlag(recommend, parsed);
-      recommend = opt ? `Use '${(0, _help.flagUsage)(opt)}' instead.` : '';
-      name = opt ? attributeName(opt, parsed) : name;
-    } // operator was provided, log deprecation warning
-
-
-    if (parsed.operators.has(option)) {
-      // show better usage message for flags
-      let flag = parsed.command.definition.flags.includes(option);
-      let usage = flag ? (0, _help.flagUsage)(option) : option.name;
-      parsed.log.deprecated((`The '${usage}' ${flag ? 'option' : 'argument'} ` + `will be removed in ${until || 'a future release'}. ` + (recommend || '')).trim());
-    }
-  }
-
-  return name;
-} // Normalizes a command runner into an object of command properties. Optionally derives nested
-// commands from any provided definition commands method.
-
-
-async function normalizeCommand(command, properties) {
-  // shallow copy command definition
-  let { ...definition
-  } = command.definition; // evaluate commands if needed
-
-  if (typeof definition.commands === 'function') {
-    definition.commands = await definition.commands();
-  } // return shallow copy with additional properties
-
-
-  return { ...command,
-    ...properties,
-    definition
-  };
-} // Parses and validates command-line arguments according to a command definition.
-
-
-async function parse(command, argv) {
-  // initial input and output
-  let input = argv.slice().filter(a => a != null);
-  let parsed = {
-    command: await normalizeCommand(command),
-    operators: new Map(),
-    log: (0, _logger.default)('cli'),
-    flags: {},
-    args: {},
-    argv: []
-  }; // while there is input left, parse it
-
-  while (input.length) {
-    // parse and mutate input and output, looping if an option is found
-    if (await maybeParseCommand(input, parsed)) continue;
-    if (await maybeParseFlag(input, parsed)) continue;
-    if (await maybeParseArg(input, parsed)) continue;
-    await maybeParseUnknown(input, parsed);
-  } // help or version requested, skip remaining parse logic
-
-
-  if (parsed.help || parsed.version) {
-    return parsed;
-  } // validate and map defined flags
-
-
-  for (let flag of parsed.command.definition.flags) {
-    // collect last-minute env info
-    await maybeParseEnv(flag, parsed);
-
-    if (parsed.operators.has(flag)) {
-      // validate before setting the parsed attribute
-      validateInclusiveFlag(flag, parsed);
-      validateExclusiveFlag(flag, parsed);
-      let value = parsed.operators.get(flag);
-      if (flag.validate) await flag.validate(value, parsed);
-      parsed.flags[attributeName(flag, parsed)] = value;
-    } else if (flag.default != null) {
-      // a default value needs to be set, but not parsed
-      parsed.flags[attributeName(flag, parsed)] = flag.default;
-    }
-  } // validate and map defined args
-
-
-  for (let arg of (_parsed$command$defin2 = parsed.command.definition.args) !== null && _parsed$command$defin2 !== void 0 ? _parsed$command$defin2 : []) {
-    var _parsed$command$defin2;
-
-    // collect last-minute env info
-    await maybeParseEnv(arg, parsed);
-
-    if (parsed.operators.has(arg)) {
-      var _arg$deprecated, _arg$deprecated$;
-
-      // validate before setting the parsed attribute
-      let value = parsed.operators.get(arg);
-      if (arg.validate) await arg.validate(value, parsed); // a deprecated arg might be mapped to a flag
-
-      if ((_arg$deprecated = arg.deprecated) !== null && _arg$deprecated !== void 0 && (_arg$deprecated$ = _arg$deprecated[1]) !== null && _arg$deprecated$ !== void 0 && _arg$deprecated$.startsWith('--') && findFlag(arg.deprecated[1], parsed)) {
-        parsed.flags[attributeName(arg, parsed)] = value;
-      } else {
-        parsed.args[attributeName(arg, parsed)] = value;
-      }
-    } else if (arg.required) {
-      // a required argument was not provided
-      parseError(`Missing required argument '${arg.name}'`);
-    } else if (arg.default != null) {
-      // a default value needs to be set, but not parsed
-      parsed.args[attributeName(arg, parsed)] = arg.default;
-    }
-  }
-
-  return parsed;
-}
-
-var _default = parse;
-exports.default = _default;