@thegetty/quire-cli 1.0.0-rc.5 → 1.0.0-rc.50

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/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/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,
@@ -67,12 +83,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)
+    })
+    build.all.pipe(process.stdout)
+    await build
+
+    if (build.exitCode !== 0) {
+      process.exit(build.exitCode)
+    }
   },
 
   serve: async (options = {}) => {