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

package/README.md

@@ -1,44 +1,193 @@
 # @percy/cli-command
 
-The base command class that Percy CLI commands should extend from. Adds commonly used configuration
-options to Percy config files, a `#percyrc()` method for parsing config files, and other shared
-methods. Also provides common CLI flags along with oclif flag functions.
+Percy CLI command parser and runner.
 
 - [Usage](#usage)
-- [Mapping CLI Flags](#mapping-cli-flags)
+- [Options](#options)
+  - [Args](#args)
+  - [Flags](#flags)
+  - [Percy](#percy)
 
 ## Usage
 
-```js
-import PercyCommand, { flags } from '@percy/cli-command'
-
-export class PercyPlugin extends PercyCommand {
-  static flags = {
-    ...flags.logging,
-    ...flags.discovery,
-    ...flags.config
-  }
-
-  run() {
-    let { args, flags } = this
-    let { snapshot, discovery } = this.percyrc()
-    // ...
-  }
-
-  finally() {
-    // called after #run() and also on process termination events
-  }
-}
+The `command` function accepts a name, definition, and callback and returns a runner function that
+accepts an array of command-line arguments.
+
+``` js
+const { command } = require('@percy/cli-command');
+
+// example command runner
+const example = command('example', {
+  description: 'Example command description',
+  // positional arguments
+  args: [
+    { name: 'one' }
+  ],
+  // flags and options
+  flags: [
+    { name: 'foo' }, // boolean by default
+    { name: 'bar', type: 'string' }
+  ],
+  // shows in help output
+  examples: [
+    // $0 will be replaced by the command name
+    '$0 --foo --bar baz qux'
+  ]
+}, ({ flags, args }) => {
+  // see below for other available properties
+  console.log({ flags, args });
+});
+
+// remove the script name from argv
+example(process.argv.slice(2));
 ```
 
-## Mapping CLI Flags
+``` shell
+$ node ./example --foo --bar baz qux
+{ flags: { foo: true, bar: 'baz' }, args: { one: 'qux' } }
+```
+
+## Options
+
+Only a command `name` is required. However, without any other options, a command will only show the
+default help output with global flags. A command's `callback` will be called when the resulting
+command runner is invoked with an array of command-line arguments. How those arguments are
+interpreted and parsed is defined by the command's `definition`.
+
+- `name` — The command name shown in help output, also used to match nested commands.
+- `definition` — A command definition object defines various options to control help output, the
+  arguments parser, and other percy options.
+  - `description` — The command description shown in help output.
+  - `usage` — Custom command usage shown in help output.
+  - `examples` — An array of example strings to show in help output.
+  - `version` — A version string to display via a `-V, --version` flag.
+  - `commands` — An array or function returning an array of nested subcommands.
+  - `flags` — Optional flag arguments accepted by the command ([see below](#flags)).
+  - `args` — Positional arguments accepted by the command ([see below](#args)).
+  - `percy` — Enable creation of a core percy instance ([see below](#percy)).
+  - `config` — Automatic percy config registration ([see below](#percy)).
+  - `loose` — Push unknown arguments to `argv`. A string value will log as a warning when unknown
+    arguments are first encountered by the parser.
+  - `exitOnError` — Call `process.exit()` if the command encounters an error while running.
+- `callback` — The command callback invoked after the runner is called with command-line arguments
+  and after those arguments are interpreted by the internal parser.
+
+The `callback` argument can be a function, an async function, or an async generator function. Given
+an async generator function, the command becomes cancelable via process interruption and is able to
+clean up after itself using traditional try-catch error handling.
+
+The `callback` function is invoked with a single argument containing various contextual properties
+according to the command definition:
+
+- `flags` — An object containing key-value pairs of flag arguments interpreted by the parser as
+  determined by the flag's respective definition ([see below](#flags)).
+- `args` — An object containing key-value pairs of positional arguments interpreted by the parser as
+  determined by the arg's respective definition ([see below](#args)).
+- `argv` — An array of unknown arguments that were not parsed due to either the `loose` option or
+  the presence of an end-of-arguments delimiter (`--`).
+- `percy` — An instance of `@percy/core` only present when a corresponding `percy` definition option
+  is provided ([see below](#percy)).
+- `log` — A `@percy/logger` group namespaced under the command's `name`. The initial loglevel is
+  optionally determined by various global logging flags (`--verbose`, `--silent`, `--quiet`).
+- `exit` — Utility function to stop the execution of a command from within the runner. Accepts
+  an exit code (default `1`) and an exit reason (default `'EEXIT: ${exitCode}'`). The function will
+  throw an error which can be handled, or let bubble where the presence of `exitOnError` will cause
+  the process to exit with the provided exit code.
+
+### Flags
+
+Each flag definition must contain either a `name` or a `short` option. By default, all flags will be
+interpreted as boolean flags and will produce an error if a value is provided. Setting the `type`
+option to anything other than `'boolean'` will allow providing command-line values and error if one
+_is not_ provided.
+
+- `name` — The flag name (i.e. `--flag-name`).
+- `short` — The flag short character (i.e. `-s`).
+- `type` — The flag type as displayed in help output.
+- `default` — The flag's default value when not provided.
+- `parse` — A function used to parse any provided flag value.
+- `validate` — A function that should throw an error when the provided flag value is invalid.
+- `attribute` — A string or function returning a string to set the value at on the `callback`
+  argument's `flags` property. Defaults to the camelcase `name` or `short` character.
+- `percyrc` — A string to map this flag to percy config options ([see below](#percy)).
+- `deprecated` — A boolean, string, or tuple used to warn about a deprecated flag and optionally map
+  it to an alternate flag ([see below](#deprecations)).
+
+### Args
+
+Positional args correspond to their definition index, so the arg definition at index `0` will match
+the first provided command-line argument that is not a flag or subcommand. By default, positional
+args are optional, but can be configured to be required or have default values.
 
-The `#percyrc()` method will parse command flags for Percy configuration mappings as determined by a
-`percyrc` flag configuration option.
+- `name` — The arg name shown in help output.
+- `required` — Indicate that this flag is required, which causes an error when not provided.
+- `default` — The arg's default value when not provided.
+- `parse` — A function used to parse the provided argument.
+- `validate` — A function that should throw an error when the provided argument is invalid.
+- `attribute` — A string or function returning a string to set the value at on the `callback`
+  argument's `args` property. Defaults to camelcase `name`.
+- `percyrc` — A string to map this arg to percy config options ([see below](#percy)).
+- `deprecated` — A boolean, string, or tuple used to warn about a deprecated arg and optionally map
+  it to a flag ([see below](#deprecations)).
+
+#### Deprecations
+
+When the `deprecated` option is `true` and the flag or positional arg has been provided by
+command-line arguments, a deprecation warning will be logged. A string value indicates the version
+in which this argument will be removed and is reflected in the deprecation message.
+
+<details>
+  <summary>Remapping deprecated arguments</summary><br>
+
+When providing a tuple, the version is the first option of the tuple, while the second option can be
+an alternate flag to use, or a recommendation message to display when the deprecation warning is
+logged. Given an alternate flag, the value will be automatically mapped to the corresponding flag's
+attribute name on the `callback` argument's `flags` property.
 
 ``` js
-'allowed-hostnames': flags.string({
-  // maps the --allowed-hostnames flag to the corresponding config option
-  percyrc: 'discovery.allowedHostnames'
-})
+{ name: 'foo', deprecated: true }
+// [percy] Warning: The '--foo' option will be removed in a future release.
+
+{ name: 'foo', deprecated: 'v2.0.0' }
+// [percy] Warning: The '--foo' option will be removed in v2.0.0.
+
+{ name: 'foo', deprecated: ['v2.0.0', '--bar'] }
+// [percy] Warning: The '--foo' option will be removed in v2.0.0. Use '--bar' instead.
+
+{ name: 'foo', deprecated: ['v2.0.0', 'Use the config file option instead.'] }
+// [percy] Warning: The '--foo' option will be removed in v2.0.0. Use the config file option instead.
 ```
+</details>
+
+### Percy
+
+The `percy` definition option accepts an object consisting of `@percy/core` options. The presence of
+this option will add shared percy flags to accepted command-line arguments and provide the command
+callback with a percy instance initialized with the provided options.
+
+When the `percy` definition option is `true`, shared percy flags will not be accepted, but a default
+percy instance will still be provided to the command callback when run. Regardless of the `percy`
+option, if the environment variable `PERCY_ENABLE` is `0`, the callback _will not_ receive a percy
+instance (and can act accordingly).
+
+- `percy` — Enables creation of a `@percy/core` instance initialized with provided options.
+  - `discoveryFlags` — When `false` prevents percy discovery flags from being accepted, but will
+    still allow other percy flags such as `--config` and `--dry-run`.
+  - `...` — All other options are passed along to the new percy instance.
+
+#### Config
+
+Acceptable percy config file options can be extended before the file is loaded via
+`PercyConfig.addSchema()` and `PercyConfig.addMigration()`. These functions can be called before the
+command is run to achieve the same effect as including them in the command definition. However, the
+presence of a `percy` definition option will also signal `@percy/core` config schemas and migrations
+to be automatically registered before the following options are registered.
+
+- `config` — Percy config schemas and migrations to register while creating the command runner.
+  - `schemas` — An array of percy config schemas to automatically register.
+  - `migrations` — An array of percy config migrations to automatically register.
+
+Additionally, flags and positional arguments that define a `percyrc` option will have their
+associated values mapped to a corresponding `percy` property that is used when initializing a
+`@percy/core` instance. Provided options are validated against config schemas and are made available
+on the command callback argument's `percy.config` property.

package/bin/readme

@@ -0,0 +1,51 @@
+#!/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 '';
+
+  let sections = [];
+  let toc = [];
+
+  for (let cmdPath of pkg['@percy/cli'].commands) {
+    let { default: command } = require(path.join(CWD, cmdPath));
+    command = { ...command, parent: { name: 'percy' } };
+
+    for (let cmd of [command, ...(command.definition.commands || [])]) {
+      if (!cmd.callback) continue;
+      if (cmd !== command) cmd = { ...cmd, parent: command };
+      if (cmd.parent.parent) cmd.name = `${cmd.parent.name}:${cmd.name}`;
+
+      let title = `\`percy ${cmd.name}\``;
+      let slug = title.slice(1, -1).replace(/\s/g, '-').replace(/:/g, '');
+      toc.push(`* [${title}](#${slug})`);
+
+      let help = await formatHelp(cmd);
+      help = help.replace(HELP_USAGE, '$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);
+}
+
+updatePackageReadme();

package/dist/command.js

@@ -3,111 +3,238 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.command = command;
 exports.default = void 0;
 
-var _command = _interopRequireDefault(require("@oclif/command"));
+var _logger = _interopRequireDefault(require("@percy/logger"));
 
 var _config = _interopRequireDefault(require("@percy/config"));
 
 var _utils = require("@percy/config/dist/utils");
 
-var _logger = _interopRequireDefault(require("@percy/logger"));
+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 _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; }
+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
+
 
-// The PercyCommand class that all Percy CLI commands should extend
-// from. Provides common #init() and #catch() methods and provides other methods
-// for loading configuration and checking if Percy is enabled.
-class PercyCommand extends _command.default {
-  constructor(...args) {
-    super(...args);
+  if (def.percy && def.percy !== true) {
+    builtInFlags.PERCY.forEach(addDedupedFlag); // maybe include percy discovery flags
 
-    _defineProperty(this, "log", (0, _logger.default)('cli:command'));
+    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);
   }
 
-  //  Initialize flags, args, the loglevel, and attach process handlers to allow
-  //  commands to seemlessly cleanup on interupt or termination
-  init() {
+  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 {
-      args,
-      flags
-    } = this.parse();
-
-    _logger.default.loglevel('info', flags);
-
-    this.flags = flags;
-    this.args = args; // log and map deprecated flags
-
-    for (let f in this.constructor.flags) {
-      let {
-        deprecated
-      } = this.constructor.flags[f];
-
-      if (deprecated && flags[f] != null) {
-        if (deprecated === true) deprecated = {};
-        let {
-          until: ver,
-          map,
-          alt
-        } = deprecated;
-        let message = `The --${f} flag ` + [`will be removed in ${ver || 'a future release'}.`, map ? `Use --${map} instead.` : alt || ''].join(' ').trim();
-        this.log.deprecated(message);
-        if (map) flags[map] = flags[f];
+      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;
       }
-    } // ensure cleanup is always performed
 
+    });
+  } // wrap and bind the parsed command callback
 
-    let cleanup = () => this.finally(new Error('SIGTERM'));
 
-    process.on('SIGHUP', cleanup);
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
-  } // Log errors using the Percy logger
+  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.
 
 
-  async catch(err) {
-    try {
-      // real errors will bubble
-      await super.catch(err);
-    } catch (err) {
-      // oclif exit method actually throws an error, let it continue
-      if (err.oclif && err.code === 'EEXIT') throw err; // log all other errors and exit
+function command(name, definition, callback) {
+  definition = withBuiltIns(definition); // auto register config schemas and migrations
 
-      this.log.error(err);
-      this.exit(1);
-    }
-  } // Returns true or false if Percy has not been disabled
+  _config.default.addSchema(definition.config.schemas);
 
+  _config.default.addMigration(definition.config.migrations);
 
-  isPercyEnabled() {
-    return process.env.PERCY_ENABLE !== '0';
-  } // Parses command flags and maps them to config options according to their
-  // respective `percyrc` parameter. The flag input is then merged with options
-  // loaded from a config file and default config options. The PERCY_TOKEN
-  // environment variable is also included as a convenience.
+  async function runner(argv = []) {
+    // reset loglevel for testing
+    _logger.default.loglevel('info');
 
+    let log = (0, _logger.default)('cli');
 
-  percyrc(initialOverrides = {}) {
-    let overrides = Object.entries(this.constructor.flags).reduce((conf, [name, flag]) => {
-      if (!flag.percyrc || this.flags[name] == null) return conf;
-      return (0, _utils.set)(conf, flag.percyrc, this.flags[name]);
-    }, initialOverrides); // will also validate config and log warnings
+    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
 
-    let config = _config.default.load({
-      path: this.flags.config,
-      overrides
-    }); // set config: false to prevent core from reloading config
 
+      if (err.exitCode !== 0) {
+        var _err$exitCode;
 
-    return Object.assign(config, {
-      skipUploads: this.flags.debug,
-      dryRun: this.flags['dry-run'],
-      config: false
-    });
-  }
+        (_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;
 }
 
-exports.default = PercyCommand;
+var _default = command;
+exports.default = _default;