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

package/src/lib/platform.js

@@ -0,0 +1,95 @@
+/**
+ * Platform detection utilities
+ *
+ * Provides OS detection and platform-specific helpers for the CLI.
+ *
+ * @module lib/platform
+ */
+import os from 'node:os'
+
+/**
+ * Platform identifiers
+ * @readonly
+ * @enum {string}
+ */
+export const Platform = {
+  MACOS: 'macos',
+  WINDOWS: 'windows',
+  LINUX: 'linux',
+  UNKNOWN: 'unknown',
+}
+
+/**
+ * Get the current platform identifier
+ * @returns {string} Platform identifier (macos, windows, linux, or unknown)
+ */
+export function getPlatform() {
+  switch (process.platform) {
+    case 'darwin':
+      return Platform.MACOS
+    case 'win32':
+      return Platform.WINDOWS
+    case 'linux':
+      return Platform.LINUX
+    default:
+      return Platform.UNKNOWN
+  }
+}
+
+/**
+ * Get a human-readable platform name
+ * @returns {string} Human-readable OS name (e.g., "macOS 14.0", "Windows 11", "Linux")
+ */
+export function getPlatformName() {
+  const platform = getPlatform()
+  const release = os.release()
+
+  switch (platform) {
+    case Platform.MACOS: {
+      // Darwin kernel version to macOS version mapping (approximate)
+      const majorVersion = parseInt(release.split('.')[0], 10)
+      // Darwin 23.x = macOS 14 (Sonoma), 22.x = macOS 13, etc.
+      const macOSVersion = majorVersion >= 20 ? majorVersion - 9 : majorVersion - 4
+      return `macOS ${macOSVersion >= 14 ? macOSVersion : release}`
+    }
+    case Platform.WINDOWS:
+      return `Windows (${release})`
+    case Platform.LINUX:
+      return `Linux (${release})`
+    default:
+      return `${process.platform} (${release})`
+  }
+}
+
+/**
+ * Check if running on macOS
+ * @returns {boolean}
+ */
+export function isMacOS() {
+  return process.platform === 'darwin'
+}
+
+/**
+ * Check if running on Windows
+ * @returns {boolean}
+ */
+export function isWindows() {
+  return process.platform === 'win32'
+}
+
+/**
+ * Check if running on Linux
+ * @returns {boolean}
+ */
+export function isLinux() {
+  return process.platform === 'linux'
+}
+
+export default {
+  Platform,
+  getPlatform,
+  getPlatformName,
+  isMacOS,
+  isWindows,
+  isLinux,
+}

package/src/lib/project/build.js

@@ -2,12 +2,15 @@
  * Build detection module
  *
  * Detects if build output exists and provides build status information.
+ * Uses shared output path resolution to ensure consistency with the
+ * doctor command and generation commands.
  *
  * @module lib/project/build
  */
 import fs from 'node:fs'
 import path from 'node:path'
 import paths from './paths.js'
+import { getPdfOutputPaths, getEpubOutputPaths, getEpubBuildDir } from './output-paths.js'
 
 /**
  * Get build output information
@@ -17,45 +20,60 @@ import paths from './paths.js'
  */
 export function getBuildInfo(projectRoot = paths.getProjectRoot()) {
   const sitePath = path.join(projectRoot, '_site')
-  const epubPath = path.join(projectRoot, '_epub')
-  const pdfFiles = ['pagedjs.pdf', 'prince.pdf']
+  const epubBuildPath = getEpubBuildDir({ projectRoot })
 
   const info = {
     site: {
       exists: fs.existsSync(sitePath),
       path: sitePath,
-      mtime: null,
+      lastModified: null,
     },
     epub: {
-      exists: fs.existsSync(epubPath),
-      path: epubPath,
-      mtime: null,
+      exists: false,
+      paths: [],
+      buildDir: epubBuildPath,
+      buildDirExists: fs.existsSync(epubBuildPath),
+      lastModified: null,
     },
     pdf: {
       exists: false,
       paths: [],
-      mtime: null,
+      lastModified: null,
     },
   }
 
-  // Get modification times if directories exist
+  // Get last modified times if directories exist
   if (info.site.exists) {
-    info.site.mtime = fs.statSync(sitePath).mtime
+    const { mtime: lastModified } = fs.statSync(sitePath)
+    info.site.lastModified = lastModified
   }
-  if (info.epub.exists) {
-    info.epub.mtime = fs.statSync(epubPath).mtime
+  if (info.epub.buildDirExists) {
+    const { mtime: lastModified } = fs.statSync(epubBuildPath)
+    info.epub.lastModified = lastModified
   }
 
-  // Check for PDF files
-  for (const file of pdfFiles) {
-    const pdfPath = path.join(projectRoot, file)
+  // Check for EPUB files using shared path resolution
+  const epubPaths = getEpubOutputPaths({ projectRoot })
+  for (const epubPath of epubPaths) {
+    if (fs.existsSync(epubPath)) {
+      info.epub.exists = true
+      info.epub.paths.push(epubPath)
+      const { mtime: lastModified } = fs.statSync(epubPath)
+      if (!info.epub.lastModified || lastModified > info.epub.lastModified) {
+        info.epub.lastModified = lastModified
+      }
+    }
+  }
+
+  // Check for PDF files using shared path resolution
+  const pdfPaths = getPdfOutputPaths({ projectRoot })
+  for (const pdfPath of pdfPaths) {
     if (fs.existsSync(pdfPath)) {
       info.pdf.exists = true
       info.pdf.paths.push(pdfPath)
-      // Use most recent mtime if multiple PDFs exist
-      const mtime = fs.statSync(pdfPath).mtime
-      if (!info.pdf.mtime || mtime > info.pdf.mtime) {
-        info.pdf.mtime = mtime
+      const { mtime: lastModified } = fs.statSync(pdfPath)
+      if (!info.pdf.lastModified || lastModified > info.pdf.lastModified) {
+        info.pdf.lastModified = lastModified
       }
     }
   }
@@ -77,20 +95,21 @@ export function hasSiteOutput(projectRoot = paths.getProjectRoot()) {
 /**
  * Check if epub build output exists
  *
+ * Checks for the intermediate _epub build directory.
+ *
  * @param {string} [projectRoot] - Project root directory (defaults to cwd)
  * @returns {boolean} True if _epub directory exists
  */
 export function hasEpubOutput(projectRoot = paths.getProjectRoot()) {
-  const epubPath = path.join(projectRoot, '_epub')
+  const epubPath = getEpubBuildDir({ projectRoot })
   return fs.existsSync(epubPath)
 }
 
 /**
  * Check if PDF output exists
  *
- * Checks for PDF output at common locations:
- * - Default library outputs: pagedjs.pdf, prince.pdf
- * - Specific library output when lib option provided
+ * Uses shared path resolution to check all possible PDF output locations,
+ * including config-aware custom paths and default engine-named paths.
  *
  * @param {Object} [options]
  * @param {string} [options.lib] - Specific library to check ('pagedjs' or 'prince')
@@ -105,9 +124,9 @@ export function hasPdfOutput(options = {}) {
     return fs.existsSync(pdfPath)
   }
 
-  // Check for any common PDF output
-  const pdfFiles = ['pagedjs.pdf', 'prince.pdf']
-  return pdfFiles.some((file) => fs.existsSync(path.join(projectRoot, file)))
+  // Check all possible PDF output locations
+  const pdfPaths = getPdfOutputPaths({ projectRoot })
+  return pdfPaths.some((pdfPath) => fs.existsSync(pdfPath))
 }
 
 /**

package/src/lib/project/build.test.js

@@ -84,6 +84,7 @@ test('getBuildInfo returns correct status for existing builds', async (t) => {
   vol.fromJSON({
     [memfsPath('_site', 'index.html')]: '<html></html>',
     [memfsPath('_epub', 'content.opf')]: '<package></package>',
+    [memfsPath('epubjs.epub')]: 'PK\x03\x04',
     [memfsPath('pagedjs.pdf')]: '%PDF-1.4',
   })
 
@@ -95,15 +96,17 @@ test('getBuildInfo returns correct status for existing builds', async (t) => {
 
   t.true(info.site.exists)
   t.is(info.site.path, nativePath('_site'))
-  t.truthy(info.site.mtime)
+  t.truthy(info.site.lastModified)
 
   t.true(info.epub.exists)
-  t.is(info.epub.path, nativePath('_epub'))
-  t.truthy(info.epub.mtime)
+  t.true(info.epub.buildDirExists)
+  t.is(info.epub.buildDir, nativePath('_epub'))
+  t.true(info.epub.paths.includes(nativePath('epubjs.epub')))
+  t.truthy(info.epub.lastModified)
 
   t.true(info.pdf.exists)
   t.deepEqual(info.pdf.paths, [nativePath('pagedjs.pdf')])
-  t.truthy(info.pdf.mtime)
+  t.truthy(info.pdf.lastModified)
 })
 
 test('getBuildInfo returns correct status for missing builds', async (t) => {
@@ -120,14 +123,15 @@ test('getBuildInfo returns correct status for missing builds', async (t) => {
   const info = getBuildInfo(testRoot)
 
   t.false(info.site.exists)
-  t.is(info.site.mtime, null)
+  t.is(info.site.lastModified, null)
 
   t.false(info.epub.exists)
-  t.is(info.epub.mtime, null)
+  t.false(info.epub.buildDirExists)
+  t.is(info.epub.lastModified, null)
 
   t.false(info.pdf.exists)
   t.deepEqual(info.pdf.paths, [])
-  t.is(info.pdf.mtime, null)
+  t.is(info.pdf.lastModified, null)
 })
 
 test('getBuildInfo returns multiple PDF paths when both exist', async (t) => {
@@ -148,7 +152,25 @@ test('getBuildInfo returns multiple PDF paths when both exist', async (t) => {
   t.is(info.pdf.paths.length, 2)
   t.true(info.pdf.paths.includes(nativePath('pagedjs.pdf')))
   t.true(info.pdf.paths.includes(nativePath('prince.pdf')))
-  t.truthy(info.pdf.mtime)
+  t.truthy(info.pdf.lastModified)
+})
+
+test('getBuildInfo detects epub build dir without .epub files', async (t) => {
+  const { vol } = t.context
+
+  vol.fromJSON({
+    [memfsPath('_epub', 'content.opf')]: '<package></package>',
+  })
+
+  const { getBuildInfo } = await esmock('./build.js', {
+    'node:fs': createFsFromVolume(vol),
+  })
+
+  const info = getBuildInfo(testRoot)
+
+  t.false(info.epub.exists, 'no .epub files should mean exists is false')
+  t.true(info.epub.buildDirExists, '_epub directory should be detected')
+  t.truthy(info.epub.lastModified, 'lastModified from _epub dir should be present')
 })
 
 test('requireBuildOutput throws when site output missing', async (t) => {

package/src/lib/project/detect.js

@@ -7,7 +7,21 @@
  */
 import fs from 'node:fs'
 
-const QUIRE_DOT_FILES = Object.freeze([
+/**
+ * Files that indicate a Quire project directory.
+ *
+ * These marker files are created by `quire new` or exist in Quire project templates.
+ * The presence of any one of these files indicates the directory is a Quire project root.
+ *
+ * @constant {ReadonlyArray<string>}
+ *
+ * @example
+ * // Check if a file is a project marker
+ * if (PROJECT_MARKERS.includes(filename)) {
+ *   console.log('This is a Quire project root')
+ * }
+ */
+export const PROJECT_MARKERS = Object.freeze([
   '.eleventy.js',
   '.quire',
   '.quire-11ty',
@@ -29,5 +43,5 @@ const QUIRE_DOT_FILES = Object.freeze([
  */
 export default function (dirpath) {
   return fs.readdirSync(dirpath)
-    .find((entry) => QUIRE_DOT_FILES.includes(entry))
+    .find((entry) => PROJECT_MARKERS.includes(entry))
 }

package/src/lib/project/index.js

@@ -4,8 +4,8 @@
  * Provides project-level concerns including paths, detection, configuration,
  * build status, and version management.
  */
-import paths, { Paths } from './paths.js'
-import detect from './detect.js'
+import paths, { DATA_DIR, Paths, REQUIRED_DATA_FILES, SOURCE_DIRECTORIES } from './paths.js'
+import detect, { PROJECT_MARKERS } from './detect.js'
 import { loadProjectConfig } from './config.js'
 import {
   getBuildInfo,
@@ -14,6 +14,13 @@ import {
   hasSiteOutput,
   requireBuildOutput,
 } from './build.js'
+import {
+  getPdfOutputPaths,
+  getEpubOutputPaths,
+  getEpubBuildDir,
+  PDF_ENGINES,
+  EPUB_ENGINES,
+} from './output-paths.js'
 import {
   getVersion,
   setVersion,
@@ -23,8 +30,17 @@ import {
 } from './version.js'
 
 export {
+  DATA_DIR,
+  EPUB_ENGINES,
+  PDF_ENGINES,
+  PROJECT_MARKERS,
+  REQUIRED_DATA_FILES,
+  SOURCE_DIRECTORIES,
   detect,
   getBuildInfo,
+  getEpubBuildDir,
+  getEpubOutputPaths,
+  getPdfOutputPaths,
   hasEpubOutput,
   hasPdfOutput,
   hasSiteOutput,

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'
@@ -93,6 +94,14 @@ program.hook('preAction', (thisCommand) => {
   }
 })
 
+/**
+ * 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()
+})
+
 /**
  * Register each command as a subcommand of this program
  * @see https://github.com/tj/commander.js?tab=readme-ov-file#automated-help
@@ -190,12 +199,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