@thegetty/quire-cli 1.0.0-rc.37 → 1.0.0-rc.39

package/src/lib/project/output-paths.js

@@ -0,0 +1,87 @@
+/**
+ * Output path resolution module
+ *
+ * Centralizes knowledge of where PDF and EPUB output files are located.
+ * Used by the doctor command and build detection to find output artifacts
+ * using the same logic as the generation commands.
+ *
+ * @module lib/project/output-paths
+ */
+import path from 'node:path'
+import { ENGINES as PDF_ENGINES } from '#lib/pdf/schema.js'
+import { ENGINES as EPUB_ENGINES } from '#lib/epub/schema.js'
+
+export { PDF_ENGINES, EPUB_ENGINES }
+
+/**
+ * Get all possible PDF output file paths for a project
+ *
+ * PDF output paths depend on configuration:
+ * - With config.pdf: `{outputDir}/{config.pdf.outputDir}/{config.pdf.filename}.pdf`
+ * - Without config (default): `{projectRoot}/{engine}.pdf`
+ *
+ * This reuses the same resolution logic as `lib/pdf/index.js#getOutputPath`.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot=process.cwd()] - Project root directory
+ * @param {string} [options.outputDir='_site'] - Build output directory (relative)
+ * @param {Object} [options.pdfConfig] - PDF config from config.yaml (config.pdf)
+ * @param {string} [options.pdfConfig.outputDir] - PDF output subdirectory
+ * @param {string} [options.pdfConfig.filename] - PDF filename (without extension)
+ * @returns {string[]} Array of absolute paths to check for PDF output
+ */
+export function getPdfOutputPaths(options = {}) {
+  const {
+    projectRoot = process.cwd(),
+    outputDir = '_site',
+    pdfConfig,
+  } = options
+
+  const paths = []
+
+  if (pdfConfig && pdfConfig.outputDir && pdfConfig.filename) {
+    // Config-aware path: matches lib/pdf/index.js getOutputPath()
+    paths.push(
+      path.join(projectRoot, outputDir, pdfConfig.outputDir, `${pdfConfig.filename}.pdf`)
+    )
+  }
+
+  // Default engine-named paths (always check these as fallback)
+  for (const engine of PDF_ENGINES) {
+    paths.push(path.join(projectRoot, `${engine}.pdf`))
+  }
+
+  return paths
+}
+
+/**
+ * Get all possible EPUB output file paths for a project
+ *
+ * EPUB output is at `{projectRoot}/{engine}.epub` for each supported engine.
+ * The `_epub` directory is an intermediate build artifact, not the final output.
+ *
+ * This reuses the same resolution logic as `commands/epub.js`.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot=process.cwd()] - Project root directory
+ * @returns {string[]} Array of absolute paths to check for EPUB output
+ */
+export function getEpubOutputPaths(options = {}) {
+  const { projectRoot = process.cwd() } = options
+
+  return EPUB_ENGINES.map(
+    (engine) => path.join(projectRoot, `${engine}.epub`)
+  )
+}
+
+/**
+ * Get the intermediate EPUB build directory path
+ *
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot=process.cwd()] - Project root directory
+ * @returns {string} Absolute path to _epub directory
+ */
+export function getEpubBuildDir(options = {}) {
+  const { projectRoot = process.cwd() } = options
+  return path.join(projectRoot, '_epub')
+}

package/src/lib/project/output-paths.test.js

@@ -0,0 +1,66 @@
+import test from 'ava'
+import path from 'node:path'
+import { getPdfOutputPaths, getEpubOutputPaths, getEpubBuildDir } from './output-paths.js'
+
+const projectRoot = '/test-project'
+
+test('getPdfOutputPaths returns default engine paths', (t) => {
+  const paths = getPdfOutputPaths({ projectRoot })
+
+  t.true(paths.includes(path.join(projectRoot, 'pagedjs.pdf')))
+  t.true(paths.includes(path.join(projectRoot, 'prince.pdf')))
+})
+
+test('getPdfOutputPaths includes config-aware path when pdfConfig provided', (t) => {
+  const pdfConfig = { outputDir: 'pdf', filename: 'my-publication' }
+  const paths = getPdfOutputPaths({ projectRoot, outputDir: '_site', pdfConfig })
+
+  // Config path should be first
+  t.is(paths[0], path.join(projectRoot, '_site', 'pdf', 'my-publication.pdf'))
+  // Default paths should still be present
+  t.true(paths.includes(path.join(projectRoot, 'pagedjs.pdf')))
+  t.true(paths.includes(path.join(projectRoot, 'prince.pdf')))
+})
+
+test('getPdfOutputPaths skips config path when pdfConfig is incomplete', (t) => {
+  // Missing filename
+  const paths = getPdfOutputPaths({ projectRoot, pdfConfig: { outputDir: 'pdf' } })
+
+  // Should only have default engine paths
+  t.is(paths.length, 2)
+  t.true(paths.includes(path.join(projectRoot, 'pagedjs.pdf')))
+  t.true(paths.includes(path.join(projectRoot, 'prince.pdf')))
+})
+
+test('getPdfOutputPaths uses cwd when no projectRoot provided', (t) => {
+  const paths = getPdfOutputPaths()
+
+  t.true(paths.includes(path.join(process.cwd(), 'pagedjs.pdf')))
+  t.true(paths.includes(path.join(process.cwd(), 'prince.pdf')))
+})
+
+test('getEpubOutputPaths returns default engine paths', (t) => {
+  const paths = getEpubOutputPaths({ projectRoot })
+
+  t.true(paths.includes(path.join(projectRoot, 'epubjs.epub')))
+  t.true(paths.includes(path.join(projectRoot, 'pandoc.epub')))
+})
+
+test('getEpubOutputPaths uses cwd when no projectRoot provided', (t) => {
+  const paths = getEpubOutputPaths()
+
+  t.true(paths.includes(path.join(process.cwd(), 'epubjs.epub')))
+  t.true(paths.includes(path.join(process.cwd(), 'pandoc.epub')))
+})
+
+test('getEpubBuildDir returns _epub path', (t) => {
+  const dir = getEpubBuildDir({ projectRoot })
+
+  t.is(dir, path.join(projectRoot, '_epub'))
+})
+
+test('getEpubBuildDir uses cwd when no projectRoot provided', (t) => {
+  const dir = getEpubBuildDir()
+
+  t.is(dir, path.join(process.cwd(), '_epub'))
+})

package/src/lib/project/paths.js

@@ -5,6 +5,54 @@ import path from 'node:path'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+/**
+ * Source directories that contain content for building.
+ *
+ * These directories are monitored for changes during preview and are used
+ * to determine if a build is stale. Changes to files in these directories
+ * indicate the site needs to be rebuilt.
+ *
+ * @constant {ReadonlyArray<string>}
+ *
+ * @example
+ * // Check all source directories for changes
+ * for (const dir of SOURCE_DIRECTORIES) {
+ *   const mtime = getLatestMtime(dir)
+ *   // ...
+ * }
+ */
+export const SOURCE_DIRECTORIES = Object.freeze([
+  '_data',
+  '_includes',
+  '_layouts',
+  'content',
+  'static',
+])
+
+/**
+ * Path to data files directory (relative to project root)
+ *
+ * Contains YAML configuration files for the publication:
+ * - publication.yaml - Publication metadata
+ * - config.yaml - Site configuration
+ * - figures.yaml - Figure definitions
+ * - objects.yaml - Object catalog entries
+ * - references.yaml - Bibliography entries
+ *
+ * @constant {string}
+ */
+export const DATA_DIR = 'content/_data'
+
+/**
+ * Required data files that must exist in a Quire project.
+ *
+ * These files are validated by the doctor command and the validate command.
+ * Missing required files will trigger a warning.
+ *
+ * @constant {ReadonlyArray<string>}
+ */
+export const REQUIRED_DATA_FILES = Object.freeze(['publication.yaml'])
+
 /**
  * Project path configuration
  *

package/src/main.js

@@ -9,6 +9,7 @@ import {
 import commands from '#src/commands/index.js'
 import config from '#lib/conf/config.js'
 import { handleError } from '#lib/error/handler.js'
+import reporter from '#lib/reporter/index.js'
 import { docsUrl, DOCS_BASE } from '#helpers/docs-url.js'
 import packageConfig from '#src/packageConfig.js'
 import { enableDebug } from '#lib/logger/debug.js'
@@ -33,7 +34,14 @@ Output Modes:
 
   Set defaults: quire settings set verbose true
 
+Paging:
+  --no-pager             Disable paging for long output
+  NO_PAGER=1             Disable paging via environment variable
+  PAGER=cat              Traditional Unix alternative (passes output through)
+
 Environment Variables:
+  NO_PAGER=1             Disable paging for long output
+  PAGER=<program>        Set pager program (default: less). Use PAGER=cat to disable
   DEBUG=quire:*          Enable debug output for all modules
   DEBUG=quire:lib:pdf    Enable debug output for PDF module only
   DEBUG=quire:lib:*      Enable debug output for all lib modules
@@ -48,7 +56,7 @@ Examples:
 /**
  * Quire CLI implements the command pattern.
  *
- * The `main` module acts as the _receiver_, parsing input from the client,
+ * The \`main\` module acts as the _receiver_, parsing input from the client,
  * calling the appropriate command module(s), managing messages between modules,
  * and sending formatted messages to the client for display.
  */
@@ -61,6 +69,7 @@ program
   .addOption(arrayToOption(quietOption))
   .addOption(arrayToOption(verboseOption))
   .addOption(arrayToOption(debugOption))
+  .option('--no-pager', 'disable paging for long output')
   .addHelpText('after', mainHelpText)
   .configureHelp({
     helpWidth: 80,
@@ -91,6 +100,19 @@ program.hook('preAction', (thisCommand) => {
   if (opts.debug ?? config.get('debug')) {
     enableDebug('quire:*')
   }
+
+  // --no-pager sets pager to false; propagate via env var for pager utility
+  if (opts.pager === false) {
+    process.env.NO_PAGER = '1'
+  }
+})
+
+/**
+ * Stop the reporter after every command to clear any active setInterval timers
+ * (e.g. elapsed time display) that would otherwise keep the event loop alive.
+ */
+program.hook('postAction', () => {
+  reporter.stop()
 })
 
 /**
@@ -190,12 +212,25 @@ commands.forEach((command) => {
     })
   }
 
-  // Wrap action in centralized error handler
-  // Using apply() preserves `this` context for `this.debug` and `this.logger`
+  /**
+   * Wrap action in centralized error handler.
+   * Using apply() preserves `this` context for `this.debug` and `this.logger`.
+   *
+   * Nota bene: Commander passes subcommand-local opts as the options argument,
+   * but global options (--verbose, --quiet, --debug) defined on the parent
+   * program are only available via optsWithGlobals(). We replace the options
+   * argument with the merged set so action handlers see all options uniformly.
+   */
   subCommand.action(async (...args) => {
     try {
+      // Commander Command instance is the last element in args array
+      // @see https://github.com/tj/commander.js#action-handler
+      const cmd = args[args.length - 1]
+      const mergedOpts = cmd.optsWithGlobals()
+      args[args.length - 2] = mergedOpts
       await action.apply(command, args)
     } catch (error) {
+      reporter.stop()
       const { debug } = program.opts()
       handleError(error, { debug })
     }

package/src/packageConfig.js

@@ -1,6 +1,7 @@
 import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readPackageUpSync } from 'read-package-up'
+import which from '#helpers/which.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -12,4 +13,20 @@ const __dirname = dirname(__filename)
  */
 const { packageJson } = readPackageUpSync({ cwd: __dirname, normalize: true })
 
+/**
+ * Resolve the full filesystem path to the quire CLI executable
+ *
+ * Uses the `which` helper to find the first `quire` executable in PATH.
+ * Returns null if the executable is not found.
+ *
+ * @returns {string|null} Absolute path to the quire executable, or null
+ */
+export function binPath() {
+  try {
+    return which('quire')
+  } catch {
+    return null
+  }
+}
+
 export default packageJson

package/src/validators/validate-data-files.js

@@ -0,0 +1,154 @@
+/**
+ * Data files validation for Quire projects
+ *
+ * Validates YAML files in content/_data/ directory:
+ * - Required files exist (publication.yaml)
+ * - YAML syntax is correct
+ * - Files conform to their JSON schemas (when schema exists)
+ * - No duplicate IDs in arrays
+ *
+ * @module validators/validate-data-files
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import yaml from 'js-yaml'
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { DATA_DIR, REQUIRED_DATA_FILES } from '#lib/project/index.js'
+import { getSchemaForDocument, checkForDuplicateIds } from './utils.js'
+
+/**
+ * Validation result for a single file
+ * @typedef {Object} FileValidationResult
+ * @property {string} file - Filename
+ * @property {boolean} valid - Whether the file is valid
+ * @property {string[]} errors - List of error messages
+ */
+
+/**
+ * Validation result for all data files
+ * @typedef {Object} DataFilesValidationResult
+ * @property {boolean} valid - Whether all files are valid
+ * @property {string[]} errors - All error messages across all files
+ * @property {number} fileCount - Number of YAML files found
+ * @property {FileValidationResult[]} files - Per-file validation results
+ */
+
+/**
+ * Validate a single YAML file
+ *
+ * @param {string} filePath - Absolute path to the YAML file
+ * @returns {FileValidationResult} Validation result
+ */
+export function validateYamlFile(filePath) {
+  const errors = []
+  const filename = path.basename(filePath)
+
+  // Check file exists
+  if (!fs.existsSync(filePath)) {
+    return { file: filename, valid: false, errors: [`File not found: ${filename}`] }
+  }
+
+  // Read and parse YAML
+  let doc
+  try {
+    const content = fs.readFileSync(filePath, 'utf8')
+    doc = yaml.load(content)
+  } catch (error) {
+    const loc = error.mark ? ` at line ${error.mark.line + 1}` : ''
+    errors.push(`${filename}: YAML syntax error${loc} - ${error.reason || error.message}`)
+    return { file: filename, valid: false, errors }
+  }
+
+  // Validate against schema if one exists
+  const schema = getSchemaForDocument(filePath)
+  if (schema) {
+    const ajv = new Ajv({ allErrors: true })
+    addFormats(ajv)
+    const validate = ajv.compile(schema)
+    const valid = validate(doc)
+
+    if (!valid) {
+      for (const err of validate.errors) {
+        const errPath = err.instancePath || '(root)'
+        errors.push(`${filename}: ${errPath} ${err.message}`)
+      }
+    }
+  }
+
+  // Check for duplicate IDs using the existing utility
+  // Note: checkForDuplicateIds throws, so we need to catch
+  try {
+    checkForDuplicateIds(doc, filePath)
+  } catch (error) {
+    // Extract the duplicate ID info from the error
+    const match = error.reason?.match(/Duplicate IDs found: (.+)/)
+    if (match) {
+      errors.push(`${filename}: duplicate IDs found: ${match[1]}`)
+    } else {
+      errors.push(`${filename}: ${error.reason || error.message}`)
+    }
+  }
+
+  return { file: filename, valid: errors.length === 0, errors }
+}
+
+/**
+ * Validate all data files in content/_data/
+ *
+ * @returns {DataFilesValidationResult} Validation result
+ */
+export function validateDataFiles() {
+  const allErrors = []
+  const fileResults = []
+
+  // Check if data directory exists
+  if (!fs.existsSync(DATA_DIR)) {
+    return {
+      valid: true,
+      errors: [],
+      fileCount: 0,
+      files: [],
+      notInProject: true,
+    }
+  }
+
+  // Check required files exist
+  for (const required of REQUIRED_DATA_FILES) {
+    const filePath = path.join(DATA_DIR, required)
+    if (!fs.existsSync(filePath)) {
+      allErrors.push(`Required file missing: ${required}`)
+    }
+  }
+
+  // Find all YAML files
+  let yamlFiles = []
+  try {
+    yamlFiles = fs.readdirSync(DATA_DIR)
+      .filter((file) => file.endsWith('.yaml') || file.endsWith('.yml'))
+      .map((file) => path.join(DATA_DIR, file))
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`Cannot read ${DATA_DIR}: ${error.message}`],
+      fileCount: 0,
+      files: [],
+    }
+  }
+
+  // Validate each file
+  for (const filePath of yamlFiles) {
+    const result = validateYamlFile(filePath)
+    fileResults.push(result)
+    allErrors.push(...result.errors)
+  }
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    fileCount: yamlFiles.length,
+    files: fileResults,
+  }
+}
+
+export default validateDataFiles

package/src/validators/validate-data-files.test.js

@@ -0,0 +1,217 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('validateDataFiles returns notInProject when data dir does not exist', async (t) => {
+  const { sandbox } = t.context
+
+  const { validateDataFiles } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(false),
+      },
+    },
+  })
+
+  const result = validateDataFiles()
+
+  t.true(result.valid)
+  t.true(result.notInProject)
+  t.is(result.fileCount, 0)
+  t.deepEqual(result.errors, [])
+})
+
+test('validateDataFiles returns error when required file is missing', async (t) => {
+  const { sandbox } = t.context
+
+  const existsStub = sandbox.stub()
+  existsStub.withArgs('content/_data').returns(true)
+  existsStub.withArgs('content/_data/publication.yaml').returns(false)
+  existsStub.returns(false)
+
+  const path = await import('node:path')
+  const { validateDataFiles } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: existsStub,
+        readdirSync: sandbox.stub().returns([]),
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+  })
+
+  const result = validateDataFiles()
+
+  t.false(result.valid)
+  t.true(result.errors.includes('Required file missing: publication.yaml'))
+})
+
+test('validateDataFiles validates all YAML files in directory', async (t) => {
+  const { sandbox } = t.context
+
+  const existsStub = sandbox.stub()
+  existsStub.withArgs('content/_data').returns(true)
+  existsStub.withArgs('content/_data/publication.yaml').returns(true)
+  existsStub.returns(true)
+
+  const readFileStub = sandbox.stub()
+  readFileStub.callsFake((filePath) => {
+    if (filePath.includes('publication.yaml')) {
+      return 'title: Test Publication'
+    }
+    if (filePath.includes('config.yaml')) {
+      return 'setting: value'
+    }
+    throw new Error('ENOENT')
+  })
+
+  const path = await import('node:path')
+  const { validateDataFiles } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: existsStub,
+        readdirSync: sandbox.stub().returns(['publication.yaml', 'config.yaml']),
+        readFileSync: readFileStub,
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+    './utils.js': {
+      getSchemaForDocument: sandbox.stub().returns(null),
+      checkForDuplicateIds: sandbox.stub(),
+    },
+  })
+
+  const result = validateDataFiles()
+
+  t.true(result.valid)
+  t.is(result.fileCount, 2)
+  t.is(result.files.length, 2)
+})
+
+test('validateYamlFile returns error for invalid YAML syntax', async (t) => {
+  const { sandbox } = t.context
+
+  const path = await import('node:path')
+  const { validateYamlFile } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns('title: [invalid yaml'),
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+    './utils.js': {
+      getSchemaForDocument: sandbox.stub().returns(null),
+      checkForDuplicateIds: sandbox.stub(),
+    },
+  })
+
+  const result = validateYamlFile('content/_data/test.yaml')
+
+  t.false(result.valid)
+  t.true(result.errors.some((e) => e.includes('YAML syntax error')))
+})
+
+test('validateYamlFile returns error when file not found', async (t) => {
+  const { sandbox } = t.context
+
+  const path = await import('node:path')
+  const { validateYamlFile } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(false),
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+  })
+
+  const result = validateYamlFile('content/_data/missing.yaml')
+
+  t.false(result.valid)
+  t.true(result.errors.some((e) => e.includes('File not found')))
+})
+
+test('validateYamlFile validates against schema when available', async (t) => {
+  const { sandbox } = t.context
+
+  const schema = {
+    type: 'object',
+    required: ['title'],
+    properties: {
+      title: { type: 'string' },
+    },
+  }
+
+  const path = await import('node:path')
+  const { validateYamlFile } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns('notitle: value'),
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+    './utils.js': {
+      getSchemaForDocument: sandbox.stub().returns(schema),
+      checkForDuplicateIds: sandbox.stub(),
+    },
+  })
+
+  const result = validateYamlFile('content/_data/test.yaml')
+
+  t.false(result.valid)
+  t.true(result.errors.some((e) => e.includes('title')))
+})
+
+test('validateYamlFile catches duplicate ID errors', async (t) => {
+  const { sandbox } = t.context
+
+  const path = await import('node:path')
+  const { validateYamlFile } = await esmock('./validate-data-files.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns('title: Test'),
+      },
+    },
+    'node:path': {
+      default: path.default,
+    },
+    './utils.js': {
+      getSchemaForDocument: sandbox.stub().returns(null),
+      checkForDuplicateIds: sandbox.stub().throws({
+        reason: 'Duplicate IDs found: fig-1, fig-2',
+      }),
+    },
+  })
+
+  const result = validateYamlFile('content/_data/figures.yaml')
+
+  t.false(result.valid)
+  t.true(result.errors.some((e) => e.includes('duplicate IDs')))
+})
+
+test('default export is validateDataFiles', async (t) => {
+  const module = await import('./validate-data-files.js')
+
+  t.is(typeof module.default, 'function')
+  t.is(module.default, module.validateDataFiles)
+})