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

package/src/lib/logger/debug.js

@@ -1,3 +1,4 @@
+import util from 'node:util'
 import debug from 'debug'
 
 /**
@@ -6,6 +7,10 @@ import debug from 'debug'
  * Creates debug instances with the `quire:` namespace prefix.
  * Uses the standard `debug` package for namespace-based filtering.
  *
+ * Object formatting:
+ *   %O  Pretty-printed, indented on a new line (multi-line)
+ *   %o  Compact single-line output (built-in default)
+ *
  * @example
  * // In a module (short alias)
  * import createDebug from '#debug'
@@ -22,6 +27,42 @@ import debug from 'debug'
  * @see https://www.npmjs.com/package/debug
  */
 
+/**
+ * Override %O formatter to produce indented multi-line output
+ *
+ * Pretty-prints objects with each line indented by 2 spaces,
+ * starting on a new line after the label.
+ *
+ * Use %o (lowercase) for compact single-line output.
+ */
+debug.formatters.O = function (value) {
+  this.inspectOpts.colors = this.useColors
+  const string = util.inspect(value, this.inspectOpts)
+  return '\n' + string.split('\n').map((line) => '  ' + line).join('\n')
+}
+
+/**
+ * Override formatArgs to prevent per-line namespace prefixing
+ *
+ * The default debug formatArgs (in color mode) splits the formatted
+ * message on newlines and inserts the namespace prefix before every
+ * line. This makes multi-line %O output noisy. This override only
+ * prefixes the first line, letting continuation lines flow cleanly.
+ */
+const originalFormatArgs = debug.formatArgs
+debug.formatArgs = function (args) {
+  if (this.useColors) {
+    const c = this.color
+    const colorCode = '\u001B[3' + (c < 8 ? c : '8;5;' + c)
+    const prefix = `  ${colorCode};1m${this.namespace} \u001B[0m`
+
+    args[0] = prefix + args[0]
+    args.push(colorCode + 'm+' + debug.humanize(this.diff) + '\u001B[0m')
+  } else {
+    originalFormatArgs.call(this, args)
+  }
+}
+
 /**
  * Root namespace for all Quire CLI debug output
  */
@@ -37,7 +78,8 @@ export const DEBUG_NAMESPACE = 'quire'
  * const debug = createDebug('lib:pdf:paged')
  * debug('printer options: %O', options)
  * // Output (when DEBUG=quire:lib:pdf:paged):
- * // quire:lib:pdf:paged printer options: { ... } +0ms
+ * // quire:lib:pdf:paged printer options:
+ * //   { format: 'A4', landscape: false } +0ms
  */
 export default function createDebug(namespace) {
   return debug(`${DEBUG_NAMESPACE}:${namespace}`)

package/src/lib/logger/debug.test.js

@@ -0,0 +1,128 @@
+import test from 'ava'
+import debug from 'debug'
+// Import to register formatter and formatArgs overrides
+import './debug.js'
+
+/**
+ * Debug formatter and output tests
+ *
+ * Verifies the custom %O formatter produces indented multi-line output,
+ * the %o formatter remains compact single-line, and the formatArgs
+ * override prevents per-line namespace prefixing in colored output.
+ */
+
+/**
+ * Helper to call a debug formatter with a value
+ *
+ * Formatters are called with `this` bound to a debugger-like context.
+ * We provide the minimal context the formatters expect.
+ */
+function callFormatter(specifier, value) {
+  const formatter = debug.formatters[specifier]
+  const context = {
+    useColors: false,
+    inspectOpts: { colors: false },
+  }
+  return formatter.call(context, value)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// %O formatter (pretty-printed, indented)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('%O output starts with a newline', (t) => {
+  const result = callFormatter('O', { a: 1 })
+  t.true(result.startsWith('\n'))
+})
+
+test('%O output lines are indented with 2 spaces', (t) => {
+  const result = callFormatter('O', { a: 1, b: 2 })
+  const lines = result.split('\n').slice(1) // skip leading empty line
+  for (const line of lines) {
+    t.true(line.startsWith('  '), `Line not indented: "${line}"`)
+  }
+})
+
+test('%O formats nested objects with indentation', (t) => {
+  const result = callFormatter('O', { outer: { inner: 'value' } })
+  t.true(result.includes('outer'))
+  t.true(result.includes('inner'))
+  // Every line after the leading newline should be indented
+  const lines = result.split('\n').slice(1)
+  for (const line of lines) {
+    t.true(line.startsWith('  '), `Line not indented: "${line}"`)
+  }
+})
+
+test('%O handles null without error', (t) => {
+  const result = callFormatter('O', null)
+  t.true(result.includes('null'))
+})
+
+test('%O handles undefined without error', (t) => {
+  const result = callFormatter('O', undefined)
+  t.true(result.includes('undefined'))
+})
+
+test('%O handles primitive values', (t) => {
+  t.true(callFormatter('O', 42).includes('42'))
+  t.true(callFormatter('O', 'hello').includes('hello'))
+  t.true(callFormatter('O', true).includes('true'))
+})
+
+test('%O handles arrays', (t) => {
+  const result = callFormatter('O', [1, 2, 3])
+  t.true(result.includes('1'))
+  t.true(result.includes('2'))
+  t.true(result.includes('3'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// %o formatter (compact single-line, built-in)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('%o output is single-line', (t) => {
+  const result = callFormatter('o', { a: 1, b: 2, c: 3 })
+  t.false(result.includes('\n'))
+})
+
+test('%o does not start with a newline', (t) => {
+  const result = callFormatter('o', { a: 1 })
+  t.false(result.startsWith('\n'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// formatArgs override (prefix only on first line)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Helper to call formatArgs and capture the result
+ *
+ * Creates a minimal debugger-like context to test formatArgs behavior.
+ * In color mode, the default debug formatArgs would split on newlines
+ * and insert the prefix before every line. Our override prevents this.
+ */
+function callFormatArgs(message, useColors = true) {
+  const args = [message]
+  const context = {
+    namespace: 'test',
+    useColors,
+    color: 5,
+    diff: 0,
+  }
+  debug.formatArgs.call(context, args)
+  return args[0]
+}
+
+test('formatArgs prefixes the first line in color mode', (t) => {
+  const result = callFormatArgs('hello')
+  t.true(result.includes('test'))
+  t.true(result.includes('hello'))
+})
+
+test('formatArgs does not duplicate prefix on multi-line output', (t) => {
+  const result = callFormatArgs('paths:\n  { a: 1 }\n  { b: 2 }')
+  // Namespace should appear exactly once
+  const matches = result.match(/test/g)
+  t.is(matches.length, 1)
+})

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')
+}