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

package/src/lib/quire/index.js

@@ -3,9 +3,11 @@ import { chdir, cwd } from 'node:process'
 import { execa, execaCommand } from 'execa'
 import { fileURLToPath } from 'node:url'
 import { isEmpty } from '#helpers/is-empty.js'
+import config from '#lib/conf/config.js'
+import fetch from 'node-fetch'
 import fs from 'fs-extra'
-import git from '#src/lib/git/index.js'
-import inv from 'install-npm-version'
+import git from '#lib/git/index.js'
+import packageConfig from '#src/packageConfig.js'
 import path from 'node:path'
 import semver from 'semver'
 
@@ -15,17 +17,19 @@ const __dirname = path.dirname(__filename)
 // Version install path is relative to process working directory
 const INSTALL_PATH = path.join('src', 'lib', 'quire', 'versions')
 const PACKAGE_NAME = '@thegetty/quire-11ty'
-const VERSION_FILE = '.quire'
+
+const QUIRE_VERSION = config.get('quireVersion')
+const VERSION_FILE = config.get('versionFile')
 
 /**
- * Return an absolute path to an installed `quire-11ty` version
+ * Return an absolute path to an installed quire-11ty version
  *
- * @return  {String}  path to installed `quire-11ty` version
+ * @return  {String}  path to installed quire-11ty version
  */
-function getPath(version='latest') {
-  const absolutePath = path.relative('/', `${INSTALL_PATH}/${version}`)
+function getPath(version=QUIRE_VERSION) {
+  const absolutePath = path.relative('/', path.join(INSTALL_PATH, version))
   if (!fs.existsSync(absolutePath)) {
-    console.error(`[CLI:quire] \`quire-11ty@${version}\` is not installed`)
+    console.error(`[CLI:quire] quire-11ty@${version} is not installed`)
     return null
   }
   console.debug(`[CLI:quire] %s`, absolutePath)
@@ -33,7 +37,7 @@ function getPath(version='latest') {
 }
 
 /**
- * Read the required `quire-11ty` version for the project `.quire` file
+ * Read the required quire-11ty version for the quire version file
  *
  * @param    {String}   projectPath  Absolute system path to the project root
  *
@@ -48,25 +52,19 @@ function getVersion(projectPath) {
 }
 
 /**
- * Read the required `quire-11ty` version from starter `package.json` `peerDependencies`
+ * Read required quire-11ty and starter versions from starter peerDependencies
  *
  * @param    {String}   projectPath  Absolute system path to the project root
  *
- * @return  {String}  version  Quire-11ty semantic version with caret or other
- * comparators trimmed off the beginning
- *
- * @TODO refactor `latest()` function to programmatically return a specific
- * version of `@thegetty/quire-11ty` from a semantic version string
- * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`) so this string-trimming
- * logic can be removed
+ * @return  {Object}
+ * @property {String} quire11tyVersion  Latest compatible Quire-11ty semantic version
+ * @property {String} starterVersion  Starter project version defined in the starter package.json
  */
-async function getVersionFromStarter(projectPath) {
-  const packageConfig = fs.readFileSync(path.join(projectPath, 'package.json'), { encoding:'utf8' })
-  const { peerDependencies } = JSON.parse(packageConfig)
-  const version = peerDependencies[PACKAGE_NAME]
-  return version === 'latest'
-    ? await latest()
-    : version.substr(version.search(/\d/))
+async function getVersionsFromStarter(projectPath) {
+  const projectPackageConfig = fs.readFileSync(path.join(projectPath, 'package.json'), { encoding:'utf8' })
+  const { peerDependencies, version: starterVersion } = JSON.parse(projectPackageConfig)
+  const quire11tyVersion = peerDependencies[PACKAGE_NAME]
+  return { quire11tyVersion, starterVersion }
 }
 
 /**
@@ -79,7 +77,7 @@ async function getVersionFromStarter(projectPath) {
  * @return   {String}   quireVersion  A string indicating the current version
  *                                    of quire being used with a new project
  */
-async function initStarter (starter, projectPath) {
+async function initStarter (starter, projectPath, options) {
   projectPath = projectPath || cwd()
 
   // ensure that the target path exists
@@ -93,11 +91,9 @@ async function initStarter (starter, projectPath) {
     return
   }
 
-  starter = starter || 'https://github.com/thegetty/quire-starter-default'
-
   console.debug('[CLI:quire] init-starter',
-    `\n  project root: "${projectPath}"`,
-    `\n  starter: "${starter}"`
+    `\n  project: ${path.join(__dirname, projectPath)}`,
+    `\n  starter: ${starter}`
   )
 
   /**
@@ -110,12 +106,24 @@ async function initStarter (starter, projectPath) {
     .catch((error) => console.error('[CLI:error] ', error))
 
   /**
-   * Determine `quire-11ty` version required by the starter project
-   * and write a `.quire` file with the semantic version string.
+   * Determine the quire-11ty version to use in the new project,
+   * from the quireVersion option or as required by the starter project.
+   *
+   * Uses 'latest' to get the latest semantic version compatible with version ranges
    */
-  const quireVersion = await getVersionFromStarter(projectPath)
+  const { quire11tyVersion, starterVersion } = await getVersionsFromStarter(projectPath)
+  const quireVersion = await latest(options.quireVersion || quire11tyVersion)
   setVersion(projectPath, quireVersion)
 
+  /**
+   * Write quire-11ty, quire-cli, starter versions to the version file
+   */
+  const versionInfo = {
+    cli: packageConfig.version,
+    starter: `${starter}@${starterVersion}`,
+  }
+  fs.writeFileSync(path.join(projectPath, VERSION_FILE), JSON.stringify(versionInfo))
+
   // Re-initialize project directory as a new git repository
   await fs.remove(path.join(projectPath, '.git'))
 
@@ -135,69 +143,28 @@ async function initStarter (starter, projectPath) {
    */
   const projectFiles = fs.readdirSync(projectPath)
   await git.init().add(projectFiles).commit('Initial Commit')
-
   return quireVersion
 }
 
 /**
- * Install a specific version of `quire-11ty`
+ * Install `quire-11ty` directly into a quire project
  *
- * @param  {String}  version  Quire-11ty semantic version
- * @param  {Object}  options  options passed from `quire new` command
- * @return  {Promise}
- */
-async function install(version, options={}) {
-  console.debug(`[CLI:quire] installing quire-11ty@${version}`)
-  const absoluteInstallPath = path.join(__dirname, 'versions')
-  fs.ensureDirSync(absoluteInstallPath)
-  /**
-   * `Destination` is relative to `node_modules` of the working-directory
-   * so we have included a relative path to parent directory in order to
-   * install versions to a different local path.
-   * @see https://github.com/scott-lin/install-npm-version
-   */
-  const installOptions = {
-    Destination: path.join('..', version),
-    Debug: false,
-    Overwrite: options.force || options.overwrite || false,
-    Verbosity: options.debug ? 'Debug' : 'Silent',
-    WorkingDirectory: absoluteInstallPath
-  }
-  await inv.Install(`${PACKAGE_NAME}@${version}`, installOptions)
-
-  // delete empty `node_modules` directory that `install-npm-version` creates
-  const invNodeModulesDir = path.join(absoluteInstallPath, 'node_modules')
-  if (fs.existsSync(invNodeModulesDir)) fs.rmdir(invNodeModulesDir)
-
-  symlinkLatest()
-
-  console.debug('[CLI:quire] installing dev dependencies')
-  /**
-   * Manually install necessary dev dependencies to run 11ty;
-   * these must be `devDependencies` so that they are not bundled into
-   * the final `_site` package when running `quire build`
-   */
-  const currentWorkingDirectory = cwd()
-  const versionDir = path.join(absoluteInstallPath, version)
-  chdir(versionDir)
-  await execaCommand('npm cache clean --force')
-  await execaCommand('npm install --save-dev')
-}
-
-/**
- * Install a specific version of `quire-11ty` directly into a quire project
+ * @TODO refactor this to use the install method with pre and post-install hooks
+ * or steps to prepare the working directory and cleanup on error and completion
  *
  * @param  {String}  projectPath  Absolute system path to the project root
- * @param  {String}  version  Quire-11ty semantic version
  * @param  {Object}  options  options passed from `quire new` command
  * @return  {Promise}
  */
-async function installInProject(projectPath, version, options={}) {
-  console.debug(`[CLI:quire] installing quire-11ty@${version} into ${projectPath}`)
+async function installInProject(projectPath, quireVersion, options = {}) {
+  const { quirePath } = options
+  const quire11tyPackage = `${PACKAGE_NAME}@${quireVersion}`
+
+  console.debug(`[CLI:quire] installing ${quire11tyPackage} into ${projectPath}`)
 
   /**
-   * delete `package.json` from starter project, as it will be replaced with
-   * `package.json` from `@thegetty/quire-11ty`
+   * Delete the starter project package configuration so that it can be replaced
+   * with the `@thegetty/quire-11ty` configuration
    * @TODO If a user runs quire eject at a later date we may want to merge their
    * package.json with the `quire-11ty` dev dependencies, scripts, etc
    */
@@ -207,27 +174,24 @@ async function installInProject(projectPath, version, options={}) {
     .catch((error) => console.error('[CLI:error] ', error))
 
   const temp11tyDirectory = '.temp'
-  /**
-   * `Destination` is relative to `node_modules` of the working-directory
-   * so we have included a relative path to parent directory in order to
-   * install versions to a different local path.
-   * @see https://github.com/scott-lin/install-npm-version
-   */
-  const installOptions = {
-    Destination: path.join('..', temp11tyDirectory),
-    Debug: false,
-    Overwrite: options.force || options.overwrite || false,
-    Verbosity: options.debug ? 'Debug' : 'Silent',
-    WorkingDirectory: projectPath
-  }
-  await inv.Install(`${PACKAGE_NAME}@${version}`, installOptions)
+  const tempDir = path.join(projectPath,temp11tyDirectory)
+  fs.mkdirSync(tempDir)
+
+  // Copy if passed a path and it exists, otherwise attempt to download the tarball for this pathspec
+  if (fs.existsSync(quirePath)) {
+    fs.cpSync(quirePath, tempDir, {recursive: true})
+  } else {
+    await execaCommand(`npm pack ${ options.debug ? '--debug' : '--quiet' } --pack-destination ${tempDir} ${quire11tyPackage}`)
+
+    // Extract only the package dir from the tar bar and strip it from the extracted path
+    const tarballPath = path.join(tempDir, `thegetty-quire-11ty-${quireVersion}.tgz`)
+    await execaCommand(`tar -xzf ${tarballPath} -C ${tempDir} --strip-components=1 package/`)
 
-  // delete empty `node_modules` directory that `install-npm-version` creates
-  const invNodeModulesDir = path.join(projectPath, 'node_modules')
-  if (fs.existsSync(invNodeModulesDir)) fs.rmdir(invNodeModulesDir)
+    fs.rmSync(tarballPath)
+  }
 
-  // Copy all files installed in `.temp` to projectPath
-  fs.copySync(path.join(projectPath, '.temp'), projectPath)
+  // Copy `.temp` to projectPath
+  fs.cpSync(tempDir, projectPath, {recursive: true})
 
   console.debug('[CLI:quire] installing dev dependencies into quire project')
   /**
@@ -240,12 +204,12 @@ async function installInProject(projectPath, version, options={}) {
     await execaCommand('npm install --save-dev', { cwd: projectPath })
   } catch(error) {
     console.warn(`[CLI:error]`, error)
-    fs.removeSync(projectPath)
+    fs.rmSync(projectPath, {recursive: true})
     return
   }
 
   const eleventyFilesToCommit = fs
-    .readdirSync(path.join(projectPath, temp11tyDirectory))
+    .readdirSync(tempDir)
     .filter((filePath) => filePath !== 'node_modules')
 
   eleventyFilesToCommit.push('package-lock.json')
@@ -257,30 +221,32 @@ async function installInProject(projectPath, version, options={}) {
   await git.add(eleventyFilesToCommit).commit('Adds `@thegetty/quire-11ty` files')
 
   // remove temporary 11ty install directory
-  fs.removeSync(path.join(projectPath, temp11tyDirectory))
+  fs.rmSync(path.join(projectPath, temp11tyDirectory), {recursive: true})
 }
 
 /**
  * Retrieve latest published version of the `quire-11ty` package
-
- * @todo refactor to programmatically return a specific version
- * of `@thegetty/quire-11ty` from a semantic version string
- * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`)
- * so that the latest function may be used like:
- *  await latest('^1.0.0-pre-release.0') => '1.0.0-pre-release.2'
- *
- * Nota bene: `npm view [<@scope>/]<name>[@<version>] version`
- * @see https://docs.npmjs.com/cli/v7/commands/npm-view
- * returns a list of versions that satisfy the `<version>` range specifier,
- * piping this to execa `stdout` we get only the last line of output.
- * @todo use [`parse-columns`](https://github.com/sindresorhus/parse-columns)
- * to parse the column formated list of versions returned by `npm view`
- *
+ * or the latest compatible version with the provided semantic version string
+ * 
+ * @param {String} version A semantic version string, i.e `^1.0.0-pre-release.0`
+ * 
  * @return {String} `quire-11ty@latest` semantic version string
  */
-async function latest() {
-  const { stdout: quireVersion } =
-    await execa('npm', ['view', PACKAGE_NAME, 'version'])
+async function latest(version) {
+  let quireVersion;
+  if (!version || version === 'latest') {
+    const { stdout } = 
+      await execa('npm', ['view', PACKAGE_NAME, 'version'])
+    quireVersion = stdout
+  } else {
+    const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}`)
+    const json = await response.json()
+    const versions = Object.keys(json.versions)
+    quireVersion = semver.maxSatisfying(versions, version)
+  }
+  if (!quireVersion) {
+    throw new Error(`[CLI:quire] Sorry, we couldn't find a version of quire-11ty compatible with the version "${version}". You can set the quire-11ty version in the starter project's package.json or specify a version when running \`quire new\` with the \`--quire-version\` flag. You can run \`npm view @thegetty/quire-11ty versions\` to view all versions.`)
+  }
   return quireVersion
 }
 
@@ -314,16 +280,11 @@ async function remove(version) {
 /**
  * Sets the quire-11ty version for a project
  *
- * @param  {String}  version  Quire-11ty semantic version
+ * @param  {String}  version  a version identifier or distribution tag
  */
 function setVersion(projectPath, version) {
-  if (!version) {
-    console.error('[CLI] no version specified')
-  }
   const projectName = path.basename(projectPath)
   console.info(`${projectName} set to use quire-11ty@${version}`)
-  const versionFilePath = path.join(projectPath, VERSION_FILE)
-  fs.writeFileSync(versionFilePath, version)
 }
 
 /**
@@ -370,19 +331,6 @@ function symlinkLatest() {
   return fs.symlinkSync(target, source, type)
 }
 
-/**
- * Tests if a `quire-11ty` version is already installed
- * and installs the version if it is not already installed.
- *
- * @param  {String}  version  `quire-11ty` semantic version
- */
-function testVersion(version) {
-  version ||= getVersion()
-  if (!versions.includes(version)) {
-    install(version)
-  }
-}
-
 /**
  * Get an array of published `quire-11ty` package versions
  *
@@ -396,12 +344,10 @@ export const quire = {
   getPath,
   getVersion,
   initStarter,
-  install,
   installInProject,
   latest,
   list,
   remove,
   setVersion,
-  testVersion,
   versions,
 }

package/src/main.js

@@ -1,6 +1,9 @@
 import { Argument, Command, Option } from 'commander'
-import commands from './commands/index.js'
-import packageConfig from '../package.json' assert { type: 'json' }
+import commands from '#src/commands/index.js'
+import config from '#lib/conf/config.js'
+import packageConfig from '#src/packageConfig.js'
+
+const { version } = packageConfig
 
 /**
  * Quire CLI implements the command pattern.
@@ -12,9 +15,9 @@ 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')
+  .version(version,  '-v, --version', 'output quire version number')
   .configureHelp({
     helpWidth: 80,
     sortOptions: false,
@@ -23,9 +26,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 +39,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 +113,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/packageConfig.js

@@ -0,0 +1,15 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readPackageUpSync } from 'read-package-up'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+/**
+ * Nota bene: current working directory will be that from which cli commands
+ * are being, readPackageUpSync is passed the directory of this module as the
+ * starting path to search for the quire-cli package config file.
+ */
+const { packageJson } = readPackageUpSync({ cwd: __dirname, normalize: true })
+
+export default packageJson

package/src/validators/utils.js

@@ -0,0 +1,98 @@
+import YamlDuplicateIdError from '../errors/validation/yaml-duplicate-error.js'
+import { fileURLToPath } from 'url'
+import fs from 'node:fs'
+import path from 'path'
+import { projectRoot  } from '#lib/11ty/index.js'
+
+const IMAGE_KEYS = new Set(['src', 'image', 'logo'])
+
+export function getSchemaForDocument(file) {
+  const schemaName = path.basename(file, path.extname(file))
+  const __dirname = path.dirname(fileURLToPath(import.meta.url))
+  const schemaPath = path.join(__dirname,'..','..','schemas', `${schemaName}.schema.json`)
+
+  try {
+    return JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  } catch (error) {
+    console.warn(`Warning: No schema found for document ${schemaName} at path: ${schemaPath}.`)
+    return null
+  }
+}
+
+// Recursive helper to check image paths in nested figure list structures
+function collectImagePaths(node, paths=[]) {
+  if(!node || typeof node !== 'object') return
+
+  for (const key in node) {
+    const value = node[key]
+    if (IMAGE_KEYS.has(key) && typeof value === 'string') {
+      paths.push(value)
+    }
+    collectImagePaths(value, paths)
+  }
+
+  return paths
+}
+
+function validateImage(label, src) {
+  if(!src) return
+
+  let assetPath = ''
+  if(src.endsWith('.html')) {
+    assetPath = path.join(projectRoot, 'content', '_assets', src)
+  } else {
+    assetPath = path.join(projectRoot, 'content', '_assets', 'images', src)
+  }
+
+  if(!fs.existsSync(assetPath)) {
+    console.warn(`Warning: ${label} source not found at path: ${assetPath}`)
+  }
+}
+
+export function validateImagePaths(doc) {
+  validateImage('Cover image', doc?.epub?.defaultCoverImage)
+  validateImage('Promo image', doc?.promo_image)
+
+  for (const figure of doc?.figure_list || []) {
+    let paths = []
+    const imagePaths = collectImagePaths(figure, paths)
+    for (const imgPath of imagePaths) {
+      validateImage(`Figure id ${figure.id}`, imgPath)
+    }
+  }
+
+  for (const publisher of doc?.publisher || []) {
+    validateImage('Logo', publisher.logo)
+  }
+
+  for (const contributor of doc?.contributor || []) {
+    validateImage('Contributor', contributor.image)
+  }
+}
+
+/**
+ * Lifted from packages/11ty/_plugins/globalData
+ * Throws an error if data contains duplicate ids
+ * @param  {Object|Array} data
+ */
+export const checkForDuplicateIds = function (data, file) {
+  if (!data) return
+
+  if (Array.isArray(data)) {
+    if (data.every((item) => Object.hasOwn(item, 'id'))) {
+      const duplicates = data.filter((a, index) => {
+        return index !== data.findIndex((b) => b.id === a.id)
+      })
+      if (duplicates.length) {
+        const ids = duplicates.map(({ id }) => id)
+        throw new YamlDuplicateIdError(file, `Error in ${file}: Duplicate IDs found: ${ids.join(', ')}`)
+      }
+    }
+  }
+
+  if (typeof data === 'object') {
+    Object.keys(data).forEach((key) => {
+      checkForDuplicateIds(data[key], file)
+    })
+  }
+}

package/src/validators/validate-yaml.js

@@ -0,0 +1,38 @@
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { validateImagePaths ,getSchemaForDocument, checkForDuplicateIds } from './utils.js'
+import YamlValidationError from '../errors/validation/yaml-validation-error.js'
+import fs from 'fs'
+import yaml from 'js-yaml'
+
+export default function yamlValidation(file) {
+
+  const fileContent = fs.readFileSync(file, 'utf8')
+
+  let doc
+  try {
+    doc = yaml.load(fileContent)
+  } catch (error) {
+    const message = `Error in ${file}: ${error.reason} at line ${error.mark.line} column ${error.mark.column}`
+    throw new YamlValidationError(file, `${message}`)
+  }
+
+  const schema = getSchemaForDocument(file)
+  if(!schema){ return } 
+
+  const ajv = new Ajv({allErrors:true})
+  addFormats(ajv)
+  const validate = ajv.compile(schema)
+  const valid = validate(doc)
+  if(!valid) {
+    const messages = validate.errors
+      .map(err => `${err.instancePath || '(root)'} ${err.message}`)
+      .join('\n')
+
+    const fullMessage = `Error in ${file}:\n${messages}`
+    throw new YamlValidationError(file, fullMessage)
+  }
+
+  validateImagePaths(doc)
+  checkForDuplicateIds(doc, file)
+}

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'