@thegetty/quire-cli 0.20.4 → 1.0.0-pre-release.1

package/CHANGELOG.md

@@ -1,46 +1,23 @@
-# Quire CLI Change Log
+# Changelog
 
-All notable changes to the `quire-cli` will be documented in this file. 
+All notable changes to the `quire-cli` will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+The log format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+Changelog entries are classified using the following labels:
 
-## [0.18.0] - 2020-02-03
-### Added
-+ Rollup configuration for minification
-+ Jest Test (tests run through each function that is included in the CLI)
-+ CircleCI configuration to run Jest Tests automatically on each pull request
-+ async/await instead of .then().catch()
-+ function to determine what GIT protocol to use to prevent permissions warnings
-+ eslint configuration
+- `Added`: for new features
 
-### Changed
-+ Documentation to reflect changes to install and use of CLI
-+ Version Number
-+ Replace kindlegen package with kindlegen from user-installed Kindle Previewer
+- `Bumped`: updated dependencies, only minor or higher will be listed
 
-### Removed
-- All author information from files
+- `Changed`: for changes in existing functionality
 
-### Security
-* Updated NodeJS/NPM dependencies
+- `Deprecated`: for once-stable features removed in upcoming releases
 
-### Fixed
-- fix id formatting for non h1 ids
+- `Fixed`: for any bug fixes
 
-## [0.17.0] - 2019-08-01
-### Added
-+ Prettier formatting 
+- `Removed`: for deprecated features removed in this release
 
-### Changed
-+ Ora to use string instead of arrays
-+ Version Number
 
-### Fixed
-- font issue
+## [Unreleased]
 
-[Unreleased]: https://github.com/gettypubs/quire-cli/compare/v0.18.0...HEAD
-[0.18.0]: https://github.com/gettypubs/quire-cli/compare/v0.17.0...v0.18.0
-[0.17.0]: https://github.com/gettypubs/quire-cli/releases/tag/v0.17.0

package/LICENSE

@@ -0,0 +1 @@
+Copyright (c) 2022, J Paul Getty Trust.

package/README.md

@@ -1,46 +1,11 @@
-# Quire 
-
-Developed by Getty, Quire is a new, multiformat publishing tool available for immediate access and use. Quire is in a limited beta, © J. Paul Getty Trust, and not yet released as open-source software. For a free license to use Quire, please complete [this form](https://docs.google.com/forms/d/e/1FAIpQLScKOJEq9ivhwizmdazjuhxBII-s-5SUsnerWmyF8VteeeRBhA/viewform).
-
 ## Quire CLI
 
-For information on **installing, updating, and uninstalling Quire (macOS + Windows) and Quire commands** please refer to the [Quire documentation](https://quire.getty.edu/documentation/install-uninstall/). 
-
-### **Developing the Quire CLI**
-
-1. Enter the quire root directory
-    ```tx
-    cd quire/packages/cli
-    ```
-2. Install devDependencies 
-    ```tx
-    npm install
-    ```
-3. Run Rollup.JS watch command to build as you make changes to the files or you can also build at any time with build
-    ```bash
-    # watch command
-    npm run watch
-    # build command
-    npm run build
-    ```
-4. The Quire CLI core code is under lib/ with an entry point of `index.js`
-
-5. If running the watch command `Control + C` to quit
-
-### **Testing the Quire CLI**
+The `quire-cli` implements the [command pattern](https://en.wikipedia.org/wiki/Command_pattern) to receive input from a user and delegate command behavoir to modules for the services, such as `git` and `11ty`, involved in working on Quire publications.
 
-1. Enter the quire root directory
-    ```tx
-    cd quire/packages/cli
-    ```
-2. Install devDependencies 
-    ```tx
-    npm install
-    ```
-3. Run Jest test command to run tests against the Quire CLI (**Must have completed the entire Quire CLI install process before testing.**)
-    ```tx
-    npm run test
+### Using the CLI
 
-## License
+`npx` supports executing npm package binaries even when they are not yet installed and will download the package into a cache if it does not find either a locally or globally installed version. Simply run
 
-Copyright © 2021, J Paul Getty Trust.
+```sh
+npx quire-cli --help
+```

package/bin/README.md

@@ -0,0 +1,34 @@
+## `@thegetty/quire-cli`
+
+The `bin/cli.js` module is the exported entry point for the [published `quire-cli` package](https://www.npmjs.com/package/@thegetty/quire-cli).
+
+### Running the CLI in development
+
+During development the `quire-cli` can be run locally by executing the `bin/cli.js` shell script, for example:
+
+```sh
+./bin/cli.js --help
+```
+
+The `bin/cli.js` module specifies the `node` environment and is configured to suppress Node.js warnings.
+
+```sh
+#!/usr/bin/env node --no-warnings
+```
+
+Additional options can be set using the `NODE_OPTIONS` environment variable, this sets the environment for the duration of the script only, for example:
+
+```sh
+#!/usr/bin/env NODE_OPTIONS=--no-warnings node
+```
+
+For a long digression down a reading rabbit-hole about supressing NodeJS warnings, see [nodejs/node#32876](https://github.com/nodejs/node/issues/32876).
+
+
+### Running the published CLI
+
+`npx` supports executing npm package binaries even when they are not yet installed and will download the package into a cache if it does not find either a locally or globally installed version. Simply run
+
+```sh
+npx quire-cli --help
+```

package/bin/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node --no-warnings
+import cli from '#src/main.js'
+import packageConfig from '#root/package.json' assert { type: 'json' }
+import updateNotifier from 'update-notifier'
+
+process.removeAllListeners('warning')
+
+const INTERVAL = Object.freeze({
+  MINUTES: 1000 * 60 * 1,
+  HOURLY: 1000 * 60 * 60,
+  DAILY: 1000 * 60 * 60 * 24,
+  WEEKLY: 1000 * 60 * 60 * 24 * 7
+})
+
+/**
+ * Check for quire-cli updates
+ * @see https://github.com/yeoman/update-notifier#usage
+ *
+ * @todo user configuration of choosen update interval
+ */
+const notifier = updateNotifier({
+  distTag: 'latest',
+  pkg: packageConfig,
+  updateCheckInterval: INTERVAL.DAILY,
+})
+
+notifier.notify()
+
+/**
+ * Run the cli program
+ */
+cli.parse()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "0.20.4",
+  "version": "1.0.0-pre-release.1",
   "author": "Getty Digital",
   "license": "J Paul Getty Trust",
   "bugs": {
@@ -12,72 +12,64 @@
     "cli",
     "quire"
   ],
+  "bin": {
+    "quire": "./bin/cli.js"
+  },
+  "exports": "./bin/cli.js",
+  "type": "module",
   "files": [
-    "bin"
+    "bin/",
+    "scripts/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
   ],
-  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/thegetty/quire.git",
     "directory": "packages/cli"
   },
   "scripts": {
-    "build": "./node_modules/.bin/rollup -c --compact",
-    "watch": "./node_modules/.bin/rollup -c -w --compact",
-    "test": "jest --verbose --colors --detectOpenHandles --runInBand",
-    "test:unit": "jest --verbose --colors --detectOpenHandles --runInBand unit/"
+    "lint": "eslint src --ext .js",
+    "lint:fix": "npm run lint -- --fix",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "bin": {
-    "quire": "./bin/index.js"
+  "imports": {
+    "#root/*": "./*",
+    "#src/*.js": "./src/*.js",
+    "#helpers/*.js": "./src/helpers/*.js",
+    "#lib/*.js": "./src/lib/*.js"
   },
   "dependencies": {
-    "@babel/runtime": "^7.7.7",
-    "axios": "^0.19.0",
-    "chalk": "^3.0.0",
-    "cheerio": "^1.0.0-rc.3",
-    "command-exists": "^1.2.8",
-    "commander": "^4.0.1",
-    "core-js": "^3.6.0",
-    "execa": "^4.0.0",
-    "file-url": "^3.0.0",
-    "fs-extra": "^8.1.0",
-    "glob": "~7.1.6",
-    "growl": "^1.10.5",
-    "hugo-bin": "^0.70.2",
-    "js-yaml": "^3.13.1",
-    "lodash": "^4.17.15",
-    "ora": "^4.0.3",
-    "regenerator-runtime": "^0.13.3",
-    "rimraf": "^3.0.0",
-    "sanitize-html": "^1.20.1",
-    "striptags": "^3.1.1",
-    "upath": "^1.2.0",
-    "webpack": "^4.41.4",
-    "yaml-front-matter": "^3.4.0"
+    "@11ty/eleventy": "^2.0.0-canary.16",
+    "boxen": "^7.0.0",
+    "chalk": "^5.1.2",
+    "commander": "^9.4.1",
+    "conf": "^10.2.0",
+    "cross-env": "^7.0.3",
+    "del": "^7.0.0",
+    "execa": "^6.1.0",
+    "fs-extra": "^10.1.0",
+    "hosted-git-info": "^6.1.1",
+    "i18next": "^22.0.4",
+    "inquirer": "^9.1.4",
+    "install-npm-version": "^1.0.8",
+    "loglevel": "^1.8.0",
+    "ora": "^6.1.2",
+    "semver": "^7.3.8",
+    "simple-git": "^3.14.1",
+    "update-notifier": "^6.0.2"
   },
   "devDependencies": {
-    "@babel/core": "*",
-    "@babel/plugin-transform-modules-commonjs": "*",
-    "@babel/plugin-transform-regenerator": "*",
-    "@babel/plugin-transform-runtime": "*",
-    "@babel/polyfill": "*",
-    "@babel/preset-env": "*",
-    "@rollup/plugin-alias": "^3.1.2",
-    "babel-jest": "*",
-    "jest": "*",
-    "jest-junit": "^10.0.0",
-    "rollup": "^1.27.13",
-    "rollup-plugin-babel": "^4.3.3",
-    "rollup-plugin-commonjs": "^10.1.0",
-    "rollup-plugin-copy": "^3.3.0",
-    "rollup-plugin-json": "^4.0.0",
-    "rollup-plugin-multi-entry": "^2.1.0",
-    "rollup-plugin-node-builtins": "^2.1.2",
-    "rollup-plugin-node-polyfills": "^0.2.1",
-    "rollup-plugin-node-resolve": "^5.2.0",
-    "rollup-plugin-preserve-shebang": "^0.1.6",
-    "rollup-plugin-replace": "^2.2.0",
-    "rollup-plugin-uglify": "^6.0.4",
-    "tmp": "0.1.0"
+    "del-cli": "^5.0.0",
+    "eslint": "^8.27.0"
+  },
+  "engines": {
+    "node": ">=14.16"
   }
 }

package/scripts/postinstall.js

@@ -0,0 +1,26 @@
+import chalk from 'chalk'
+
+// @todo use an i18n string for the documentation url
+const docsUrl = 'https://quire.getty.edu/docs/quire-cli/'
+
+const showSuccessMessage = () => {
+  const heading = chalk.inverse.green('Success!')
+  const messsage = chalk.magenta(
+    'Quire CLI installed! Please visit ',
+    chalk.underline(docsUrl),
+    ' for more information.'
+  )
+  console.log(heading, messsage)
+}
+
+try {
+  // check if the cli is a global installation of quire-cli
+  const npmArgs = JSON.parse(process.env['npm_config_argv'])
+  if (npmArgs.cooked && npmArgs.cooked.includes('--global')) {
+    showSuccessMessage()
+    // @todo run `quire-cli --help` on success
+    // cli('--help')
+  }
+} catch (error) {
+  // snafu
+}

package/src/Command.js

@@ -0,0 +1,50 @@
+/**
+ * Command
+ * @abstract
+ *
+ * @typedef CommandArgument
+ *
+ * @typedef CommandOption
+ *
+ */
+export default class Command {
+
+  /**
+   * @typedef CommandDefinition
+   * @property {String} name
+   * @property {Array<String>} aliases
+   * @property {String} descriptions
+   * @property {Array<CommandArgument>} args
+   * @property {Array<CommandOption>} options
+   * @property {String} version
+   * @property {Boolean} hidden
+   */
+  static definition = null
+
+  /**
+   * Constructs a new instance
+   *
+   * @param {CommandDefinition}  definition  The definition
+   */
+  constructor(definition) {
+    if (this.constructor.prototype === Command) {
+      throw new Error('Command is an *abstract* class')
+    }
+
+    this.name = definition.name
+    this.aliases = definition.aliases
+    this.description = definition.description
+    this.args = definition.args
+    this.options = definition.options
+    this.version = definition.version
+    this.hidden = definition.hidden
+  }
+
+  definition() {
+    return this.prototype.definition
+  }
+
+  action() {
+    throw Error(`Command '${this.name}' has not been implemented.`)
+  }
+}

package/src/README.md

@@ -0,0 +1,7 @@
+## Quire CLI Source Modules
+
+The primary entry point for the cli is the [`main.js`](/src/main.js) module in this directory.
+
+The `Command` module is an abstract class that is used in an interface pattern for individual cli commands. Modules added to the [`src/commands/`](/src/commands/) directory are automatically registered as subcommands of the `quire` cli.
+
+Thanks to [Fernando Doglio](https://fernandodoglio.substack.com/) for sharing [his implementation of this abstract command class pattern](https://blog.bitsrc.io/writing-an-extensible-cli-tool-in-2022-with-node-js-43eb03150be2), which inspired the implementation here.

package/src/commands/README.md

@@ -0,0 +1,221 @@
+## Quire CLI Commands
+
+### `build`
+
+Build Quire publication outputs.
+
+```sh
+quire build
+```
+
+#### `epub`
+
+Build Quire publication EPUB format.
+
+```sh
+quire build epub
+```
+
+#### `pdf`
+
+Build Quire publication PDF format.
+
+```sh
+quire build pdf
+```
+
+#### `site`
+
+Build Quire publication HTML format.
+
+```sh
+quire build site
+```
+
+### `clean`
+
+Remove build outputs.
+
+Note that this command is distinct from the [quire/11ty package](https://github.com/thegetty/quire/packages/11ty/package.json) script `clean`, to allow different behavoirs for Quire editors and developers.
+
+```sh
+quire clean --dry-run
+```
+
+### `configure`
+
+Edit a Quire project configuration.
+
+```sh
+quire configure
+```
+
+### `debug`
+
+Display Quire debugging information in the console.
+
+```sh
+quire debug
+```
+
+### `dev`
+
+Clone `quire/packages/11ty` into the local project.
+
+```sh
+quire dev
+```
+
+### `edit`
+
+Open or create a new content file in the default editor.
+
+```sh
+quire edit
+```
+
+### `install`
+
+Clone an existing project from a git repository.
+
+```sh
+quire install <repository>
+```
+
+### `new`
+
+Start a new Quire publication from a template project or clone an existing project from a git repository (equivalent to `install`).
+
+Running the `new` without any arguments will start an interactive prompt.
+
+```sh
+quire new
+```
+
+To start a new Quire project using the default starter run the following command:
+
+```sh
+quire new <path>
+```
+
+To create a new project from a starter template
+
+```sh
+quire new <path> <starter>
+```
+
+### `preview`
+
+Build and server the Quire site in development mode.
+
+```sh
+quire preview --port 8080
+```
+
+#### `epub`
+
+Preview the Quire publication epub in the default application.
+
+```sh
+quire preview epub --open
+```
+
+To preview the epub in Apple iBooks or Kindle Previewer
+
+```sh
+quire preview epub --open iBooks
+```
+
+```sh
+quire preview epub --open Kindle
+```
+
+#### `pdf`
+
+Preview the Quire publication PDF in the default application.
+
+```sh
+quire preview pdf --open
+```
+
+Preview the Quire publication PDF in an application.
+
+```sh
+quire preview pdf --open <Application>
+```
+
+#### `site`
+
+Build and serve the Quire site in development mode.
+
+```sh
+quire preview site
+```
+
+#### `server`
+
+Start a local web server to serve a previously built Quire site.
+
+```sh
+quire server --port 8080
+```
+
+### `version`
+
+Sets the Quire version to use when running commands on the project.
+
+```sh
+quire version 1.0.0
+```
+
+To set the quire version globally use the `--global` command flag.
+
+```sh
+quire version 1.0.0 --global
+```
+
+#### `info`
+
+Display the local and global `quire-11ty` version; this is the *default* subcommand (running `quire version` invokes the `info` subcommand).
+
+```sh
+quire version info
+```
+
+#### `install`
+
+```sh
+quire version install <version>
+```
+
+To reinstall a `quire-11ty` version run
+
+```sh
+quire version install <version> --force
+```
+
+#### `list`
+
+List installed versions of `quire-11ty`
+
+```sh
+quire version list
+```
+
+#### `prune`
+
+Remove outdated versions of `quire-11ty`
+
+```sh
+quire version prune
+```
+
+#### `remove` (alias `uninstall`)
+
+```sh
+quire version remove <version>
+```
+
+```sh
+quire version uninstall <version>
+```

package/src/commands/build.js

@@ -0,0 +1,65 @@
+import Command from '#src/Command.js'
+import { api, cli, paths, projectRoot  } from '#lib/11ty/index.js'
+import { clean } from '#helpers/clean.js'
+
+/**
+ * Quire CLI `build` Command
+ *
+ * Runs the Eleventy `build` to generate static output.
+ *
+ * @class      BuildCommand
+ * @extends    {Command}
+ */
+export default class BuildCommand extends Command {
+  static definition = {
+    name: 'build',
+    description: 'Generate publication outputs',
+    summary: 'run build',
+    version: '1.0.0',
+    args: [
+      // [
+      //   '[formats]', 'output formats',
+      //   {
+      //     choices: ['html', 'pdf', 'epub'],
+      //     default: ['html', 'html only']
+      //   }
+      // ],
+    ],
+    options: [
+      [ '-d', '--dry-run', 'run build without writing files' ],
+      [ '-q', '--quiet', 'run build with no console messages' ],
+      [ '-v', '--verbose', 'run build with verbose console messages' ],
+      [
+        '--11ty <module>', 'use the specified 11ty module', 'cli',
+        // { choices: ['api', 'cli'], default: 'cli' }
+      ],
+      [ '--debug', 'run build with debug output to console' ],
+    ],
+  }
+
+  constructor() {
+    super(BuildCommand.definition)
+  }
+
+  action(options, command) {
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    if (options['11ty'] === 'cli') {
+      console.debug('[CLI] running eleventy using lib/11ty cli')
+      cli.build(options)
+    } else {
+      console.debug('[CLI] running eleventy using lib/11ty api')
+      api.build(options)
+    }
+  }
+
+  preAction(command) {
+    const options = command.opts()
+    if (options.debug) {
+      console.debug('[CLI] Calling \'build\' command pre-action with options', options)
+    }
+    clean(projectRoot, paths, options)
+  }
+}