@thegetty/quire-cli 1.0.0-rc.1 → 1.0.0-rc.10

package/CHANGELOG.md

@@ -18,6 +18,24 @@ Changelog entries are classified using the following labels:
 
 - `Removed`: for deprecated features removed in this release
 
+## [1.0.0-rc.10]
 
-## [Unreleased]
+### Added
+- Support semantic version ranges for `quire-11ty` in quire starter projects and the `--quire-version` option of the `quire new` command, and use the latest compatible `quire-11ty` version when creating and installing a new project.
 
+## [1.0.0-rc.9]
+
+### Added
+- Update old `.quire` files  when running `info` command on versions prior to `1.0.0-rc.8`
+- Include `quire-cli` version used to generate project in `info` output
+- Adds headings to `info` output
+
+## [1.0.0-rc.8]
+
+### Added
+- Added `info` command to output package versions
+
+## [1.0.0-rc.7]
+
+### Added
+- Added `new` command `--quire-path` option to support development with local version of `quire-11ty`

package/bin/cli.js

@@ -20,12 +20,12 @@ const INTERVAL = Object.freeze({
  * @todo user configuration of choosen update interval
  */
 const notifier = updateNotifier({
-  distTag: 'rc',
+  distTag: 'latest',
   pkg: packageConfig,
   updateCheckInterval: INTERVAL.DAILY,
 })
 
-notifier.notify()
+notifier.notify({ defer: false })
 
 /**
  * Run the cli program

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.10",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -51,7 +51,7 @@
     "conf": "^11.0.1",
     "cross-env": "^7.0.3",
     "del": "^7.0.0",
-    "epubjs-cli": "^0.1.1",
+    "epubjs-cli": "^0.1.3",
     "execa": "^6.1.0",
     "fs-extra": "^11.1.0",
     "hosted-git-info": "^6.1.1",

package/src/commands/README.md

@@ -16,6 +16,14 @@ Build Quire publication EPUB format.
 quire build epub
 ```
 
+#### `info`
+
+List `quire-11ty`, `quire-cli`, and starter package versions; use the `--debug` option to include node, npm, and os versions.
+
+```sh
+quire build info
+```
+
 #### `pdf`
 
 Build Quire publication PDF format.
@@ -80,6 +88,26 @@ To create a new project from a starter template
 quire new <path> <starter>
 ```
 
+#### Specifying the `quire-11ty` version
+
+When the `--quire` flag is used the new project will be started using the specified version of `quire-11ty`
+
+```sh
+quire new <path> <starter> --quire <version>
+```
+
+##### Version identifiers
+
+The `--quire` flag must be either a semantic version identifier or a npm distribution tag. For example:
+
+```sh
+quire new ./blargh --quire 1.0.0-rc.5
+```
+
+```sh
+quire new ./blargh --quire latest
+```
+
 ### `preview`
 
 Build and server the Quire site in development mode.
@@ -134,14 +162,6 @@ To set the quire version globally use the `--global` command flag.
 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

package/src/commands/create.js

@@ -1,4 +1,5 @@
 import Command from '#src/Command.js'
+import fs from 'fs-extra'
 import { quire } from '#src/lib/quire/index.js'
 
 /**
@@ -22,8 +23,10 @@ export default class CreateCommand extends Command {
       [ '[starter]', 'repository url or local path for a starter project' ],
     ],
     options: [
-      [ '--debug', 'debug the `quire new` command' ],
-      [ '--eject', 'install quire-11ty into the project directory', 'true' ],
+      [ '--quire-path <path>', 'local path to quire-11ty package' ],
+      [ '--quire-version <version>', 'quire-11ty version to install' ],
+      // [ '--eject', 'install quire-11ty into the project directory', true ],
+      [ '--debug', 'debug the `quire new` command', false ],
     ],
   }
 
@@ -52,14 +55,27 @@ export default class CreateCommand extends Command {
       // const starter = starters['default']
       // `git clone starter path`
     } else {
-      const version = await quire.initStarter(starter, projectPath)
-      // @TODO we will want to abstract the test for emptiness to prevent further install steps on error
-      if (!version) return
+      /**
+       * @TODO test that `version` is compatible with the `requiredVersion`
+       * if version is incompatible or unknown
+       *   - interactive mode prompt to continue
+       *   - non-interactive mode throw an error and exit the process
+       */
+      let quireVersion
+      try {
+        quireVersion = await quire.initStarter(starter, projectPath, options)
+      } catch (error) {
+        console.error(error.message)
+        fs.removeSync(projectPath)
+        return
+      }
+
+      options.eject = true
 
       if (options.eject) {
-        await quire.installInProject(projectPath, version, options)
+        await quire.installInProject(projectPath, quireVersion, options)
       } else {
-        await quire.install(version, options)
+        await quire.install(options)
       }
     }
   }

package/src/commands/info.js

@@ -0,0 +1,125 @@
+import Command from '#src/Command.js'
+import { execaCommand } from 'execa'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'path'
+import testcwd from '#helpers/test-cwd.js'
+
+const VERSION_FILE = '.quire'
+
+/**
+ * Quire CLI `info` Command
+ *
+ * Runs the Eleventy `info` command to list the quire-cli, quire-11ty, node, and npm versions.
+ *
+ * @class      InfoCommand
+ * @extends    {Command}
+ */
+export default class InfoCommand extends Command {
+  static definition = {
+    name: 'info',
+    description: 'List Quire cli, quire-11ty, and node versions',
+    summary: 'list info',
+    version: '1.0.0',
+    args: [],
+    options: [['--debug', 'include os versions in output']],
+  }
+
+  constructor() {
+    super(InfoCommand.definition)
+  }
+
+  async action(options, command) {
+    if (options.debug) {
+      console.debug(
+        '[CLI] Command \'%s\' called with options %o',
+        this.name(),
+        options
+      )
+    } else {
+      console.debug('[CLI] Command \'%s\' called', this.name())
+    }
+
+    let versionFile = fs.readFileSync(VERSION_FILE, { encoding: 'utf8' })
+    try {
+      versionFile = JSON.parse(versionFile)
+    } catch (error) {
+      console.warn(
+        `This project was generated with the quire-cli prior to version 1.0.0.rc-8. Updating the version file to the new format, though this project's version file will not contain specific starter version information.`
+      )
+      versionFile = { cli: '<=1.0.0.rc-7' }
+      fs.writeFileSync(VERSION_FILE, JSON.stringify(versionFile))
+    }
+
+    const { name: projectDirectory } = path.parse(process.cwd())
+
+    const versions = [
+      {
+        title: `[${projectDirectory}]`,
+        items: [
+          {
+            name: 'quire-cli',
+            get: () => versionFile.cli,
+          },
+          {
+            name: 'quire-11ty',
+            get: () => {
+              const { version } = JSON.parse(fs.readFileSync('./package.json'))
+              return version
+            },
+          },
+          {
+            name: 'starter',
+            get: () => versionFile.starter,
+          },
+        ],
+      },
+      {
+        title: '[System]',
+        items: [
+          {
+            name: 'quire-cli',
+            get: async () => {
+              const { stdout } = await execaCommand('quire --version')
+              return stdout
+            },
+          },
+          {
+            debug: true,
+            name: 'node',
+            get: () => process.version,
+          },
+          {
+            debug: true,
+            name: 'npm',
+            get: async () => {
+              const { stdout } = await execaCommand('npm --version')
+              return stdout
+            },
+          },
+          {
+            debug: true,
+            name: 'os',
+            get: () => `${os.type()} ${os.release()}`,
+          },
+        ],
+      },
+    ]
+
+    /**
+     * Filter the command output based on `debug` settings
+     */
+    versions.forEach(async ({ items, title }) => {
+      const versions = await Promise.all(
+        items
+          .filter(({ debug }) => !debug || (options.debug && debug))
+          .map(async ({ name, get }) => `${name} ${await get()}`)
+      )
+      console.info(`${title}\n ${versions.join('\n ')}`)
+    })
+  }
+
+  preAction(command) {
+    testcwd(command)
+  }
+}

package/src/lib/epub/index.js

@@ -11,7 +11,9 @@ const __dirname = path.dirname(__filename)
 export default async (name = 'epubjs', options = {}) => {
   const lib = { name, options, path }
 
-  switch (lib.toLowerCase()) {
+  const normalizedName = name.replace(/[-_.\s]/g, '').toLowerCase()
+
+  switch (normalizedName) {
     case 'epubjs': {
       lib.name = 'Epub.js'
       lib.options = {}

package/src/lib/pdf/index.js

@@ -11,7 +11,9 @@ const __dirname = path.dirname(__filename)
 export default async (name = 'pagedjs', options = {}) => {
   const lib = { name, options, path }
 
-  switch (name.toLowerCase()) {
+  const normalizedName = name.replace(/[-_.\s]/g, '').toLowerCase()
+
+  switch (normalizedName) {
     case 'paged':
     case 'pagedjs': {
       lib.name = 'Paged.js'

package/src/lib/quire/index.js

@@ -3,9 +3,11 @@ import { chdir, cwd } from 'node:process'
 import { execa, execaCommand } from 'execa'
 import { fileURLToPath } from 'node:url'
 import { isEmpty } from '#helpers/is-empty.js'
+import fetch from 'node-fetch'
 import fs from 'fs-extra'
 import git from '#src/lib/git/index.js'
 import inv from 'install-npm-version'
+import packageConfig from '#root/package.json' assert { type: 'json' }
 import path from 'node:path'
 import semver from 'semver'
 
@@ -48,25 +50,19 @@ function getVersion(projectPath) {
 }
 
 /**
- * Read the required `quire-11ty` version from starter `package.json` `peerDependencies`
+ * Read the required `quire-11ty` and starter versions from starter `package.json` `peerDependencies`
  *
  * @param    {String}   projectPath  Absolute system path to the project root
  *
- * @return  {String}  version  Quire-11ty semantic version with caret or other
- * comparators trimmed off the beginning
- *
- * @TODO refactor `latest()` function to programmatically return a specific
- * version of `@thegetty/quire-11ty` from a semantic version string
- * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`) so this string-trimming
- * logic can be removed
+ * @return  {Object}
+ * @property {String} quire11tyVersion  Latest compatible Quire-11ty semantic version
+ * @property {String} starterVersion  Starter project version defined in the starter package.json
  */
-async function getVersionFromStarter(projectPath) {
-  const packageConfig = fs.readFileSync(path.join(projectPath, 'package.json'), { encoding:'utf8' })
-  const { peerDependencies } = JSON.parse(packageConfig)
-  const version = peerDependencies[PACKAGE_NAME]
-  return version === 'latest'
-    ? await latest()
-    : version.substr(version.search(/\d/))
+async function getVersionsFromStarter(projectPath) {
+  const projectPackageConfig = fs.readFileSync(path.join(projectPath, 'package.json'), { encoding:'utf8' })
+  const { peerDependencies, version: starterVersion } = JSON.parse(projectPackageConfig)
+  const quire11tyVersion = peerDependencies[PACKAGE_NAME]
+  return { quire11tyVersion, starterVersion }
 }
 
 /**
@@ -79,7 +75,7 @@ async function getVersionFromStarter(projectPath) {
  * @return   {String}   quireVersion  A string indicating the current version
  *                                    of quire being used with a new project
  */
-async function initStarter (starter, projectPath) {
+async function initStarter (starter, projectPath, options) {
   projectPath = projectPath || cwd()
 
   // ensure that the target path exists
@@ -110,12 +106,24 @@ async function initStarter (starter, projectPath) {
     .catch((error) => console.error('[CLI:error] ', error))
 
   /**
-   * Determine `quire-11ty` version required by the starter project
-   * and write a `.quire` file with the semantic version string.
+   * Determine the `quire-11ty` version to use in the new project,
+   * from the `quireVersion` option or as required by the starter project.
+   *
+   * Uses `latest` to get the latest semantic version compatible with version ranges
    */
-  const quireVersion = await getVersionFromStarter(projectPath)
+  const { quire11tyVersion, starterVersion } = await getVersionsFromStarter(projectPath)
+  const quireVersion = await latest(options.quireVersion || quire11tyVersion)
   setVersion(projectPath, quireVersion)
 
+  /**
+   * Write quire-11ty, cli, starter name and version to VERSION_FILE
+   */
+  const versionInfo = { 
+    cli: packageConfig.version,
+    starter: `${starter}@${starterVersion}`,
+  }
+  fs.writeFileSync(path.join(projectPath, VERSION_FILE), JSON.stringify(versionInfo))
+
   // Re-initialize project directory as a new git repository
   await fs.remove(path.join(projectPath, '.git'))
 
@@ -135,18 +143,19 @@ async function initStarter (starter, projectPath) {
    */
   const projectFiles = fs.readdirSync(projectPath)
   await git.init().add(projectFiles).commit('Initial Commit')
-
   return quireVersion
 }
 
 /**
- * Install a specific version of `quire-11ty`
+ * Install `quire-11ty`, default to 'latest' version
+ *
+ * @TODO refactor this to be callable by the installInProject method
  *
- * @param  {String}  version  Quire-11ty semantic version
  * @param  {Object}  options  options passed from `quire new` command
  * @return  {Promise}
  */
-async function install(version, options={}) {
+async function install(options = {}) {
+  const version = options.quireVersion || 'latest'
   console.debug(`[CLI:quire] installing quire-11ty@${version}`)
   const absoluteInstallPath = path.join(__dirname, 'versions')
   fs.ensureDirSync(absoluteInstallPath)
@@ -185,19 +194,23 @@ async function install(version, options={}) {
 }
 
 /**
- * Install a specific version of `quire-11ty` directly into a quire project
+ * Install `quire-11ty` directly into a quire project
+ *
+ * @TODO refactor this to use the install method with pre and post-install hooks
+ * or steps to prepare the working directory and cleanup on error and completion
  *
  * @param  {String}  projectPath  Absolute system path to the project root
- * @param  {String}  version  Quire-11ty semantic version
  * @param  {Object}  options  options passed from `quire new` command
  * @return  {Promise}
  */
-async function installInProject(projectPath, version, options={}) {
-  console.debug(`[CLI:quire] installing quire-11ty@${version} into ${projectPath}`)
+async function installInProject(projectPath, quireVersion, options = {}) {
+  const { quirePath } = options
+  const quire11tyPackage = fs.existsSync(quirePath) ? quirePath : `${PACKAGE_NAME}@${quireVersion}`
+  console.debug(`[CLI:quire] installing ${quire11tyPackage} into ${projectPath}`)
 
   /**
-   * delete `package.json` from starter project, as it will be replaced with
-   * `package.json` from `@thegetty/quire-11ty`
+   * Delete the starter project package configuration so that it can be replaced
+   * with the `@thegetty/quire-11ty` configuration
    * @TODO If a user runs quire eject at a later date we may want to merge their
    * package.json with the `quire-11ty` dev dependencies, scripts, etc
    */
@@ -220,7 +233,7 @@ async function installInProject(projectPath, version, options={}) {
     Verbosity: options.debug ? 'Debug' : 'Silent',
     WorkingDirectory: projectPath
   }
-  await inv.Install(`${PACKAGE_NAME}@${version}`, installOptions)
+  await inv.Install(quire11tyPackage, installOptions)
 
   // delete empty `node_modules` directory that `install-npm-version` creates
   const invNodeModulesDir = path.join(projectPath, 'node_modules')
@@ -262,25 +275,27 @@ async function installInProject(projectPath, version, options={}) {
 
 /**
  * Retrieve latest published version of the `quire-11ty` package
-
- * @todo refactor to programmatically return a specific version
- * of `@thegetty/quire-11ty` from a semantic version string
- * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`)
- * so that the latest function may be used like:
- *  await latest('^1.0.0-pre-release.0') => '1.0.0-pre-release.2'
- *
- * Nota bene: `npm view [<@scope>/]<name>[@<version>] version`
- * @see https://docs.npmjs.com/cli/v7/commands/npm-view
- * returns a list of versions that satisfy the `<version>` range specifier,
- * piping this to execa `stdout` we get only the last line of output.
- * @todo use [`parse-columns`](https://github.com/sindresorhus/parse-columns)
- * to parse the column formated list of versions returned by `npm view`
- *
+ * or the latest compatible version with the provided semantic version string
+ * 
+ * @param {String} version A semantic version string, i.e `^1.0.0-pre-release.0`
+ * 
  * @return {String} `quire-11ty@latest` semantic version string
  */
-async function latest() {
-  const { stdout: quireVersion } =
-    await execa('npm', ['view', PACKAGE_NAME, 'version'])
+async function latest(version) {
+  let quireVersion;
+  if (!version || version === 'latest') {
+    const { stdout } = 
+      await execa('npm', ['view', PACKAGE_NAME, 'version'])
+    quireVersion = stdout
+  } else {
+    const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}`)
+    const json = await response.json()
+    const versions = Object.keys(json.versions)
+    quireVersion = semver.maxSatisfying(versions, version)
+  }
+  if (!quireVersion) {
+    throw new Error(`[CLI:quire] Sorry, we couldn't find a version of quire-11ty compatible with the version "${version}". You can set the quire-11ty version in the starter project's package.json or specify a version when running \`quire new\` with the \`--quire-version\` flag. You can run \`npm view @thegetty/quire-11ty versions\` to view all versions.`)
+  }
   return quireVersion
 }
 
@@ -314,16 +329,11 @@ async function remove(version) {
 /**
  * Sets the quire-11ty version for a project
  *
- * @param  {String}  version  Quire-11ty semantic version
+ * @param  {String}  version  a version identifier or distribution tag
  */
 function setVersion(projectPath, version) {
-  if (!version) {
-    console.error('[CLI] no version specified')
-  }
   const projectName = path.basename(projectPath)
   console.info(`${projectName} set to use quire-11ty@${version}`)
-  const versionFilePath = path.join(projectPath, VERSION_FILE)
-  fs.writeFileSync(versionFilePath, version)
 }
 
 /**