@thegetty/quire-cli 1.0.0-rc.17 → 1.0.0-rc.18

package/CHANGELOG.md

@@ -12,11 +12,32 @@ Changelog entries are classified using the following labels:
 - `Fixed`: for any bug fixes
 - `Removed`: for deprecated features removed in this release
 
+## [1.0.0-rc.18]
+
+### Added
+
+- Quire CLI configuration management using the `conf` package
+- `quire conf` command to manage cli configuration properties
+
+## [1.0.0-rc.17]
+
+### Bumped
+
+- `install-npm-version` patch version
+
+### Changed
+
+- update patch `install-npm-version`
+
 ## [1.0.0-rc.16]
 
+### Added
+
+- Patch for `install-npm-version`; see https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2
+
 ### Changed
 
-- Patch for `install-npm-version@8.0.0`; see https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2
+**Nota bene** installing `quire-cli` as a _local package_ requires running `npm install` with the `--install-strategy=nested` flag; installing `quire-cli` as a global node module has not changed.
 
 ### Fixed
 

package/bin/cli.js

@@ -1,28 +1,35 @@
 #!/usr/bin/env -S node --no-warnings
 
 import cli from '#src/main.js'
+import config from '#src/lib/conf/config.js'
 import packageConfig from '#root/package.json' assert { type: 'json' }
 import updateNotifier from 'update-notifier'
 
 process.removeAllListeners('warning')
 
+/**
+ * Interval constants in milliseconds
+ */
 const INTERVAL = Object.freeze({
-  MINUTES: 1000 * 60 * 1,
+  MINUTE: 1000 * 60 * 1,
   HOURLY: 1000 * 60 * 60,
   DAILY: 1000 * 60 * 60 * 24,
   WEEKLY: 1000 * 60 * 60 * 24 * 7
 })
 
+const updateChannel = config.get('updateChannel')
+const updateIterval = config.get('updateIterval')
+
 /**
- * Check for quire-cli updates
+ * Create a notifier to Check for quire-cli updates
  * @see https://github.com/yeoman/update-notifier#usage
  *
- * @todo user configuration of choosen update interval
+ * @todo refactor to check multiple channels
  */
 const notifier = updateNotifier({
-  distTag: 'latest',
+  distTag: updateChannel,
   pkg: packageConfig,
-  updateCheckInterval: INTERVAL.DAILY,
+  updateCheckInterval: INTERVAL[updateIterval],
 })
 
 notifier.notify({ defer: false })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.17",
+  "version": "1.0.0-rc.18",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -51,7 +51,7 @@
     "boxen": "^7.0.1",
     "chalk": "^5.2.0",
     "commander": "^10.0.0",
-    "conf": "^11.0.1",
+    "conf": "^13.1.0",
     "cross-env": "^7.0.3",
     "del": "^7.0.0",
     "epubjs-cli": "^0.1.6",
@@ -69,7 +69,7 @@
     "pagedjs-cli": "^0.4.3",
     "semver": "^7.3.8",
     "simple-git": "^3.16.0",
-    "update-notifier": "^6.0.2"
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "eslint": "^8.32.0"

package/src/Command.js

@@ -1,3 +1,5 @@
+import config from '#src/lib/conf/config.js'
+
 /**
  * Command
  * @abstract
@@ -12,6 +14,7 @@ export default class Command {
   /**
    * @typedef CommandDefinition
    * @property {String} name
+   * @property {String} alias
    * @property {Array<String>} aliases
    * @property {String} descriptions
    * @property {Array<CommandArgument>} args
@@ -24,6 +27,8 @@ export default class Command {
   /**
    * Constructs a new instance
    *
+   * Nota bene: Only the first command alias is displayed in the help.
+   *
    * @param {CommandDefinition}  definition  The definition
    */
   constructor(definition) {
@@ -31,6 +36,15 @@ export default class Command {
       throw new Error('Command is an *abstract* class')
     }
 
+    this.config = config // quire-cli configuration
+
+    /**
+     * Merge and deduplicate command definition alias and aliases
+     * Nota bene: Only the first command alias is displayed in the help.
+     */
+    // let aliases = Array.isArray(definition.aliases) ? definition.aliases || []
+    // aliases = new Set([ definition.alias, ...aliases ])
+
     this.name = definition.name
     this.aliases = definition.aliases
     this.description = definition.description

package/src/commands/conf.js

@@ -0,0 +1,43 @@
+import Command from '#src/Command.js'
+
+/**
+ * Quire CLI `conf` Command
+ *
+ * @class      ConfCommand
+ * @extends    {Command}
+ */
+export default class ConfCommand extends Command {
+  static definition = {
+    name: 'conf',
+    aliases: ['config', 'configure'],
+    description: 'Manage the Quire CLI configuration.',
+    summary: 'read/write quire-cli configuration options',
+    version: '1.0.0',
+    options: [
+      [ '--debug', 'run command in debug mode' ],
+    ],
+  }
+
+  constructor() {
+    super(ConfCommand.definition)
+  }
+
+  /**
+   * @param      {Object}  options
+   * @return     {Promise}
+   */
+  async action(key, value, options = {}) {
+    if (options.debug) {
+      console.info('Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    // this.outputHelp()
+
+    console.info('quire-cli configuration %s', this.config.path)
+
+    for (const [ key, value ] of Object.entries(this.config.store)) {
+      if (key.startsWith('__internal__') && !options.debug) continue
+      console.info('%s: %O', key, value)
+    }
+  }
+}

package/src/commands/create.js

@@ -45,6 +45,8 @@ export default class CreateCommand extends Command {
       console.info('Command \'%s\' called with options %o', CreateCommand.name, options)
     }
 
+    starter = starter || this.config.get('projectTemplate')
+
     if (!projectPath && !starter) {
       // @TODO implement this case of interactively selecting starter templates
       // from available subtrees in `lib/quire` module

package/src/commands/info.js

@@ -5,8 +5,6 @@ import os from 'node:os'
 import path from 'path'
 import testcwd from '#helpers/test-cwd.js'
 
-const VERSION_FILE = '.quire'
-
 /**
  * Quire CLI `info` Command
  *
@@ -22,7 +20,9 @@ export default class InfoCommand extends Command {
     summary: 'list info',
     version: '1.0.0',
     args: [],
-    options: [['--debug', 'include os versions in output']],
+    options: [
+      ['--debug', 'include os versions in output']
+    ],
   }
 
   constructor() {
@@ -40,15 +40,18 @@ export default class InfoCommand extends Command {
       console.debug('[CLI] Command \'%s\' called', this.name())
     }
 
-    let versionFile = fs.readFileSync(VERSION_FILE, { encoding: 'utf8' })
+    const versionFileName = this.config.get('versionFile')
+
     try {
-      versionFile = JSON.parse(versionFile)
+      // the quire version file is always local to the project root
+      let fileData = fs.readFileSync(versionFileName, { encoding: 'utf8' })
+      versionInfo = JSON.parse(fileData)
     } 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))
+      versionInfo = { cli: '<=1.0.0.rc-7' }
+      fs.writeFileSync(versionFileName, JSON.stringify(versionInfo))
     }
 
     const { name: projectDirectory } = path.parse(process.cwd())
@@ -59,7 +62,7 @@ export default class InfoCommand extends Command {
         items: [
           {
             name: 'quire-cli',
-            get: () => versionFile.cli,
+            get: () => versionInfo.cli,
           },
           {
             name: 'quire-11ty',
@@ -70,7 +73,7 @@ export default class InfoCommand extends Command {
           },
           {
             name: 'starter',
-            get: () => versionFile.starter,
+            get: () => versionInfo.starter,
           },
         ],
       },

package/src/lib/conf/README.md

@@ -0,0 +1,104 @@
+## CLI Configuration Manager
+
+This `quire-cli/lib/config` module manages reading and writing (persisting) options for the Quire CLI using the [`conf`](https://github.com/sindresorhus/conf) package.
+
+`conf` stores the config in the system default [user config directory](https://github.com/sindresorhus/env-paths#pathsconfig). For example, on macOS, the config file will be stored in the `~/Library/Preferences/@thegetty/quire-cli` directory.
+
+> Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config.
+
+### Configuration
+
+`logLevel` The default logging level for the Quire CLI output; default `'info'`.
+
+`projectTemplate` A default project starter template to use when creating new projects; default `'quire-starter-default'`.
+
+`quirePath` The relative path to `quire-11ty` installed in the project directory; default `./11ty`. When set to `null`, `quire-11ty` is installed to the CLI `lib/quire/versions/<version>/` directory.
+
+```sh
+❯ quire config quire-path '.'
+```
+
+`quireVersion` The default version of `quire-11ty` to install when creating new Quire projects; default `'latest'`.
+
+```sh
+❯ quire config quire-version '1.0.0'
+```
+
+`telemetry` Send anonymous data about Quire usage; default `false`.
+
+```sh
+❯ quire config telemetry --enabled
+```
+
+```sh
+❯ quire config telemetry --disabled
+```
+
+`updateChannels` A list of distribution tags to use when checking for version updates; default `['latest']`. To show notifications for pre-releases version updates include `'pre-release'` in the array of channels. This can be set using the configuration `--pre-release` command flag.
+
+```sh
+❯ quire config update-channels
+Quire configured to check for updates tagged 'latest'
+```
+
+```sh
+❯ quire config update-channels --add 'pre-release'
+Quire configured to check for updates tagged 'latest', 'pre-release'
+```
+
+```sh
+❯ quire config update-channels --rm 'pre-release'
+Quire configured to check for updates tagged 'latest'
+```
+
+`updateInterval` Interval at which to check for updates to the Quire CLI and project's `quire-11ty` version; default `'DAILY'`.
+
+```sh
+❯ quire config update-interval
+Quire configured to check for updates DAILY
+```
+
+```sh
+❯ quire config update-interval WEEKLY
+```
+
+`versionFile ['.quire-version']` The default file name for the `quire-11ty` version file.
+
+```sh
+❯ quire config version-file '.blargh'
+```
+
+### Quire CLI `config` Command
+
+Running the `config` command without any arguments will start an interactive prompt to configure Quire.
+
+To view an individual configuration value and its default value use:
+
+```sh
+❯ quire config [key]
+```
+
+To view the current `logLevel` setting for example:
+
+```sh
+❯ quire config logLevel
+loglevel: 'debug' (default 'info')
+```
+
+To set an individual configuration value, use the `set` argument:
+
+```sh
+❯ quire config set <key> <value>
+```
+
+To reset *all* keys to their default values, use the `reset` argument:
+
+```sh
+❯ quire config reset
+```
+
+To reset an individual key to its default value:
+
+```sh
+❯ quire config reset [key]
+```

package/src/lib/conf/config.js

@@ -0,0 +1,35 @@
+import Conf from 'conf'
+import defaults from './defaults.js'
+import migrations from './migrations.js'
+import schema from './schema.js'
+import packageConfig from '#root/package.json' assert { type: 'json' }
+
+const { name, version } = packageConfig
+
+const beforeEachMigration = (store, context) => {
+  const { fromVersion, toVersion } = context
+  console.info(`quire-cli migrating config from ${fromVersion} → ${toVersion}`)
+}
+
+/**
+ * Create quire-cli configuration instance
+ * @see https://github.com/sindresorhus/conf#confoptions
+ *
+ * @todo support yaml configuration files
+ * https://github.com/sindresorhus/conf?tab=readme-ov-file#can-i-use-yaml-or-another-serialization-format
+ *
+ * @type       {Conf}
+ */
+const config = new Conf({
+  beforeEachMigration,
+  clearInvalidConfig: true,
+  defaults,
+  migrations,
+  projectName: name,
+  projectSuffix: '',
+  projectVersion: version,
+  schema,
+  watch: true,
+})
+
+export default config

package/src/lib/conf/defaults.js

@@ -0,0 +1,37 @@
+/**
+ * Default values for Quire configuration properties
+ *
+ * Nota bene: these values will overwrite schema default values
+ * @see https://github.com/sindresorhus/conf#defaults
+ */
+export default {
+  /**
+   * Logging level for the Quire CLI output.
+   */
+  logLevel: 'info',
+  /**
+   * Project starter template to use when creating new projects.
+   */
+  projectTemplate: 'https://github.com/thegetty/quire-starter-default',
+  /**
+   * Relative path to quire-11ty installed in the project directory.
+   */
+  quire11tyPath: '.',
+  /**
+   * Version of quire-11ty to install when creating new projects.
+   */
+  quireVersion: 'latest',
+  /**
+   * Npm distribution tag to use when checking for version updates
+   */
+  updateChannel: 'rc',
+  /**
+   * Interval at which to check for updates to the Quire CLI
+   * and to quire-11ty version for a prject.
+   */
+  updateInterval: 'DAILY',
+  /**
+   * File name for the quire-11ty version file.
+   */
+  versionFile: '.quire',
+}

package/src/lib/conf/migrations.js

@@ -0,0 +1,11 @@
+/**
+ * Quire configuration migrations
+ * @see https://github.com/sindresorhus/conf#migrations
+ */
+const migrations = {
+  '1.0.0': (store) => {
+    store.set('updateChannel', 'latest')
+  }
+}
+
+export default migrations

package/src/lib/conf/schema.js

@@ -0,0 +1,30 @@
+/**
+ * Quire configuration schema
+ * @see https://github.com/sindresorhus/conf#schema
+ *
+ * Nota bene: schema default values will are overwritten by `defaults.js` values
+ * @see https://github.com/sindresorhus/conf#defaults
+ */
+export default {
+  logLevel: {
+    type: 'string'
+  },
+  projectTemplate: {
+    type: 'string'
+  },
+  quire11tyPath: {
+    type: 'string'
+  },
+  quireVersion: {
+    type: 'string'
+  },
+  updateChannel: {
+    type: 'string'
+  },
+  updateInterval: {
+    type: 'string'
+  },
+  versionFile: {
+    type: 'string'
+  }
+}

package/src/lib/quire/index.js

@@ -89,8 +89,6 @@ async function initStarter (starter, projectPath, options) {
     return
   }
 
-  starter = starter || 'https://github.com/thegetty/quire-starter-default'
-
   console.debug('[CLI:quire] init-starter',
     `\n  project root: "${projectPath}"`,
     `\n  starter: "${starter}"`

package/src/main.js

@@ -1,5 +1,6 @@
 import { Argument, Command, Option } from 'commander'
-import commands from './commands/index.js'
+import commands from '#src/commands/index.js'
+import config from '#lib/conf/config.js'
 import packageConfig from '../package.json' assert { type: 'json' }
 
 /**
@@ -12,7 +13,7 @@ import packageConfig from '../package.json' assert { type: 'json' }
 const program = new Command()
 
 program
-  .name('quire-cli')
+  .name('quire')
   .description('Quire command-line interface')
   .version(packageConfig.version,  '-v, --version', 'output quire version number')
   .configureHelp({
@@ -23,9 +24,12 @@ program
 
 /**
  * Register each command as a subcommand of this program
+ *
+ * @todo refactor command definition to allow for per-command custom help text
+ * @see https://github.com/tj/commander.js?tab=readme-ov-file#automated-help
  */
 commands.forEach((command) => {
-  const { action, aliases, args, description, name, options } = command
+  const { action, alias, aliases, args, description, name, options } = command
 
   const subCommand = program
     .command(name)
@@ -33,8 +37,12 @@ commands.forEach((command) => {
     .addHelpCommand()
     .showHelpAfterError()
 
+  if (alias instanceof String) {
+    subCommand.alias(alias)
+  }
+
   if (Array.isArray(aliases)) {
-    aliases.forEach((alias) => subCommand.alias(alias))
+    subCommand.aliases(aliases)
   }
 
   /**
@@ -103,6 +111,11 @@ commands.forEach((command) => {
 
   // subCommand.action((args) => action.apply(command, args))
   subCommand.action(action)
+
+  /**
+   * Inject the CLI configuration into commands
+   */
+  subCommand.config = config
 })
 
 /**

package/src/lib/config/README.md

@@ -1,3 +0,0 @@
-## CLI Configuration Manager
-
-This `quire-cli/lib/config` module orchestrates creation of new projects and management of existing project configuration.

package/src/lib/config/index.js

@@ -1 +0,0 @@
-import semver from 'semver'