@percy/cli 1.0.0-beta.7 → 1.0.0-beta.73

package/README.md

@@ -1,22 +1,20 @@
 # Percy CLI
 
-![Test](https://github.com/percy/cli/workflows/Test/badge.svg)
+[![Test](https://github.com/percy/cli/workflows/Test/badge.svg)](https://github.com/percy/cli/actions)
 
-The Percy CLI is used to capture and upload snapshots to [percy.io](https://percy.io) from the
-command line.
+The Percy CLI is used to interact with, and upload snapshots to, [percy.io](https://percy.io) via
+the command line.
 
-## Installation
-
-Using yarn: 
-
-```sh-session
-$ yarn add @percy/cli --dev
-```
+- [Installation](#installation)
+- [Command Topics](#command-topics)
+- [Advanced](#advanced)
+- [Issues](#issues)
+- [Developing](#developing)
 
-Using npm: 
+## Installation
 
 ```sh-session
-$ npm install @percy/cli --save-dev
+$ npm install --save-dev @percy/cli
 ```
 
 ## Command Topics
@@ -30,33 +28,36 @@ $ npm install @percy/cli --save-dev
 ### Advanced
 
 In addition to the CLI packages, this repo contains core libraries responsible for Percy's CI/CD
-integrations, Percy API communication, DOM snapshotting, and asset discovery.
+integrations, Percy API communication, DOM serialization, asset discovery, etc.
 
 - [`@percy/core`](./packages/core#readme) - performs snapshot asset discovery and uploading
-- [`@percy/config`](./packages/config#readme) - loads Percy configuration files
+- [`@percy/client`](./packages/client#readme) - handles communicating with the Percy API
 - [`@percy/dom`](./packages/dom#readme) - serializes DOM snapshots
 - [`@percy/env`](./packages/env#readme) - captures CI build environment variables
-- [`@percy/client`](./packages/client#readme) - handles communicating with the Percy API
+- [`@percy/config`](./packages/config#readme) - loads Percy configuration files
 - [`@percy/logger`](./packages/logger#readme) - common logger used throughout the CLI
+- [`@percy/sdk-utils`](./packages/sdk-utils#readme) - shared helpers for JavaScript SDKs
+- [`@percy/cli-command`](./packages/cli-command#readme) - Percy CLI command framework
 
 ## Issues
 
 For problems directly related to the CLI, [add an issue on
 GitHub](https://github.com/percy/cli/issues/new).
 
-For other issues, [open a support request](https://percy.io).
+For other issues, [open a support
+request](https://www.browserstack.com/contact?ref=percy#technical-support).
 
 ## Developing
 
 This project is built with [lerna](https://lerna.js.org/). The core libaries and CLI plugins are
-located in [./packages](./packages). Run `yarn` to install dependencies after cloning the repo and use
-the following scripts for various development tasks:
+located in [./packages](./packages). Run `yarn` to install dependencies after cloning the repo and
+use the following scripts for various development tasks:
 
 - `yarn build` - build all packages
 - `yarn build:watch` - build and watch all packages in parallel
 - `yarn clean` - clean up build and coverage output
 - `yarn lint` - lint all packages
-- `yarn readme` - generate oclif readme usage
+- `yarn readme` - generate cli commands readme usage
 - `yarn test` - run all tests, one package after another
 - `yarn test:coverage` - run all tests with coverage, one package after another
 
@@ -66,12 +67,3 @@ Individual package scripts can be invoked using yarn's
 ```sh-session
 $ yarn workspace @percy/core test
 ```
-
-### Releasing
-
-1. Run `yarn bump-version` and choose an appropriate version.
-2. Commit the updated version with a matching commit (e.g. `🔖v1.0.0`).
-3. Push the commit to GitHub and wait for CI to pass.
-4. Run `yarn -s release-notes` to generate release notes since the last tag.
-5. Create a new GitHub release using the release notes.
-6. The GitHub release will trigger an [automated NPM release](https://github.com/percy/cli/actions?query=workflow%3ARelease).

package/bin/run

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
-require('@oclif/command').run()
-  .then(require('@oclif/command/flush'))
-  .catch(require('@oclif/errors/handle'))
+if (parseInt(process.version.split('.')[0].substring(1), 10) < 12) {
+  console.error(`Node ${process.version} is not supported. Percy only ` + (
+    'supports the current LTS version of Node. Please upgrade to Node 12+'));
+  process.exit(1);
+}
+
+import('../dist/index.js').then(
+  async ({ checkForUpdate, percy }) => {
+    await checkForUpdate();
+    await percy(process.argv.slice(2));
+  });

package/dist/commands.js

@@ -0,0 +1,181 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.importCommands = importCommands;
+
+var _os = _interopRequireDefault(require("os"));
+
+var _fs = _interopRequireDefault(require("fs"));
+
+var _path = _interopRequireDefault(require("path"));
+
+var _module = require("module");
+
+var _logger = _interopRequireDefault(require("@percy/logger"));
+
+var _cliCommand = require("@percy/cli-command");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: 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; }
+
+// Helper to simplify reducing async functions
+async function reduceAsync(iter, reducer, accum = []) {
+  for (let i of iter) accum = await reducer(accum, i);
+
+  return accum;
+} // Helper to read and reduce files within a directory
+
+
+function reduceFiles(dir, reducer) {
+  return reduceAsync(_fs.default.readdirSync(dir, {
+    withFileTypes: true
+  }), reducer);
+} // Returns the paths of potential percy packages found within node_modules
+
+
+function findModulePackages(dir) {
+  try {
+    // not given node_modules or a directory that contains node_modules, look up
+    if (_path.default.basename(dir) !== 'node_modules') {
+      let modulesPath = _path.default.join(dir, 'node_modules');
+
+      let next = _fs.default.existsSync(modulesPath) ? modulesPath : _path.default.dirname(dir);
+      if (next === dir || next === _os.default.homedir()) return [];
+      return findModulePackages(next);
+    } // given node modules, look for percy packages
+
+
+    return reduceFiles(dir, async (roots, file) => {
+      let rootPath = _path.default.join(dir, file.name);
+
+      if (file.name === '@percy') {
+        return roots.concat(await reduceFiles(rootPath, (dirs, f) => // specifically protect against files to allow linked directories
+        f.isFile() ? dirs : dirs.concat(_path.default.join(rootPath, f.name)), []));
+      } else if (file.name.startsWith('percy-cli-')) {
+        return roots.concat(rootPath);
+      } else {
+        return roots;
+      }
+    }, []);
+  } catch (error) {
+    (0, _logger.default)('cli:plugins').debug(error);
+    return [];
+  }
+} // Used by `findPnpPackages` to filter Percy CLI plugins
+
+
+const PERCY_PKG_REG = /^(@percy\/|percy-cli-)/; // Returns the paths of potential percy packages found within yarn's pnp system
+
+function findPnpPackages(dir) {
+  var _pkgInfo$packageDepen;
+
+  let pnpapi = _module.findPnpApi === null || _module.findPnpApi === void 0 ? void 0 : (0, _module.findPnpApi)(`${dir}/`);
+  let pkgLoc = pnpapi === null || pnpapi === void 0 ? void 0 : pnpapi.findPackageLocator(`${dir}/`);
+  let pkgInfo = pkgLoc && (pnpapi === null || pnpapi === void 0 ? void 0 : pnpapi.getPackageInformation(pkgLoc));
+  let pkgDeps = (_pkgInfo$packageDepen = pkgInfo === null || pkgInfo === void 0 ? void 0 : pkgInfo.packageDependencies.entries()) !== null && _pkgInfo$packageDepen !== void 0 ? _pkgInfo$packageDepen : [];
+  return Array.from(pkgDeps).reduce((roots, [name, ref]) => {
+    if (!ref || !PERCY_PKG_REG.test(name)) return roots;
+    let depLoc = pnpapi.getLocator(name, ref);
+    let depInfo = pnpapi.getPackageInformation(depLoc);
+    return roots.concat(depInfo.packageLocation);
+  }, []);
+} // Helper to import and wrap legacy percy commands for reverse compatibility
+
+
+function importLegacyCommands(commandsPath) {
+  return reduceFiles(commandsPath, async (cmds, file) => {
+    let {
+      name
+    } = _path.default.parse(file.name);
+
+    let filepath = _path.default.join(commandsPath, name);
+
+    if (file.isDirectory()) {
+      // recursively import nested commands and find the index command
+      let commands = await importLegacyCommands(filepath);
+      let index = commands.findIndex(cmd => cmd.name === 'index'); // modify or create an index command to hold nested commands
+
+      index = ~index ? commands.splice(index, 1)[0] : (0, _cliCommand.command)();
+      Object.defineProperty(index, 'name', {
+        value: name
+      });
+      index.definition.commands = commands;
+      return cmds.concat(index);
+    } else {
+      // find and wrap the command exported by the module
+      let exports = Object.values(await Promise.resolve(`${filepath}`).then(s => _interopRequireWildcard(require(s))));
+      let cmd = exports.find(e => {
+        var _e$prototype;
+
+        return typeof (e === null || e === void 0 ? void 0 : (_e$prototype = e.prototype) === null || _e$prototype === void 0 ? void 0 : _e$prototype.run) === 'function';
+      });
+      return cmd ? cmds.concat((0, _cliCommand.legacyCommand)(name, cmd)) : cmds;
+    }
+  });
+} // Imports and returns compatibile CLI commands from various sources
+
+
+async function importCommands() {
+  // start with a set to get built-in deduplication
+  let cmdPkgs = await reduceAsync(new Set([// find included dependencies
+  _path.default.join(__dirname, '..'), // find potential sibling packages
+  _path.default.join(__dirname, '..', '..'), // find any current project dependencies
+  process.cwd()]), async (roots, dir) => {
+    roots.push(...(await findModulePackages(dir)));
+    roots.push(...(await findPnpPackages(dir)));
+    return roots;
+  }); // reduce found packages to functions which import cli commands
+
+  let cmdImports = await reduceAsync(cmdPkgs, async (pkgs, pkgPath) => {
+    var _pkg$oclif, _pkg$PercyCli;
+
+    let pkg = require(_path.default.join(pkgPath, 'package.json')); // do not include self
+
+
+    if (pkg.name === '@percy/cli') return pkgs; // support legacy oclif percy commands
+
+    if (((_pkg$oclif = pkg.oclif) === null || _pkg$oclif === void 0 ? void 0 : _pkg$oclif.bin) === 'percy') {
+      pkgs.set(pkg.name, async () => {
+        var _pkg$oclif$hooks;
+
+        if ((_pkg$oclif$hooks = pkg.oclif.hooks) !== null && _pkg$oclif$hooks !== void 0 && _pkg$oclif$hooks.init) {
+          let initPath = _path.default.join(pkgPath, pkg.oclif.hooks.init);
+
+          let init = await Promise.resolve(`${initPath}`).then(s => _interopRequireWildcard(require(s)));
+          await init.default();
+        }
+
+        if (pkg.oclif.commands) {
+          let commandsPath = _path.default.join(pkgPath, pkg.oclif.commands);
+
+          return importLegacyCommands(commandsPath);
+        }
+
+        return [];
+      });
+    } // overwrite any found package of the same name
+
+
+    if ((_pkg$PercyCli = pkg['@percy/cli']) !== null && _pkg$PercyCli !== void 0 && _pkg$PercyCli.commands) {
+      pkgs.set(pkg.name, () => Promise.all(pkg['@percy/cli'].commands.map(async cmdPath => {
+        let module = await Promise.resolve(`${_path.default.join(pkgPath, cmdPath)}`).then(s => _interopRequireWildcard(require(s)));
+        return module.default;
+      })));
+    }
+
+    return pkgs;
+  }, new Map()); // actually import found commands
+
+  let cmds = await reduceAsync(cmdImports.values(), async (cmds, importCmds) => cmds.concat(await importCmds())); // sort standalone commands before command topics
+
+  return cmds.sort((a, b) => {
+    if (a.callback && !b.callback) return -1;
+    if (b.callback && !a.callback) return 1;
+    return a.name.localeCompare(b.name);
+  });
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "checkForUpdate", {
+  enumerable: true,
+  get: function () {
+    return _update.checkForUpdate;
+  }
+});
+Object.defineProperty(exports, "default", {
+  enumerable: true,
+  get: function () {
+    return _percy.default;
+  }
+});
+Object.defineProperty(exports, "percy", {
+  enumerable: true,
+  get: function () {
+    return _percy.percy;
+  }
+});
+
+var _percy = _interopRequireWildcard(require("./percy"));
+
+var _update = require("./update");
+
+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; }

package/dist/percy.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.percy = exports.default = void 0;
+
+var _cliCommand = _interopRequireDefault(require("@percy/cli-command"));
+
+var _commands = require("./commands");
+
+var _package = _interopRequireDefault(require("../package.json"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+const percy = (0, _cliCommand.default)('percy', {
+  version: `${_package.default.name} ${_package.default.version}`,
+  commands: () => (0, _commands.importCommands)(),
+  exitOnError: true
+});
+exports.percy = percy;
+var _default = percy;
+exports.default = _default;

package/dist/update.js

@@ -0,0 +1,120 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.checkForUpdate = checkForUpdate;
+exports.default = void 0;
+
+var _fs = _interopRequireDefault(require("fs"));
+
+var _path = _interopRequireDefault(require("path"));
+
+var _logger = _interopRequireDefault(require("@percy/logger"));
+
+var _util = require("@percy/logger/dist/util");
+
+var _package = _interopRequireDefault(require("../package.json"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: 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; }
+
+// filepath where the cache will be read and written to
+const CACHE_FILE = _path.default.join(__dirname, '..', '.releases'); // max age the cache should be used for (3 days)
+
+
+const CACHE_MAX_AGE = 3 * 24 * 60 * 60 * 1000; // Safely read from CACHE_FILE and return an object containing `data` mirroring what was previously
+// written using `writeToCache(data)`. An empty object is returned when older than CACHE_MAX_AGE,
+// and an `error` will be present if one was encountered.
+
+function readFromCache() {
+  let cached = {};
+
+  try {
+    if (_fs.default.existsSync(CACHE_FILE)) {
+      let {
+        createdAt,
+        data
+      } = JSON.parse(_fs.default.readFileSync(CACHE_FILE));
+      if (Date.now() - createdAt < CACHE_MAX_AGE) cached.data = data;
+    }
+  } catch (error) {
+    let log = (0, _logger.default)('cli:update:cache');
+    log.debug('Unable to read from cache');
+    log.debug(cached.error = error);
+  }
+
+  return cached;
+} // Safely write data to CACHE_FILE with the current timestamp.
+
+
+function writeToCache(data) {
+  try {
+    _fs.default.writeFileSync(CACHE_FILE, JSON.stringify({
+      createdAt: Date.now(),
+      data
+    }));
+  } catch (error) {
+    let log = (0, _logger.default)('cli:update:cache');
+    log.debug('Unable to write to cache');
+    log.debug(error);
+  }
+} // Fetch and return release information for @percy/cli.
+
+
+async function fetchReleases() {
+  let {
+    request
+  } = await Promise.resolve().then(() => _interopRequireWildcard(require('@percy/client/dist/request'))); // fetch releases from the github api without retries
+
+  let api = 'https://api.github.com/repos/percy/cli/releases';
+  let data = await request(api, {
+    headers: {
+      'User-Agent': _package.default.name
+    },
+    retries: 0
+  }); // return relevant information
+
+  return data.map(r => ({
+    tag: r.tag_name,
+    prerelease: r.prerelease
+  }));
+} // Check for updates by comparing latest releases with the current version. The result of the check
+// is cached to speed up subsequent CLI usage.
+
+
+async function checkForUpdate() {
+  let {
+    data: releases,
+    error: cacheError
+  } = readFromCache();
+  let log = (0, _logger.default)('cli:update');
+
+  try {
+    // request new release information if needed
+    if (!releases) {
+      releases = await fetchReleases();
+      if (!cacheError) writeToCache(releases, log);
+    } // check the current package version against released versions
+
+
+    let versions = releases.map(r => r.tag.substr(1));
+    let age = versions.indexOf(_package.default.version); // a new version is available
+
+    if (age !== 0) {
+      let range = `${_util.colors.red(_package.default.version)} -> ${_util.colors.green(versions[0])}`;
+      log.stderr.write('\n');
+      log.warn(`${age > 0 && age < 10 ? 'A new version of @percy/cli is available!' : 'Heads up! The current version of @percy/cli is more than 10 releases behind!'} ${range}`);
+      log.stderr.write('\n');
+    }
+  } catch (err) {
+    log.debug('Unable to check for updates');
+    log.debug(err);
+  }
+}
+
+var _default = checkForUpdate;
+exports.default = _default;

package/package.json

@@ -1,43 +1,41 @@
 {
   "name": "@percy/cli",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.73",
   "license": "MIT",
-  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
   "bin": {
     "percy": "bin/run"
   },
   "files": [
     "bin",
-    "index.js",
-    "oclif.manifest.json"
+    "dist"
   ],
+  "engines": {
+    "node": ">=12"
+  },
   "scripts": {
+    "build": "node ../../scripts/build",
     "lint": "eslint --ignore-path ../../.gitignore .",
-    "postbuild": "oclif-dev manifest"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "oclif": {
-    "bin": "percy",
-    "plugins": [
-      "@percy/cli-config",
-      "@percy/cli-exec",
-      "@percy/cli-build",
-      "@percy/cli-snapshot",
-      "@percy/cli-upload",
-      "@oclif/plugin-help",
-      "@oclif/plugin-plugins"
-    ]
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@oclif/plugin-help": "^3.1.0",
-    "@oclif/plugin-plugins": "^1.7.10",
-    "@percy/cli-build": "^1.0.0-beta.7",
-    "@percy/cli-config": "^1.0.0-beta.7",
-    "@percy/cli-exec": "^1.0.0-beta.7",
-    "@percy/cli-snapshot": "^1.0.0-beta.7",
-    "@percy/cli-upload": "^1.0.0-beta.7"
+    "@percy/cli-build": "1.0.0-beta.73",
+    "@percy/cli-command": "1.0.0-beta.73",
+    "@percy/cli-config": "1.0.0-beta.73",
+    "@percy/cli-exec": "1.0.0-beta.73",
+    "@percy/cli-snapshot": "1.0.0-beta.73",
+    "@percy/cli-upload": "1.0.0-beta.73",
+    "@percy/client": "1.0.0-beta.73",
+    "@percy/logger": "1.0.0-beta.73"
   },
-  "gitHead": "5be796ec8f17958e93ada0b634899b945c9b0d60"
+  "gitHead": "aa8160e02bea3e04ab1d3605762f89fbe79605d4"
 }

package/index.js

@@ -1,2 +0,0 @@
-// This package is a multi-command oclif CLI composed of plugins that provide
-// various functionalities for taking Percy snapshots.