@percy/cli-command 1.0.0-beta.9 → 1.0.0

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/package.json

@@ -1,32 +1,41 @@
 {
   "name": "@percy/cli-command",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0",
   "license": "MIT",
-  "main": "dist/index.js",
-  "types": "types/index.d.ts",
-  "files": [
-    "dist",
-    "types/index.d.ts"
-  ],
-  "scripts": {
-    "build": "babel --root-mode upward src --out-dir dist",
-    "lint": "eslint --ignore-path ../../.gitignore .",
-    "test": "cross-env NODE_ENV=test mocha",
-    "test:coverage": "nyc yarn test",
-    "test:types": "tsd"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/cli-command"
   },
   "publishConfig": {
     "access": "public"
   },
-  "mocha": {
-    "require": "../../scripts/babel-register"
+  "files": [
+    "./dist"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "bin": {
+    "percy-cli-readme": "./bin/readme"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils": "./dist/utils.js",
+    "./test/helpers": "./test/helpers.js"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build",
+    "lint": "eslint --ignore-path ../../.gitignore .",
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@oclif/command": "^1.5.19",
-    "@oclif/config": "^1.14.0",
-    "@oclif/plugin-help": "^3.1.0",
-    "@percy/config": "^1.0.0-beta.9",
-    "@percy/logger": "^1.0.0-beta.9"
+    "@percy/config": "1.0.0",
+    "@percy/core": "1.0.0",
+    "@percy/logger": "1.0.0"
   },
-  "gitHead": "57a2eeb90c7f5cdf8827c78be1e5c12df581f4b5"
+  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
 }

package/dist/command.js

@@ -1,83 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _command = _interopRequireDefault(require("@oclif/command"));
-
-var _config = _interopRequireDefault(require("@percy/config"));
-
-var _logger = _interopRequireDefault(require("@percy/logger"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// 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
-
-    _logger.default.loglevel('info', flags); // ensure cleanup is always performed
-
-
-    let cleanup = () => this.finally();
-
-    process.on('SIGHUP', cleanup);
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
-  } // Log errors using the Percy logger
-
-
-  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;
-    }
-  } // Returns true or false if Percy has not been disabled
-
-
-  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.
-
-
-  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;
-
-        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
-
-    return _config.default.load({
-      path: this.flags.config,
-      overrides
-    });
-  }
-
-}
-
-exports.default = PercyCommand;

package/dist/flags.js

@@ -1,58 +0,0 @@
-"use strict";
-
-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`
-
-var _default = { ..._command.flags,
-  logging,
-  discovery,
-  config
-};
-exports.default = _default;

package/dist/index.js

@@ -1,23 +0,0 @@
-"use strict";
-
-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 }; }

package/types/index.d.ts

@@ -1,45 +0,0 @@
-// Minimum TypeScript Version: 3.8
-import Command from '@oclif/command';
-import * as Parser from '@oclif/parser';
-
-export namespace flags {
-  interface PercyFlagBase { percyrc?: string }
-  interface PercyOptionFlag<T> extends PercyFlagBase, Parser.flags.IOptionFlag<T> {}
-  interface PercyBooleanFlag<T> extends PercyFlagBase, Parser.flags.IBooleanFlag<T> {}
-  interface PercyDefinition<T> extends Parser.flags.Definition<T> {
-    (options: { multiple: true } & Partial<PercyOptionFlag<T[]>>): PercyOptionFlag<T[]>;
-    (options: ({ required: true } | { default: Parser.flags.Default<T> }) & Partial<PercyOptionFlag<T>>): PercyOptionFlag<T>;
-    (options?: Partial<PercyOptionFlag<T>>): PercyOptionFlag<T | undefined>;
-  }
-
-  type PercyParseOptions<T> = { parse: PercyOptionFlag<T>['parse'] } & Partial<PercyOptionFlag<T>>;
-  function build<T>(defaults: PercyParseOptions<T>): PercyDefinition<T>;
-  function build(defaults: Partial<PercyOptionFlag<string>>): PercyDefinition<string>;
-  function option<T>(options: PercyParseOptions<T>): PercyOptionFlag<T | undefined>;
-  function boolean<T = boolean>(options?: Partial<PercyBooleanFlag<T>>): PercyBooleanFlag<T>;
-  const integer: PercyDefinition<number>;
-  const string: PercyDefinition<string>;
-
-  const logging: {
-    verbose: PercyOptionFlag<boolean>,
-    quiet: PercyOptionFlag<boolean>,
-    silent: PercyOptionFlag<boolean>
-  };
-
-  const discovery: {
-    ['allowed-hostnames']: PercyOptionFlag<string[]>,
-    ['network-idle-timeout']: PercyOptionFlag<number>,
-    ['disable-asset-cache']: PercyOptionFlag<boolean>
-  };
-
-  const config: {
-    config: PercyOptionFlag<string>
-  };
-}
-
-export default abstract class PercyCommand extends Command {
-  isPercyEnabled(): boolean
-  percyrc(): { [x: string]: any }
-  flags: { [x: string]: any }
-  args: { [x: string]: any }
-}