@thegetty/quire-cli 1.0.0-rc.9 → 1.0.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

@@ -1,4 +1,5 @@
 import Command from '#src/Command.js'
+import fs from 'fs-extra'
 import { quire } from '#src/lib/quire/index.js'
 
 /**
@@ -23,7 +24,7 @@ export default class CreateCommand extends Command {
     ],
     options: [
       [ '--quire-path <path>', 'local path to quire-11ty package' ],
-      [ '--quire-version <version>', 'quire-11ty version to install', 'latest' ],
+      [ '--quire-version <version>', 'quire-11ty version to install' ],
       // [ '--eject', 'install quire-11ty into the project directory', true ],
       [ '--debug', 'debug the `quire new` command', false ],
     ],
@@ -44,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
@@ -60,15 +63,16 @@ export default class CreateCommand extends Command {
        *   - interactive mode prompt to continue
        *   - non-interactive mode throw an error and exit the process
        */
-      await quire.initStarter(starter, projectPath, options)
-
-      options.eject = true
-
-      if (options.eject) {
-        await quire.installInProject(projectPath, options)
-      } else {
-        await quire.install(options)
+      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

@@ -2,11 +2,9 @@ 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 path from 'node: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,20 @@ export default class InfoCommand extends Command {
       console.debug('[CLI] Command \'%s\' called', this.name())
     }
 
-    let versionFile = fs.readFileSync(VERSION_FILE, { encoding: 'utf8' })
+    // 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 {
-      versionFile = JSON.parse(versionFile)
+      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.`
       )
-      versionFile = { cli: '<=1.0.0.rc-7' }
-      fs.writeFileSync(VERSION_FILE, JSON.stringify(versionFile))
+
+      fs.writeFileSync(versionFileName, JSON.stringify(versionInfo))
     }
 
     const { name: projectDirectory } = path.parse(process.cwd())
@@ -59,7 +64,7 @@ export default class InfoCommand extends Command {
         items: [
           {
             name: 'quire-cli',
-            get: () => versionFile.cli,
+            get: () => versionInfo.cli,
           },
           {
             name: 'quire-11ty',
@@ -70,7 +75,7 @@ export default class InfoCommand extends Command {
           },
           {
             name: 'starter',
-            get: () => versionFile.starter,
+            get: () => versionInfo.starter,
           },
         ],
       },

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/commands/validate.js

@@ -0,0 +1,64 @@
+import Command from '#src/Command.js'
+import { YAMLException } from 'js-yaml'
+import YamlValidationError from '../errors/validation/yaml-validation-error.js'
+import fs from 'fs-extra'
+import path from 'node:path'
+import { projectRoot  } from '#lib/11ty/index.js'
+import testcwd from '../helpers/test-cwd.js'
+import yamlValidation from '../validators/validate-yaml.js'
+
+
+/**
+ * Quire CLI `validate` Command
+ *  
+ * @class     ValidateCommand
+ * @extends   {Command}
+ */
+export default class ValidateCommand extends Command {
+  static definition = {
+    name: 'validate',
+    description: 'Validate configuration files',
+    summary: 'run validation',
+    version: '1.0.0',
+    options: [
+      [ '--debug', 'run validate with debug output to console' ],
+    ],
+  }
+
+  constructor() {
+    super(ValidateCommand.definition)
+  }
+
+  action(options, command){
+    if(options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
+    
+    const dataPath = path.join(projectRoot, 'content', '_data')
+    const files = fs.readdirSync(dataPath)
+      .filter(file => file.endsWith('.yaml') || file.endsWith('.yml'))
+      .map(file => path.join(dataPath, file)
+      )
+
+    let errorList = []
+    console.log('Validating YAML files..')
+
+    for (const file of files) {
+      try {
+        yamlValidation(file)
+      } catch (error){
+        errorList.push(error)
+      }
+    }
+
+    if(errorList.length > 0) {
+      errorList.forEach(err => { console.error(`${err.reason}`) })
+    } else {
+      console.log('Validation complete.')
+    }
+  }
+
+  preAction(options, command) {
+    testcwd(command)
+  }
+}

package/src/errors/validation/validation-error.js

@@ -0,0 +1,13 @@
+export default class ValidationError extends Error {
+  constructor(message, {filePath, reason, code} = {}) {
+    super(message)
+    this.name = this.constructor.name
+    this.filePath = filePath
+    this.reason = reason
+    this.code = code
+
+    if ('captureStackTrace' in Error) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+}

package/src/errors/validation/yaml-duplicate-error.js

@@ -0,0 +1,11 @@
+import ValidationError from './validation-error.js'
+
+export default class YamlDuplicateIdError extends ValidationError {
+  constructor(filePath, reason) {
+    super('Duplicate ID found in YAML file', {
+      filePath,
+      reason: reason,
+      code: 'YAML_DUPLICATE_ID_ERROR',
+    })
+  }
+}

package/src/errors/validation/yaml-parse-error.js

@@ -0,0 +1,11 @@
+import ValidationError from './validation-error.js'
+
+export default class YamlParseError extends ValidationError {
+  constructor(filePath, reason) {
+    super('Error parsing YAML file', {
+      filePath,
+      reason: reason,
+      code: 'YAML_PARSE_ERROR',
+    })
+  }
+}

package/src/errors/validation/yaml-validation-error.js

@@ -0,0 +1,11 @@
+import ValidationError from './validation-error.js'
+
+export default class YamlValidationError extends ValidationError {
+  constructor(filePath, reason) {
+    super('Error validating YAML file', {
+      filePath,
+      reason: reason,
+      code: 'YAML_VALIDATION_ERROR',
+    })
+  }
+}

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/api.js

@@ -42,6 +42,7 @@ const factory = async (options = {}) => {
   process.env.ELEVENTY_DATA = paths.data
   process.env.ELEVENTY_INCLUDES = paths.includes
   process.env.ELEVENTY_LAYOUTS = paths.layouts
+  process.env.QUIRE_DEBUG_LOG = options.debug
 
   /**
    * Get an instance of the runtime of eleventy.

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,
@@ -46,6 +62,7 @@ const factory = (options = {}) => {
     ELEVENTY_DATA: paths.data,
     ELEVENTY_INCLUDES: paths.includes,
     ELEVENTY_LAYOUTS: paths.layouts,
+    QUIRE_DEBUG_LOG: options.debug
   }
 
   if (options.debug) env.DEBUG = 'Eleventy*'
@@ -67,12 +84,18 @@ export default {
 
     env.ELEVENTY_ENV = 'production'
 
-    await execa('node', command, {
+    const build = execa('node', command, {
       all: true,
       cwd: projectRoot,
       env,
-      execPath: process.execPath
-    }).all.pipe(process.stdout)
+      nodePath: process.execPath
+    })
+    build.all.pipe(process.stdout)
+    await build
+
+    if (build.exitCode !== 0) {
+      process.exit(build.exitCode)
+    }
   },
 
   serve: async (options = {}) => {
@@ -90,7 +113,7 @@ export default {
       all: true,
       cwd: projectRoot,
       env,
-      execPath: process.execPath
+      nodePath: process.execPath
     }).all.pipe(process.stdout)
   }
 }

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]
+```