@percy/cli 1.0.0-beta.8 → 1.0.1

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.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// ensure that we're running within a supported node version
+if (parseInt(process.version.split('.')[0].substring(1), 10) < 14) {
+  console.error(`Node ${process.version} is not supported. Percy only ` + (
+    'supports current LTS versions of Node. Please upgrade to Node 14+'));
+  process.exit(1);
+}
+
+import('../dist/index.js')
+  .then(async ({ percy, checkForUpdate }) => {
+    await checkForUpdate();
+    await percy(process.argv.slice(2));
+  });

package/dist/commands.js

@@ -0,0 +1,162 @@
+import os from 'os';
+import fs from 'fs';
+import url from 'url';
+import path from 'path';
+import Module from 'module';
+import { command, legacyCommand, logger } from '@percy/cli-command'; // 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.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.basename(dir) !== 'node_modules') {
+      let modulesPath = path.join(dir, 'node_modules');
+      let next = fs.existsSync(modulesPath) ? modulesPath : path.dirname(dir);
+      if (next === dir || next === os.homedir()) return [];
+      return findModulePackages(next);
+    } // given node modules, look for percy packages
+
+
+    return reduceFiles(dir, async (roots, file) => {
+      let rootPath = path.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.join(rootPath, f.name)), []));
+      } else if (file.name.startsWith('percy-cli-')) {
+        return roots.concat(rootPath);
+      } else {
+        return roots;
+      }
+    }, []);
+  } catch (error) {
+    logger('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 _Module$findPnpApi;
+
+  let pnpapi = (_Module$findPnpApi = Module.findPnpApi) === null || _Module$findPnpApi === void 0 ? void 0 : _Module$findPnpApi.call(Module, `${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 === null || pkgInfo === void 0 ? void 0 : pkgInfo.packageDependencies.entries()) ?? [];
+  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 filepath = path.join(commandsPath, file.name);
+    let {
+      name
+    } = path.parse(file.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] : 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 import(url.pathToFileURL(filepath).href));
+      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(legacyCommand(name, cmd)) : cmds;
+    }
+  });
+} // Imports and returns compatibile CLI commands from various sources
+
+
+export async function importCommands() {
+  let root = path.resolve(url.fileURLToPath(import.meta.url), '../..'); // start with a set to get built-in deduplication
+
+  let cmdPkgs = await reduceAsync(new Set([// find included dependencies
+  root, // find potential sibling packages
+  path.join(root, '..'), // 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 = JSON.parse(fs.readFileSync(path.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.join(pkgPath, pkg.oclif.hooks.init);
+          let init = await import(url.pathToFileURL(initPath).href);
+          await init.default();
+        }
+
+        if (pkg.oclif.commands) {
+          let commandsPath = path.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 => {
+        var _module$default;
+
+        let modulePath = path.join(pkgPath, cmdPath);
+        let module = await import(url.pathToFileURL(modulePath).href);
+        (_module$default = module.default).packageInformation || (_module$default.packageInformation = pkg);
+        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,2 @@
+export { default, percy } from './percy.js';
+export { checkForUpdate } from './update.js';

package/dist/percy.js

@@ -0,0 +1,10 @@
+import command from '@percy/cli-command';
+import { getPackageJSON } from '@percy/cli-command/utils';
+import { importCommands } from './commands.js';
+const pkg = getPackageJSON(import.meta.url);
+export const percy = command('percy', {
+  version: `${pkg.name} ${pkg.version}`,
+  commands: () => importCommands(),
+  exitOnError: true
+});
+export default percy;

package/dist/update.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import url from 'url';
+import path from 'path';
+import logger from '@percy/logger';
+import { colors } from '@percy/logger/utils';
+import { getPackageJSON } from '@percy/cli-command/utils'; // filepath where the cache will be read and written to
+
+const CACHE_FILE = path.resolve(url.fileURLToPath(import.meta.url), '../../.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.existsSync(CACHE_FILE)) {
+      let {
+        createdAt,
+        data
+      } = JSON.parse(fs.readFileSync(CACHE_FILE));
+      if (Date.now() - createdAt < CACHE_MAX_AGE) cached.data = data;
+    }
+  } catch (error) {
+    let log = logger('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.writeFileSync(CACHE_FILE, JSON.stringify({
+      createdAt: Date.now(),
+      data
+    }));
+  } catch (error) {
+    let log = logger('cli:update:cache');
+    log.debug('Unable to write to cache');
+    log.debug(error);
+  }
+} // Fetch and return release information for @percy/cli.
+
+
+async function fetchReleases(pkg) {
+  let {
+    request
+  } = await import('@percy/client/utils'); // 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': pkg.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.
+
+
+export async function checkForUpdate() {
+  let {
+    data: releases,
+    error: cacheError
+  } = readFromCache();
+  let pkg = getPackageJSON(import.meta.url);
+  let log = logger('cli:update');
+
+  try {
+    // request new release information if needed
+    if (!releases) {
+      releases = await fetchReleases(pkg);
+      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(pkg.version); // a new version is available
+
+    if (age !== 0) {
+      let range = `${colors.red(pkg.version)} -> ${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);
+  }
+}
+export default checkForUpdate;

package/package.json

@@ -1,43 +1,43 @@
 {
   "name": "@percy/cli",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.1",
   "license": "MIT",
-  "main": "index.js",
-  "bin": {
-    "percy": "bin/run"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "files": [
     "bin",
-    "index.js",
-    "oclif.manifest.json"
+    "dist"
   ],
-  "scripts": {
-    "lint": "eslint --ignore-path ../../.gitignore .",
-    "postbuild": "oclif-dev manifest"
+  "engines": {
+    "node": ">=14"
   },
-  "publishConfig": {
-    "access": "public"
+  "bin": {
+    "percy": "./bin/run.cjs"
   },
-  "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"
-    ]
+  "main": "./dist/index.js",
+  "exports": "./dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "node ../../scripts/build",
+    "lint": "eslint --ignore-path ../../.gitignore .",
+    "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.8",
-    "@percy/cli-config": "^1.0.0-beta.8",
-    "@percy/cli-exec": "^1.0.0-beta.8",
-    "@percy/cli-snapshot": "^1.0.0-beta.8",
-    "@percy/cli-upload": "^1.0.0-beta.8"
+    "@percy/cli-build": "1.0.1",
+    "@percy/cli-command": "1.0.1",
+    "@percy/cli-config": "1.0.1",
+    "@percy/cli-exec": "1.0.1",
+    "@percy/cli-snapshot": "1.0.1",
+    "@percy/cli-upload": "1.0.1",
+    "@percy/client": "1.0.1",
+    "@percy/logger": "1.0.1"
   },
-  "gitHead": "6015850e7c20c130d625fcb327b10d7513b35707"
+  "gitHead": "38917e6027299d6cd86008e2ccd005d90bbf89c0"
 }

package/bin/run

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-
-require('@oclif/command').run()
-  .then(require('@oclif/command/flush'))
-  .catch(require('@oclif/errors/handle'))

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.