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

package/README.md

@@ -1,60 +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)
+- [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
+import command from '@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));
 ```
 
-## Percy Configuration
-
-This CLI plugin adds the following Percy configuration options that may be commonly used throughout
-other Percy CLI plugins (defaults shown).
-
-``` yaml
-version: 2
-snapshot:
-  widths: [375, 1280]
-  minHeight: 1024
-  percyCSS: ''
-  requestHeaders: {}
-discovery:
-  allowedHostnames: []
-  networkIdleTimeout: 100
-  disableAssetCache: false
-  concurrency: 5
+``` shell
+$ node ./example --foo --bar baz qux
+{ flags: { foo: true, bar: 'baz' }, args: { one: 'qux' } }
 ```
 
-### Mapping CLI Flags
+## 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,42 @@
+#!/usr/bin/env node
+
+const fs = await import('fs');
+const path = await import('path');
+const { formatHelp } = await import('../dist/help');
+
+async function updateReadmeCommands(cwd = process.cwd()) {
+  let readmePath = path.join(cwd, 'README.md');
+  let pkgPath = path.join(cwd, 'package.json');
+  let sections = [];
+  let toc = [];
+
+  let pkg = JSON.parse(fs.readFileSync(pkgPath));
+  if (!pkg['@percy/cli']?.commands) return '';
+
+  for (let cmdPath of pkg['@percy/cli'].commands) {
+    let cmdURL = url.pathToFileURL(path.join(CWD, cmdPath));
+    let { default: command } = await import(cmdURL.href);
+    command = { ...command, parent: { name: 'percy' } };
+
+    for (let cmd of [command, ...(command.definition.commands || [])]) {
+      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(/^(.*)?(usage:.*)$/gis, '$1```\n$2```');
+      sections.push(`### ${title}\n\n${help}\n`);
+    }
+  }
+
+  fs.writeFileSync(readmePath, fs.readFileSync(readmePath, 'utf-8').replace(
+    /(<!-- commands -->)(.*)(<!-- commandsstop -->)/is,
+    `$1\n${[toc.join('\n'), sections.join('\n')].join('\n\n')}$3`
+  ));
+}
+
+updateReadmeCommands();

package/dist/command.js

@@ -1,83 +1,214 @@
-"use strict";
+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
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
 
-var _command = _interopRequireDefault(require("@oclif/command"));
+  if (def.percy && def.percy !== true) {
+    builtInFlags.PERCY.forEach(addDedupedFlag); // maybe include percy discovery flags
 
-var _config = _interopRequireDefault(require("@percy/config"));
+    if (def.percy.discoveryFlags !== false) {
+      builtInFlags.DISCOVERY.forEach(addDedupedFlag);
+    }
+  } // always add global built-in flags
 
-var _logger = _interopRequireDefault(require("@percy/logger"));
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+  builtInFlags.GLOBAL.forEach(addDedupedFlag); // copy any existing config before adding to it
 
-// 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 {
-  //  Initialize flags, args, the loglevel, and attach process handlers to allow
-  //  commands to seemlessly cleanup on interupt or termination
-  init() {
-    let {
-      args,
-      flags
-    } = this.parse();
-    this.flags = flags;
-    this.args = args; // sets the log level from verbose, quiet, and silent flags
+  def.config = { ...def.config
+  };
+  def.config.schemas = [...(def.config.schemas ?? [])];
+  def.config.migrations = [...(def.config.migrations ?? [])]; // add percy specific built-in config options
 
-    _logger.default.loglevel('info', flags); // ensure cleanup is always performed
+  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.
 
-    let cleanup = () => this.finally();
 
-    process.on('SIGHUP', cleanup);
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
-  } // Log errors using the Percy logger
+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
+      });
+    };
 
-  async catch(err) {
-    try {
-      // real errors will bubble
-      await super.catch(err);
-    } catch (err) {
-      // oclif exit method actually throws an error, don't log it
-      if (!err.oclif || err.code !== 'EEXIT') _logger.default.error(err);
-      throw err;
+    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);
     }
-  } // Returns true or false if Percy has not been disabled
+  }
+} // 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
 
-  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.
 
+  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.
 
-  percyrc() {
-    let flags = Object.entries(this.constructor.flags);
-    let overrides = flags.reduce((conf, [name, flag]) => {
-      var _flag$percyrc$split$r, _flag$percyrc;
 
-      return (_flag$percyrc$split$r = (_flag$percyrc = flag.percyrc) === null || _flag$percyrc === void 0 ? void 0 : _flag$percyrc.split('.').reduce((target, key, i, paths) => {
-        var _target$key;
+export function command(name, definition, callback) {
+  definition = withBuiltIns(definition); // auto register config schemas and migrations
 
-        let last = i === paths.length - 1;
-        target[key] = last ? this.flags[name] : (_target$key = target[key]) !== null && _target$key !== void 0 ? _target$key : {};
-        return last ? conf : target[key];
-      }, conf)) !== null && _flag$percyrc$split$r !== void 0 ? _flag$percyrc$split$r : conf;
-    }, {}); // will also validate config and log warnings
+  PercyConfig.addSchema(definition.config.schemas);
+  PercyConfig.addMigration(definition.config.migrations);
 
-    return _config.default.load({
-      path: this.flags.config,
-      overrides
-    });
-  }
+  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
 
-}
 
-exports.default = PercyCommand;
+      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;