@percy/cli-command 1.0.0-beta.8 → 1.0.1

package/dist/flags.js

@@ -1,58 +1,85 @@
-"use strict";
+import logger from '@percy/logger'; // Global CLI flags
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _command = require("@oclif/command");
-
-// 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 mapped to config options.
-
-const discovery = {
-  'allowed-hostname': _command.flags.string({
-    char: 'h',
-    description: 'allowed hostnames',
-    multiple: true,
-    percyrc: 'discovery.allowedHostnames'
-  }),
-  'network-idle-timeout': _command.flags.integer({
-    char: 't',
-    description: 'asset discovery idle timeout',
-    percyrc: 'discovery.networkIdleTimeout'
-  }),
-  'disable-asset-cache': _command.flags.boolean({
-    description: 'disable asset discovery caches',
-    percyrc: 'discovery.disableAssetCache'
-  })
-}; // Common flag for loading config files.
-
-const config = {
-  config: _command.flags.string({
-    char: 'c',
-    description: 'configuration file path'
-  })
-}; // Export a single object imported as `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
 
-var _default = { ..._command.flags,
-  logging,
-  discovery,
-  config
+export const config = {
+  name: 'config',
+  description: 'Config file path',
+  percyrc: 'config',
+  type: 'file',
+  group: 'Percy',
+  short: 'c'
 };
-exports.default = _default;
+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

@@ -1,23 +1,5 @@
-"use strict";
+export { default, command } from './command.js';
+export { legacyCommand, legacyFlags as flags } from './legacy.js'; // export common packages to avoid dependency resolution issues
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _command.default;
-  }
-});
-Object.defineProperty(exports, "flags", {
-  enumerable: true,
-  get: function () {
-    return _flags.default;
-  }
-});
-
-var _command = _interopRequireDefault(require("./command"));
-
-var _flags = _interopRequireDefault(require("./flags"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+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;