@percy/cli-command 1.0.0 → 1.0.3

package/dist/command.js

@@ -0,0 +1,214 @@
+import logger from '@percy/logger';
+import PercyConfig from '@percy/config';
+import { set, del } from '@percy/config/utils';
+import * as CoreConfig from '@percy/core/config';
+import * as builtInFlags from './flags.js';
+import formatHelp from './help.js';
+import parse from './parse.js'; // Copies a command definition and adds built-in flags and config options.
+
+function withBuiltIns(definition) {
+  let def = { ...definition
+  };
+  def.flags = [...(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 ? 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.migrations = [...(def.config.migrations ?? [])]; // 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 pkg = command.packageInformation;
+  let def = command.definition; // automatically include a preconfigured percy instance
+
+  if (def.percy) {
+    let {
+      Percy
+    } = await import('@percy/core'); // set defaults and prune preconfiguraton options
+
+    let conf = del({
+      server: false,
+      ...def.percy
+    }, 'discoveryFlags');
+    if (pkg) conf.clientInfo || (conf.clientInfo = `${pkg.name}/${pkg.version}`);
+    conf.environmentInfo || (conf.environmentInfo = `node/${process.version}`);
+    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 ? 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.
+
+
+export function command(name, definition, callback) {
+  definition = withBuiltIns(definition); // auto register config schemas and migrations
+
+  PercyConfig.addSchema(definition.config.schemas);
+  PercyConfig.addMigration(definition.config.migrations);
+
+  async function runner(argv = []) {
+    // reset loglevel for testing
+    logger.loglevel('info');
+    let log = logger('cli');
+
+    try {
+      // parse input
+      let parsed = await parse(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 formatHelp(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) {
+        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;
+}
+export default command;

package/dist/flags.js

@@ -0,0 +1,85 @@
+import logger from '@percy/logger'; // Global CLI flags
+
+export const verbose = {
+  name: 'verbose',
+  description: 'Log everything',
+  exclusive: ['quiet', 'silent'],
+  parse: () => !!logger.loglevel('debug'),
+  group: 'Global',
+  short: 'v'
+};
+export const quiet = {
+  name: 'quiet',
+  description: 'Log errors only',
+  exclusive: ['verbose', 'silent'],
+  parse: () => !!logger.loglevel('warn'),
+  group: 'Global',
+  short: 'q'
+};
+export const silent = {
+  name: 'silent',
+  description: 'Log nothing',
+  exclusive: ['verbose', 'quiet'],
+  parse: () => !!logger.loglevel('silent'),
+  group: 'Global',
+  short: 's'
+}; // Common percy and asset discovery flags
+
+export const config = {
+  name: 'config',
+  description: 'Config file path',
+  percyrc: 'config',
+  type: 'file',
+  group: 'Percy',
+  short: 'c'
+};
+export const dryRun = {
+  name: 'dry-run',
+  description: 'Print snapshot names only',
+  percyrc: 'dryRun',
+  group: 'Percy',
+  short: 'd'
+};
+export const allowedHostnames = {
+  name: 'allowed-hostname',
+  description: 'Allowed hostnames to capture in asset discovery',
+  percyrc: 'discovery.allowedHostnames',
+  type: 'hostname',
+  multiple: true,
+  group: 'Percy',
+  short: 'h'
+};
+export const disallowedHostnames = {
+  name: 'disallowed-hostname',
+  description: 'Disallowed hostnames to abort in asset discovery',
+  percyrc: 'discovery.disallowedHostnames',
+  type: 'hostname',
+  multiple: true,
+  group: 'Percy'
+};
+export const networkIdleTimeout = {
+  name: 'network-idle-timeout',
+  description: 'Asset discovery network idle timeout',
+  percyrc: 'discovery.networkIdleTimeout',
+  type: 'ms',
+  parse: Number,
+  group: 'Percy',
+  short: 't'
+};
+export const disableCache = {
+  name: 'disable-cache',
+  description: 'Disable asset discovery caches',
+  percyrc: 'discovery.disableCache',
+  group: 'Percy'
+};
+export const debug = {
+  name: 'debug',
+  description: 'Debug asset discovery and do not upload snapshots',
+  parse: () => !!logger.loglevel('debug'),
+  percyrc: 'skipUploads',
+  group: 'Percy'
+}; // Group constants
+
+export const GLOBAL = [verbose, quiet, silent];
+export const PERCY = [config, dryRun];
+export const DISCOVERY = [allowedHostnames, disallowedHostnames, networkIdleTimeout, disableCache, debug];

package/dist/help.js

@@ -0,0 +1,243 @@
+import logger from '@percy/logger'; // 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) {
+  let args = command.definition.args ?? []; // 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) {
+  let commands = command.definition.commands ?? [];
+  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.
+
+
+export 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.
+
+
+export 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.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');
+}
+export default formatHelp;

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default, command } from './command.js';
+export { legacyCommand, legacyFlags as flags } from './legacy.js'; // export common packages to avoid dependency resolution issues
+
+export { default as PercyConfig } from '@percy/config';
+export { default as logger } from '@percy/logger';

package/dist/legacy.js

@@ -0,0 +1,161 @@
+import { merge } from '@percy/config/utils';
+import { command } from './command.js'; // Legacy flags for older commands that inadvertently import a newer @percy/cli-command
+
+export 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
+
+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
+
+
+export function legacyCommand(name, constructor) {
+  var _constructor$args, _constructor$flags;
+
+  let runner = 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 ?? []).map(([name, def]) => legacyFlag(name, def)).filter(({
+      name
+    }) => name !== '__percy__'),
+    percy: ((_constructor$flags = constructor.flags) === null || _constructor$flags === void 0 ? void 0 : _constructor$flags.__percy__) ?? 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 => 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.run = function run(args) {
+  return legacyCommand('legacy', this)(args);
+};
+
+export default legacyCommand;

package/dist/parse.js

@@ -0,0 +1,400 @@
+import logger from '@percy/logger';
+import { camelcase } from '@percy/config/utils';
+import { flagUsage } from './help.js'; // Make it possible to identify parse errors.
+
+export class ParseError extends Error {
+  name = this.constructor.name;
+} // Helper that makes it possible to throw parse errors without throw or new keywords.
+
+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$;
+
+  // 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$ = input[0]) === null || _input$ === void 0 ? void 0 : _input$.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 = logger(`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 automatically 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 '${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 '${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) {
+      value = (parsed.operators.get(flag) ?? []).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$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__ = 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 => 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 => 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) {
+  let {
+    attribute,
+    deprecated
+  } = option;
+  let value = parsed.operators.get(option) ?? 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 ? 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 '${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 ? 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) {
+  var _ref;
+
+  // shallow copy command definition
+  let { ...definition
+  } = command.definition; // evaluate commands if needed
+
+  if (typeof definition.commands === 'function') {
+    definition.commands = await definition.commands();
+  } // create a shallow copy with additional properties
+
+
+  let normalized = { ...command,
+    ...properties,
+    definition
+  }; // inherit parent package information by default
+
+  normalized.packageInformation || (normalized.packageInformation = (_ref = (properties === null || properties === void 0 ? void 0 : properties.parent) || command.parent) === null || _ref === void 0 ? void 0 : _ref.packageInformation);
+  return normalized;
+} // Parses and validates command-line arguments according to a command definition.
+
+
+export 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: logger('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.definition.args ?? []) {
+    // 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;
+}
+export default parse;

package/dist/utils.js

@@ -0,0 +1,2 @@
+export * from '@percy/config/utils';
+export * from '@percy/core/utils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/cli-command",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,7 +11,8 @@
     "access": "public"
   },
   "files": [
-    "./dist"
+    "dist",
+    "test/helpers.js"
   ],
   "engines": {
     "node": ">=14"
@@ -33,9 +34,9 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/config": "1.0.0",
-    "@percy/core": "1.0.0",
-    "@percy/logger": "1.0.0"
+    "@percy/config": "1.0.3",
+    "@percy/core": "1.0.3",
+    "@percy/logger": "1.0.3"
   },
-  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
+  "gitHead": "a259d5cff0933711bced21a979c577e70765d318"
 }

package/test/helpers.js

@@ -0,0 +1 @@
+export * from '@percy/core/test/helpers';