@thegetty/quire-cli 1.0.0-rc.2 → 1.0.0-rc.20

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/LOGGING.md

@@ -0,0 +1,16 @@
+
+## Logging
+
+- https://betterstack.com/community/guides/logging/nodejs-logging-best-practices/
+
+### `debug-js`
+- https://github.com/debug-js/debug
+- https://github.com/commenthol/debug-level
+
+### Pino
+- https://betterstack.com/community/guides/logging/how-to-install-setup-and-use-pino-to-log-node-js-applications/
+- https://github.com/pinojs/pino
+
+### Winston
+- https://betterstack.com/community/guides/logging/how-to-install-setup-and-use-winston-and-morgan-to-log-node-js-applications/
+- https://github.com/winstonjs/winston

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/config/config-get.js

@@ -0,0 +1,35 @@
+import Command from '#src/Command.js'
+
+/**
+ * Quire CLI `config get` Command
+ *
+ * @class      ConfigGetCommand
+ * @extends    {Command}
+ */
+export default class ConfigGetCommand extends Command {
+  static definition = {
+    name: 'config-get',
+    description: 'Get the value of a Quire CLI configuration property',
+    summary: 'get a cli configuration property',
+    version: '1.0.0',
+    args: [
+      [ '[property]', 'configuration property' ]
+    ]
+  }
+
+  constructor() {
+    super(ConfigGetCommand.definition)
+  }
+
+  /**
+   * @param      {String}  key
+   * @param      {Object}  options
+   * @return     {Promise}
+   */
+  async action(property, options = {}) {
+    for (const [ key, value ] of Object.entries(this.config.store)) {
+      if (key.startsWith('__internal__') && !options.debug) continue
+      console.info(`${key}: ${JSON.stringify(value, null, 2)}`)
+    }
+  }
+}

package/src/commands/config/config-reset.js

@@ -0,0 +1,34 @@
+import Command from '#src/Command.js'
+
+/**
+ * Quire CLI `config reset` Command
+ *
+ * @class      ConfigResetCommand
+ * @extends    {Command}
+ */
+export default class ConfigResetCommand extends Command {
+  static definition = {
+    name: 'config-reset',
+    description: 'Reset the Quire CLI configuration to the default',
+    summary: 'reset cli configuration properties to default values',
+    version: '1.0.0',
+  }
+
+  constructor() {
+    super(ConfigResetCommand.definition)
+  }
+
+  /**
+   * @return     {Promise}
+   */
+  async action(options = {}) {
+    if (options.debug) {
+      console.info('Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    for (const [ key, value ] of Object.entries(this.config.store)) {
+      if (key.startsWith('__internal__') && !options.debug) continue
+      console.info(`${key}: ${JSON.stringify(value, null, 2)}`)
+    }
+  }
+}

package/src/commands/config/config-set.js

@@ -0,0 +1,37 @@
+import Command from '#src/Command.js'
+
+/**
+ * Quire CLI `config set` Command
+ *
+ * @class      ConfigCommand
+ * @extends    {Command}
+ */
+export default class ConfigSetCommand extends Command {
+  static definition = {
+    name: 'config-set',
+    description: 'Set a Quire CLI configuration property',
+    summary: 'set a cli configuration property',
+    version: '1.0.0',
+    args: [
+      [ '[key]', 'configuration property key' ],
+      [ '[value]', 'configuration property value' ]
+    ]
+  }
+
+  constructor() {
+    super(ConfigSetCommand.definition)
+  }
+
+  /**
+   * @param      {String}  key
+   * @param      {String}  value
+   * @param      {Object}  options
+   * @return     {Promise}
+   */
+  async action(key, value, options = {}) {
+    for (const [ key, value ] of Object.entries(this.config.store)) {
+      if (key.startsWith('__internal__') && !options.debug) continue
+      console.info(`${key}: ${JSON.stringify(value, null, 2)}`)
+    }
+  }
+}

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,14 +57,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/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,128 @@
+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'
+
+/**
+ * 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())
+    }
+
+    const versionFileName = this.config.get('versionFile')
+
+    try {
+      // 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.`
+      )
+      versionInfo = { cli: '<=1.0.0.rc-7' }
+      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,49 @@
-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 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(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 +80,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'
 
 /**