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

package/src/lib/pdf/prince.js

@@ -5,33 +5,53 @@ import { fileURLToPath } from 'node:url'
 import { splitPdf } from './split.js'
 import fs from 'fs-extra'
 
-import which from '#helpers/which.js'
+import processManager from '#lib/process/manager.js'
+import reporter from '#lib/reporter/index.js'
+import { PdfGenerationError } from '#src/errors/index.js'
+import createDebug from '#debug'
+import ENGINES from './engines.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+const debug = createDebug('lib:pdf:prince')
+
+/** Re-export engine metadata from central registry */
+export const metadata = ENGINES.prince
+
 /**
  * A façade module for interacting with the Prince CLI.
  * @see https://www.princexml.com/doc/command-line/
+ *
+ * Prince availability is checked by the parent façade (lib/pdf/index.js)
+ * before this module is loaded, so we can assume prince is in PATH.
+ *
+ * @param {string} publicationInput - Path to the publication HTML file
+ * @param {string} coversInput - Path to the covers HTML file
+ * @param {string} pdfPath - Path where the PDF should be written
+ * @param {Object} [options={}] - Generation options
+ * @returns {Promise<string>} Path to the generated PDF file
  */
-export default async (publicationInput, coversInput, output, options = {}) => {
-  which('prince')
+export default async (publicationInput, coversInput, pdfPath, options = {}) => {
+  debug('input: %s', publicationInput)
+  debug('covers: %s', coversInput)
+  debug('output: %s', pdfPath)
 
   /**
    * @see https://www.princexml.com/doc/command-line/#options
    */
-  
+
   const { pdfConfig } = options
 
   // These options run once to get the map pages to essays
   const pageMapOptions = [
     `--script=${ path.join(__dirname, 'princePlugin.js') }`,
-    `--output=${output}`,
+    `--output=${pdfPath}`,
   ]
 
   // These options are for the actual user-facing PDF
   const cmdOptions = [
-    `--output=${output}`,
+    `--output=${pdfPath}`,
     `--pdf-profile=PDF/UA-1`,
   ]
 
@@ -39,60 +59,118 @@ export default async (publicationInput, coversInput, output, options = {}) => {
     pageMapOptions.push('--debug')
     cmdOptions.push('--debug')
   }
-  
+
   if (options.verbose) {
     pageMapOptions.push('--verbose')
     cmdOptions.push('--verbose')
   }
 
-  const { dir } = path.parse(output)
-  if (!fs.existsSync(dir)) { 
-    fs.mkdirsSync(dir)
+  debug('page map options: %O', pageMapOptions)
+  debug('cmd options: %O', cmdOptions)
+
+  try {
+    const { dir } = path.parse(pdfPath)
+    if (!fs.existsSync(dir)) {
+      fs.mkdirsSync(dir)
+    }
+  } catch (error) {
+    throw new PdfGenerationError('Prince', 'output directory creation', error.message)
   }
-  
-  // Execute the page mapping PDF build  
+
+  // Execute page map extraction (renders PDF with script to extract page info, then discards it)
+  debug('analyzing document structure')
+  reporter.update('Analyzing document structure...')
   let pageMap = {}
   try {
-    const pageMapOutput = await execa('prince', [...pageMapOptions, publicationInput])  
+    const pageMapOutput = await execa('prince', [...pageMapOptions, publicationInput], {
+      cancelSignal: processManager.signal,
+      gracefulCancel: true
+    })
     pageMap = JSON.parse(pageMapOutput.stdout)
-  } catch (err) {
-    console.error(`Generating the PDF page map failed with the error ${err.stderr}`)
-    process.exit(1)
+  } catch (error) {
+    if (error.isCanceled) {
+      debug('page map generation cancelled')
+      reporter.warn('PDF generation cancelled')
+      return
+    }
+    throw new PdfGenerationError('Prince', 'page map generation', error.stderr)
   }
+  debug('page map generated: %d entries', Object.keys(pageMap).length)
 
   let coversData
 
   if (pdfConfig?.pagePDF?.coverPage === true && fs.existsSync(coversInput)) {
+    debug('generating cover page map')
+    reporter.update('Rendering cover pages...')
+    try {
+      const coversPageMapOutput = await execa('prince', [...pageMapOptions, coversInput], {
+        cancelSignal: processManager.signal,
+        gracefulCancel: true
+      })
+      const coversMap = JSON.parse(coversPageMapOutput.stdout)
+
+      for (const pageId of Object.keys(coversMap)) {
+        if (pageId in pageMap) {
+          pageMap[pageId].coverPage = coversMap[pageId].startPage
+        }
+      }
 
-    const coversPageMapOutput = await execa('prince', [...pageMapOptions, coversInput])
-    const coversMap = JSON.parse(coversPageMapOutput.stdout)
-
-    for (const pageId of Object.keys(coversMap))  {
-      if (pageId in pageMap) {
-        pageMap[pageId].coverPage = coversMap[pageId].startPage       
+      coversData = fs.readFileSync(pdfPath, null)
+    } catch (error) {
+      if (error.isCanceled) {
+        debug('cover page map generation cancelled')
+        reporter.warn('PDF generation cancelled')
+        return
       }
+      throw new PdfGenerationError('Prince', 'cover page map generation', error.stderr || error.message)
     }
+    debug('cover page map merged')
+  }
 
-    coversData = fs.readFileSync(output,null)
+  debug('printing PDF')
+  reporter.update('Rendering PDF...')
 
+  try {
+    const { stderr } = await execa('prince', [...cmdOptions, publicationInput], {
+      cancelSignal: processManager.signal,
+      gracefulCancel: true
+    })
+    // Prince may emit warnings to stderr even on success (CSS warnings, font substitutions, etc.)
+    if (stderr) {
+      debug('prince warnings: %s', stderr)
+    }
+  } catch (error) {
+    if (error.isCanceled) {
+      debug('PDF printing cancelled')
+      reporter.warn('PDF generation cancelled')
+      return
+    }
+    throw new PdfGenerationError('Prince', 'PDF printing', error.stderr)
   }
+  debug('PDF printed')
 
-  let stderror,stdout
-
+  let pdfData
   try {
-    ({ stderror, stdout } = await execa('prince', [...cmdOptions, publicationInput]))
-  } catch (err) {
-    console.error(`Printing the PDF failed with the error ${err.stderr}`)
-    process.exit(1)
+    pdfData = fs.readFileSync(pdfPath, null)
+  } catch (error) {
+    throw new PdfGenerationError('Prince', 'PDF file read', error.message)
   }
 
-  const pdfData = fs.readFileSync(output,null)
-  
-  let files = await splitPdf(pdfData,coversData,pageMap,pdfConfig)
-  Object.entries(files).forEach( async ([filePath,pagePdf]) => {
-    await fs.promises.writeFile(filePath,pagePdf)
-      .catch((error) => console.error(error))
-  })
+  debug('splitting PDF')
+  reporter.update('Writing PDF files...')
+  try {
+    const files = await splitPdf(pdfData, coversData, pageMap, pdfConfig)
+
+    debug('writing %d section files', Object.keys(files).length)
+    await Promise.all(
+      Object.entries(files).map(([filePath, pagePdf]) =>
+        fs.promises.writeFile(filePath, pagePdf)
+      )
+    )
+  } catch (error) {
+    throw new PdfGenerationError('Prince', 'PDF splitting', error.message)
+  }
 
-  return { stderror, stdout }
+  debug('complete')
+  return pdfPath
 }

package/src/lib/pdf/prince.test.js

@@ -0,0 +1,202 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Prince PDF Engine Integration Tests
+ *
+ * Tests error handling paths that are difficult to trigger in E2E tests.
+ * The happy path is covered by E2E tests with real Prince installation.
+ */
+
+/**
+ * Create a cross-platform absolute path for testing
+ * @param {...string} segments - Path segments to join
+ * @returns {string} Platform-appropriate absolute path
+ */
+function testPath(...segments) {
+  const root = process.platform === 'win32' ? 'C:\\' : '/'
+  return path.join(root, ...segments)
+}
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+
+  // Mock reporter to prevent actual console output
+  t.context.mockReporter = {
+    update: t.context.sandbox.stub(),
+    warn: t.context.sandbox.stub()
+  }
+
+  // Mock processManager
+  t.context.mockProcessManager = {
+    signal: new AbortController().signal
+  }
+
+  // Mock fs-extra
+  t.context.mockFs = {
+    existsSync: t.context.sandbox.stub().returns(true),
+    mkdirsSync: t.context.sandbox.stub(),
+    readFileSync: t.context.sandbox.stub().returns(Buffer.from([1, 2, 3])),
+    promises: {
+      writeFile: t.context.sandbox.stub().resolves()
+    }
+  }
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error handling tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('throws PdfGenerationError when page map generation fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const execaError = new Error('Prince failed')
+  execaError.stderr = 'error: invalid HTML at line 42'
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: sandbox.stub().rejects(execaError) },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    prince.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Prince'))
+  t.true(error.message.includes('page map generation'))
+  t.true(error.message.includes('invalid HTML at line 42'))
+})
+
+test('throws PdfGenerationError when PDF printing fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  // First call (page map) succeeds, second call (print) fails
+  const execaStub = sandbox.stub()
+  execaStub.onCall(0).resolves({ stdout: '{}' }) // page map succeeds
+  const printError = new Error('Prince print failed')
+  printError.stderr = 'error: out of memory'
+  execaStub.onCall(1).rejects(printError)
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: execaStub },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    prince.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Prince'))
+  t.true(error.message.includes('PDF printing'))
+  t.true(error.message.includes('out of memory'))
+})
+
+test('throws PdfGenerationError when cover page map generation fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  // First call (page map) succeeds, second call (covers) fails
+  const execaStub = sandbox.stub()
+  execaStub.onCall(0).resolves({ stdout: '{"page-1": {"startPage": 0}}' })
+  const coversError = new Error('Prince covers failed')
+  coversError.stderr = 'error: covers file corrupt'
+  execaStub.onCall(1).rejects(coversError)
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: execaStub },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  // Enable cover page generation
+  const options = {
+    pdfConfig: { pagePDF: { coverPage: true } }
+  }
+
+  const error = await t.throwsAsync(() =>
+    prince.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), options)
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Prince'))
+  t.true(error.message.includes('cover page map generation'))
+  t.true(error.message.includes('covers file corrupt'))
+})
+
+test('warns and returns when page map generation is cancelled', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const cancelError = new Error('Cancelled')
+  cancelError.isCanceled = true
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: sandbox.stub().rejects(cancelError) },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const result = await prince.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+
+  t.is(result, undefined)
+  t.true(mockReporter.warn.calledWith('PDF generation cancelled'))
+})
+
+test('warns and returns when PDF printing is cancelled', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const execaStub = sandbox.stub()
+  execaStub.onCall(0).resolves({ stdout: '{}' }) // page map succeeds
+  const cancelError = new Error('Cancelled')
+  cancelError.isCanceled = true
+  execaStub.onCall(1).rejects(cancelError)
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: execaStub },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const result = await prince.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+
+  t.is(result, undefined)
+  t.true(mockReporter.warn.calledWith('PDF generation cancelled'))
+})
+
+test('throws PdfGenerationError when output directory creation fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager } = t.context
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(false),
+    mkdirsSync: sandbox.stub().throws(new Error('EACCES: permission denied'))
+  }
+
+  const prince = await esmock('./prince.js', {
+    execa: { execa: sandbox.stub() },
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    prince.default(testPath('input.html'), testPath('covers.html'), testPath('restricted', 'output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Prince'))
+  t.true(error.message.includes('output directory creation'))
+  t.true(error.message.includes('permission denied'))
+})

package/src/lib/pdf/schema.js

@@ -0,0 +1,21 @@
+/**
+ * PDF engine schema definition
+ *
+ * This module has NO imports to avoid circular dependencies.
+ * It serves as the single source of truth for PDF engine options.
+ */
+
+/**
+ * Supported PDF engines
+ * @type {string[]}
+ */
+export const ENGINES = ['pagedjs', 'prince']
+
+/**
+ * Schema definition for pdfEngine config property
+ */
+export const schema = {
+  type: 'string',
+  enum: ENGINES,
+  description: 'Default PDF engine to use (pagedjs, prince)'
+}

package/src/lib/pdf/split.js

@@ -1,61 +1,89 @@
 import path from 'node:path'
-
 import { PDFDocument } from 'pdf-lib'
 import { paths } from '#lib/11ty/index.js'
-  
+import { PdfGenerationError } from '#src/errors/index.js'
+import createDebug from '#debug'
+
+const debug = createDebug('lib:pdf:split')
+
 /**
- * @function splitPdf(file,pageMap) -- sections out individual PDFs from `file` according to `pageMap`
- * 
+ * Split a PDF into sections based on a page map
+ *
  * @param {ArrayBuffer} file - PDF file to split
- * @param {Object} pageMap - page map to split PDf by
- * 
- * Creates individual PDFs from by copying `file` (so boxes are already set) and stripping pages out of the range (in reverse order to retain the index sequence)
- * Returns a map of file paths to PDF binary data for serialization
+ * @param {ArrayBuffer} [coversFile] - Optional covers PDF file
+ * @param {Object} pageMap - Map of page IDs to page ranges
+ * @param {Object} [pdfConfig] - PDF configuration from project config
+ * @returns {Promise<Object>} Map of file paths to PDF binary data
+ * @throws {PdfGenerationError} When PDF loading or manipulation fails
  */
+export async function splitPdf(file, coversFile, pageMap, pdfConfig) {
 
-export async function splitPdf(file,coversFile,pageMap,pdfConfig) {
-
-  if (!pdfConfig) { 
+  if (!pdfConfig) {
+    debug('No pdfConfig provided, PDF splitting skipped.')
     return {}
   }
 
   const { filename, outputDir } = pdfConfig
 
-  const pdfDoc = await PDFDocument.load(file)
+  debug('loading main PDF')
+  let pdfDoc
+  try {
+    pdfDoc = await PDFDocument.load(file)
+  } catch (error) {
+    throw new PdfGenerationError('pdf-lib', 'load main PDF', error.message)
+  }
+  debug('main PDF loaded: %d pages', pdfDoc.getPageCount())
 
-  const coversDoc = (coversFile !== undefined) ? await PDFDocument.load(coversFile) : undefined
+  let coversDoc
+  if (coversFile !== undefined) {
+    debug('loading covers PDF')
+    try {
+      coversDoc = await PDFDocument.load(coversFile)
+    } catch (error) {
+      throw new PdfGenerationError('pdf-lib', 'load covers PDF', error.message)
+    }
+    debug('covers PDF loaded: %d pages', coversDoc.getPageCount())
+  }
 
   let resultFiles = {}
+  const pageEntries = Object.entries(pageMap)
+  debug('splitting into %d sections', pageEntries.length)
 
-  for ( const [pageId, pageConfig] of Object.entries(pageMap) ) {
+  for (const [pageId, pageConfig] of pageEntries) {
     const { endPage, startPage, coverPage } = pageConfig
 
-    // TODO: Set the PDF's sectional doc metadata
-    
-    const sectionDoc = await pdfDoc.copy()
+    try {
+      // TODO: Set the PDF's sectional doc metadata
 
-    for (let p=pdfDoc.getPageCount() - 1; p > endPage; --p) {
-      sectionDoc.removePage(p)
-    }
-    for (let q=startPage - 1; q >= 0; --q) {
-      sectionDoc.removePage(q)
-    }
+      const sectionDoc = await pdfDoc.copy()
 
-    if (coversDoc && coverPage !== undefined && coverPage >= 0) {
-      // NB: `copyPages()` sets page sizing + other metadata on the way into the target PDF
-      const cover = await sectionDoc.copyPages(coversDoc,[coverPage])
-      sectionDoc.insertPage(0,cover[0])
-    }
+      for (let p = pdfDoc.getPageCount() - 1; p > endPage; --p) {
+        sectionDoc.removePage(p)
+      }
+      for (let q = startPage - 1; q >= 0; --q) {
+        sectionDoc.removePage(q)
+      }
+
+      if (coversDoc && coverPage !== undefined && coverPage >= 0) {
+        // copyPages sets page sizing and other metadata on the target PDF
+        const cover = await sectionDoc.copyPages(coversDoc, [coverPage])
+        sectionDoc.insertPage(0, cover[0])
+      }
 
-    const section = await sectionDoc.save()
+      const section = await sectionDoc.save()
 
-    const sectionId = pageId.replace(/^page-/g,'')
-    const sectionFn = `${filename}-${sectionId}.pdf`
-    const sectionFp = path.join( paths.output, outputDir, sectionFn )
+      const sectionId = pageId.replace(/^page-/g, '')
+      const sectionFn = `${filename}-${sectionId}.pdf`
+      const sectionFp = path.join(paths.getOutputDir(), outputDir, sectionFn)
 
-    resultFiles[sectionFp] = section
+      resultFiles[sectionFp] = section
+      debug('extracted section %s (pages %d-%d)', sectionId, startPage, endPage)
+    } catch (error) {
+      throw new PdfGenerationError('pdf-lib', `extract section '${pageId}'`, error.message)
+    }
   }
 
+  debug('split complete: %d files', Object.keys(resultFiles).length)
   return resultFiles
 }