@thegetty/quire-cli 1.0.0-rc.3 → 1.0.0-rc.31

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/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/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

@@ -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 ],
     ],
   }
 
@@ -42,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
@@ -52,15 +57,22 @@ 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
-
-      if (options.eject) {
-        await quire.installInProject(projectPath, version, options)
-      } else {
-        await quire.install(version, options)
+      /**
+       * @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
       }
+
+      await quire.installInProject(projectPath, quireVersion, options)
     }
   }
 }

package/src/commands/epub.js

@@ -55,8 +55,7 @@ export default class EpubCommand extends Command {
   }
 
   /**
-   * test if build site has already be run and output can be reused
-   * @todo
+   * @todo test if build site has already be run and output can be reused
    */
   preAction(command) {
     const options = command.opts()

package/src/commands/info.js

@@ -0,0 +1,130 @@
+import Command from '#src/Command.js'
+import { execaCommand } from 'execa'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import testcwd from '#helpers/test-cwd.js'
+
+/**
+ * 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())
+    }
+
+    // Load filename from config with a default constraint if it doesn't exist
+    const versionFileName = this.config.get('versionFile')
+    let versionInfo = { cli: '<=1.0.0.rc-7' }
+
+    try {
+      const versionFileData = fs.readFileSync(versionFileName, { encoding: 'utf8' })
+
+      versionInfo = JSON.parse(versionFileData)      
+    } 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.`
+      )
+
+      fs.writeFileSync(versionFileName, JSON.stringify(versionInfo))
+    }
+
+    const { name: projectDirectory } = path.parse(process.cwd())
+
+    const versions = [
+      {
+        title: `[${projectDirectory}]`,
+        items: [
+          {
+            name: 'quire-cli',
+            get: () => versionInfo.cli,
+          },
+          {
+            name: 'quire-11ty',
+            get: () => {
+              const { version } = JSON.parse(fs.readFileSync('./package.json'))
+              return version
+            },
+          },
+          {
+            name: 'starter',
+            get: () => versionInfo.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/commands/pdf.js

@@ -1,10 +1,50 @@
-import Command from '#src/Command.js'
 import { paths, projectRoot  } from '#lib/11ty/index.js'
+import Command from '#src/Command.js'
 import fs from 'fs-extra'
 import libPdf from '#lib/pdf/index.js'
 import open from 'open'
 import path from 'node:path'
-// import testcwd from '#helpers/test-cwd.js'
+import { pathToFileURL } from 'node:url'
+import yaml from 'js-yaml'
+
+/**
+ * @function loadConfig(path) - loads and validates quire config, returns an empty object if not found
+ *  
+ * @param {path} string - file path to config file
+ * 
+ * @return {Object|undefined} User configuration object or undefined
+ * 
+ * @todo consider hardcoding a version check against .quire / project's package.json ver
+ */
+async function loadConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return undefined
+  }
+
+  const data = fs.readFileSync(configPath)
+  let config = yaml.load(data)
+
+  // NB: Schemas and validators are specific to the 11ty version of the project being built
+  const schemaPath = path.join(projectRoot,'_plugins','schemas','config.json')
+  const validatorPath = path.join(projectRoot, '_plugins', 'globalData', 'validator.js')
+
+  if (fs.existsSync(schemaPath) && fs.existsSync(validatorPath)) {
+
+    const { validateUserConfig } = await import(pathToFileURL(validatorPath))
+  
+    const schemaJSON = fs.readFileSync(schemaPath)
+    const schema = JSON.parse(schemaJSON)
+
+    try {
+      config = validateUserConfig('config', config, { config: schema })
+    } catch (error) {
+      console.error(error)
+      process.exit(1)
+    }
+  }
+
+  return config
+}
 
 /**
  * Quire CLI `pdf` Command
@@ -41,22 +81,32 @@ export default class PDFCommand extends Command {
       console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
     }
 
-    const input = path.join(projectRoot, paths.output, 'pdf.html')
+    const publicationInput = path.join(projectRoot, paths.output, 'pdf.html')
+    const coversInput = path.join(projectRoot, paths.output, 'pdf-covers.html')
 
-    if (!fs.existsSync(input)) {
-      console.error(`Unable to find PDF input at ${input}\nPlease first run the 'quire build' command.`)
-      return
+    const quireConfig = await loadConfig(path.join(projectRoot,'content','_data','config.yaml'))
+
+    if (quireConfig === undefined) {
+      console.error(`[quire pdf]: ERROR Unable to find a configuration file at ${path.join(projectRoot,'content','_data','config.yaml')}\nIs the command being run in a quire project?`)
+      process.exit(1)
+    }
+
+    if (!fs.existsSync(publicationInput)) {
+      console.error(`[quire pdf]: ERROR Unable to find PDF input at ${publicationInput}\nPlease first run the 'quire build' command.`)
+      process.exit(1)
     }
 
-    const output = path.join(projectRoot, `${options.lib}.pdf`)
+    const output = quireConfig.pdf !== undefined
+      ? path.join(paths.output, quireConfig.pdf.outputDir, `${quireConfig.pdf.filename}.pdf`)
+      : path.join(projectRoot, `${options.lib}.pdf`)
 
-    const pdfLib = await libPdf(options.lib, { debug: options.debug })
-    await pdfLib(input, output)
+    const pdfLib = await libPdf(options.lib, { ...options, pdfConfig: quireConfig.pdf })
+    await pdfLib(publicationInput, coversInput, output)
 
     try {
       if (fs.existsSync(output) && options.open) open(output)
     } catch (error) {
-      console.error(error)
+      console.error(`[quire pdf]: ERROR`,error)
       process.exit(1)
     }
   }

package/src/helpers/clean.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module for cleaning quire outputs
+ * @module clean
+ */
 import { deleteAsync } from 'del'
 import path from 'node:path'
 
@@ -9,6 +13,7 @@ import path from 'node:path'
  */
 export async function clean (projectRoot, paths, options = {}) {
   const pathsToClean = [
+    path.join(projectRoot, '.11ty-vite'),
     path.join(projectRoot, paths.epub),
     path.join(projectRoot, paths.output),
     path.join(projectRoot, '*.epub'),

package/src/helpers/is-empty.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module to test if a path is an empty directory
+ * @module is-empty
+ */
 import fs from 'node:fs'
 
 /**

package/src/helpers/is-quire.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module to test if a directory is a Quire project root
+ * @module is-quire
+ */
 import fs from 'node:fs'
 
 const QUIRE_DOT_FILES = Object.freeze([

package/src/helpers/os-utils.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module for cross platform dynamic imports
+ * @module os-utils
+ */
 import { pathToFileURL } from 'node:url'
 
 /**

package/src/helpers/test-cwd.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module to test the current working directory
+ * @module test-csd
+ */
 import isQuire from '#helpers/is-quire.js'
 
 /**

package/src/helpers/which.js

@@ -1,3 +1,7 @@
+/**
+ * A helper module to wrap the `which` utility
+ * @module which
+ */
 import which from 'which'
 
 /**

package/src/lib/11ty/cli.js

@@ -1,4 +1,5 @@
 import { execa } from 'execa'
+import fs from 'node:fs'
 import path from 'node:path'
 import paths, { eleventyRoot, projectRoot } from './paths.js'
 
@@ -17,9 +18,24 @@ const factory = (options = {}) => {
 
   /**
    * Use the version of Eleventy installed to `lib/quire/versions`
+   * 
+   * NB: in eleventy v3 the CLI extension (".cjs") is load-bearing but v2 is simply ".js"
+   * 
    */
-  const eleventy =
-    path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy', 'cmd.js')
+  const eleventyModuleDir = path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy')
+  const packagePath = path.join(eleventyModuleDir,'package.json')  
+
+  const pack = JSON.parse(fs.readFileSync(packagePath))
+
+  const { version } = pack
+
+  const eleventyMajorVer = version.split('.').at(0)
+
+  let eleventy = path.join(eleventyModuleDir,'cmd.cjs')
+
+  if ( Number(eleventyMajorVer) < 3 ) {
+    eleventy = path.join(eleventyModuleDir,'cmd.js')
+  }
 
   const command = [
     eleventy,

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 packageConfig from '#src/packageConfig.js'
+import schema from './schema.js'
+
+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