@percy/cli-command 1.0.0-beta.70 → 1.0.0-beta.74

package/dist/flags.js

@@ -3,63 +3,97 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = void 0;
+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 _command = require("@oclif/command");
+var _logger = _interopRequireDefault(require("@percy/logger"));
 
-// Common logging flags exclusive of each other.
-const logging = {
-  verbose: _command.flags.boolean({
-    char: 'v',
-    description: 'log everything',
-    exclusive: ['quiet', 'silent']
-  }),
-  quiet: _command.flags.boolean({
-    char: 'q',
-    description: 'log errors only',
-    exclusive: ['verbose', 'silent']
-  }),
-  silent: _command.flags.boolean({
-    description: 'log nothing',
-    exclusive: ['verbose', 'quiet']
-  })
-}; // Common asset discovery flags.
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-const discovery = {
-  'allowed-hostname': _command.flags.string({
-    char: 'h',
-    description: 'allowed hostnames to capture in asset discovery',
-    multiple: true,
-    percyrc: 'discovery.allowedHostnames'
-  }),
-  'network-idle-timeout': _command.flags.integer({
-    char: 't',
-    description: 'asset discovery network idle timeout',
-    percyrc: 'discovery.networkIdleTimeout'
-  }),
-  'disable-cache': _command.flags.boolean({
-    description: 'disable asset discovery caches',
-    percyrc: 'discovery.disableCache'
-  }),
-  'dry-run': _command.flags.boolean({
-    char: 'd',
-    description: 'print logs only, do not run asset discovery or upload snapshots'
-  }),
-  debug: _command.flags.boolean({
-    description: 'debug asset discovery and do not upload snapshots'
-  })
-}; // Common flag for loading config files.
+// 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 = {
-  config: _command.flags.string({
-    char: 'c',
-    description: 'configuration file path'
-  })
-}; // Export a single object imported as `flags`
-
-var _default = { ..._command.flags,
-  logging,
-  discovery,
-  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.default = _default;
+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

@@ -0,0 +1,262 @@
+"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

@@ -3,6 +3,12 @@
 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 () {
@@ -12,12 +18,20 @@ Object.defineProperty(exports, "default", {
 Object.defineProperty(exports, "flags", {
   enumerable: true,
   get: function () {
-    return _flags.default;
+    return _legacy.legacyFlags;
   }
 });
+Object.defineProperty(exports, "legacyCommand", {
+  enumerable: true,
+  get: function () {
+    return _legacy.legacyCommand;
+  }
+});
+
+var _command = _interopRequireWildcard(require("./command"));
 
-var _command = _interopRequireDefault(require("./command"));
+var _legacy = require("./legacy");
 
-var _flags = _interopRequireDefault(require("./flags"));
+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 _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+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

@@ -0,0 +1,176 @@
+"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;