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

package/src/lib/pdf/paged.js

@@ -4,25 +4,39 @@ import fs from 'fs-extra'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import processManager from '#lib/process/manager.js'
+import reporter from '#lib/reporter/index.js'
 import { splitPdf } from './split.js'
+import { PdfGenerationError } from '#src/errors/index.js'
+import ENGINES from './engines.js'
+import createDebug from '#debug'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
-// FIXME: This module swallows errors currently.
+const debug = createDebug('lib:pdf:paged')
+
+/** Re-export engine metadata from central registry */
+export const metadata = ENGINES.pagedjs
 
 /**
- * A façade module for interacting with Paged.js and pagedjs-cli  
+ * A façade module for interacting with Paged.js and pagedjs-cli
  * @see https://gitlab.coko.foundation/pagedjs/
+ *
+ * @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 = {}) => {
+export default async (publicationInput, coversInput, pdfPath, options = {}) => {
   /**
    * Configure the Paged.js Printer options
    * @see https://gitlab.coko.foundation/pagedjs/pagedjs-cli/-/blob/main/src/cli.js
    */
 
   let additionalScripts = []
-  
+
   const { pdfConfig } = options
 
   additionalScripts.push( path.join(__dirname, 'pagedPlugin.js') )
@@ -35,25 +49,35 @@ export default async (publicationInput, coversInput, output, options = {}) => {
     additionalScripts,
   }
 
-  if (options.debug) {
-    const optionsOutput = JSON.stringify(printerOptions, null, 2)
-    console.debug(`[CLI:lib/pdf/pagedjs] Printer options\n${optionsOutput}`)
-  }
+  debug('printer options: %O', printerOptions)
 
   let printer = new Printer(printerOptions)
 
-  printer.on('page', (page,pageElement,breakToken) => {
+  // Register cleanup handler for graceful shutdown
+  processManager.onShutdown('pagedjs', () => {
+    debug('closing printer')
+    printer.close()
+  })
+
+  printer.on('page', (page, pageElement, breakToken) => {
     if (page.position === 0) {
-      console.info(`[CLI:lib/pdf/pagedjs] loaded`)
-    } 
+      debug('paged.js loaded')
+    }
   })
 
   printer.on('rendered', (msg) => {
-    console.info(`[CLI:lib/pdf/pagedjs] ${msg}`)
+    debug('rendered: %s', msg)
   })
 
   printer.on('postprocessing', () => {
-    console.info(`[CLI:lib/pdf/pagedjs] post-processing`)
+    debug('post-processing')
+  })
+
+  // Capture browser console messages for debugging
+  printer.on('console', (type, ...args) => {
+    if (type === 'warning' || type === 'error') {
+      debug('browser %s: %s', type, args.join(' '))
+    }
   })
 
   /**
@@ -61,29 +85,31 @@ export default async (publicationInput, coversInput, output, options = {}) => {
    * @see
    *
    * @todo verify options before setting them
-   * @todo catch errors thrown by the printer
    */
   const pdfOptions = {
     outlineTags: options.outlineTags || ['h1'],
   }
 
-  if (options.debug) {
-    const optionsOutput = JSON.stringify(pdfOptions, null, 2)
-    console.debug(`[CLI:lib/pdf/pagedjs] PDF options\n${optionsOutput}`)
-  }
+  debug('pdf options: %O', pdfOptions)
 
-  try {
-    console.info(`[CLI:lib/pdf/pagedjs] printing ${publicationInput}`)
+  debug('printing %s', publicationInput)
+  reporter.update('Rendering PDF...')
 
-    const file = await printer.pdf(publicationInput, pdfOptions)
-      .catch((error) => console.error(error))
+  let file
+  try {
+    file = await printer.pdf(publicationInput, pdfOptions)
+  } catch (error) {
+    throw new PdfGenerationError('Paged.js', 'PDF rendering', error.message)
+  }
 
-    let pageMap
+  let pageMap
 
-    // Now it's printed, create the pageMap by running JS in the printer's context
-    let coversFile
+  // Now it's printed, create the pageMap by running JS in the printer's context
+  let coversFile
 
-    console.info(`[CLI:lib/pdf/pagedjs] generating page map`)
+  debug('extracting page map')
+  reporter.update('Extracting page map...')
+  try {
     const pages = await printer.browser.pages()
 
     if (pages.length > 0) {
@@ -92,15 +118,24 @@ export default async (publicationInput, coversInput, output, options = {}) => {
         return window.pageMap ?? {} // eslint-disable-line no-undef
       })
     }
+  } catch (error) {
+    throw new PdfGenerationError('Paged.js', 'page map extraction', error.message)
+  }
 
-    if ( pdfConfig?.pagePDF?.coverPage===true && fs.existsSync(coversInput) ) {
-      console.info(`[CLI:lib/pdf/pagedjs] printing ${coversInput}`)
+  if ( pdfConfig?.pagePDF?.coverPage===true && fs.existsSync(coversInput) ) {
+    debug('printing covers %s', coversInput)
+    reporter.update('Rendering cover pages...')
 
-      const coverPrinter = new Printer(printerOptions)
+    const coverPrinter = new Printer(printerOptions)
 
+    try {
       coversFile = await coverPrinter.pdf(coversInput, pdfOptions)
-        .catch((error) => console.error(error))
+    } catch (error) {
+      coverPrinter.close()
+      throw new PdfGenerationError('Paged.js', 'cover PDF rendering', error.message)
+    }
 
+    try {
       const coverPages = await coverPrinter.browser.pages()
 
       if (coverPages.length > 0) {
@@ -111,40 +146,53 @@ export default async (publicationInput, coversInput, output, options = {}) => {
 
         Object.values(coversMap).forEach( cov => {
           if (cov.id in pageMap) {
-            pageMap[cov.id].coverPage = cov.startPage           
+            pageMap[cov.id].coverPage = cov.startPage
           }
         })
-
       }
-
+    } catch (error) {
       coverPrinter.close()
-    }      
-
-    // Leave the printer open for debug logs
-    if (!options.debug) {
-      printer.close()    
+      throw new PdfGenerationError('Paged.js', 'cover page map extraction', error.message)
     }
 
-    if (file && output) {
-      console.info(`[CLI:lib/pdf/pagedjs] writing file(s)`)
+    coverPrinter.close()
+  }
+
+  // Leave the printer open for debug logs
+  if (!options.debug) {
+    printer.close()
+  }
+
+  // Unregister cleanup handler
+  processManager.onShutdownComplete('pagedjs')
 
-      const { dir } = path.parse(output)
-      if (!fs.existsSync(dir)) { 
+  if (file && pdfPath) {
+    debug('writing files')
+    reporter.update('Writing PDF files...')
+
+    try {
+      const { dir } = path.parse(pdfPath)
+      if (!fs.existsSync(dir)) {
         fs.mkdirsSync(dir)
       }
 
-      await fs.promises.writeFile(output, file)
-        .catch((error) => console.error(error))
+      await fs.promises.writeFile(pdfPath, file)
+    } catch (error) {
+      throw new PdfGenerationError('Paged.js', 'PDF file write', error.message)
+    }
 
-      const files = await splitPdf(file,coversFile,pageMap,options.pdfConfig)
+    try {
+      const files = await splitPdf(file, coversFile, pageMap, options.pdfConfig)
 
-      Object.entries(files).forEach( async ([filePath,pagePdf]) => {
-        await fs.promises.writeFile(filePath,pagePdf)
-          .catch((error) => console.error(error))
-      })
+      await Promise.all(
+        Object.entries(files).map(([filePath, pagePdf]) =>
+          fs.promises.writeFile(filePath, pagePdf)
+        )
+      )
+    } catch (error) {
+      throw new PdfGenerationError('Paged.js', 'PDF splitting', error.message)
     }
-
-  } catch (ERR_FILE_NOT_FOUND) {
-    console.error(`[CLI:lib/pdf/pagedjs] file not found ${publicationInput}`)
   }
+
+  return pdfPath
 }

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

@@ -0,0 +1,366 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Paged.js 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 Paged.js/Puppeteer.
+ */
+
+/**
+ * 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
+  t.context.mockReporter = {
+    update: t.context.sandbox.stub(),
+    warn: t.context.sandbox.stub()
+  }
+
+  // Mock processManager
+  t.context.mockProcessManager = {
+    onShutdown: t.context.sandbox.stub(),
+    onShutdownComplete: t.context.sandbox.stub()
+  }
+
+  // Mock fs-extra
+  t.context.mockFs = {
+    existsSync: t.context.sandbox.stub().returns(true),
+    mkdirsSync: t.context.sandbox.stub(),
+    promises: {
+      writeFile: t.context.sandbox.stub().resolves()
+    }
+  }
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+/**
+ * Create a mock Printer instance
+ */
+function createMockPrinter(sandbox, options = {}) {
+  const mockPrinter = {
+    on: sandbox.stub(),
+    close: sandbox.stub(),
+    pdf: options.pdf || sandbox.stub().resolves(Buffer.from([1, 2, 3])),
+    browser: {
+      pages: options.pages || sandbox.stub().resolves([{
+        evaluate: sandbox.stub().resolves({})
+      }])
+    }
+  }
+  return mockPrinter
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error handling tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('throws PdfGenerationError when PDF rendering fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox, {
+    pdf: sandbox.stub().rejects(new Error('Puppeteer crashed: out of memory'))
+  })
+
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Paged.js'))
+  t.true(error.message.includes('PDF rendering'))
+  t.true(error.message.includes('out of memory'))
+})
+
+test('throws PdfGenerationError when page map extraction fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox, {
+    pages: sandbox.stub().rejects(new Error('Browser context destroyed'))
+  })
+
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Paged.js'))
+  t.true(error.message.includes('page map extraction'))
+  t.true(error.message.includes('Browser context destroyed'))
+})
+
+test('throws PdfGenerationError when cover PDF rendering fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  // Main printer succeeds
+  const mainPrinter = createMockPrinter(sandbox)
+
+  // Cover printer fails
+  const coverPrinter = createMockPrinter(sandbox, {
+    pdf: sandbox.stub().rejects(new Error('Cover page timeout'))
+  })
+
+  let printerCallCount = 0
+  const MockPrinter = sandbox.stub().callsFake(() => {
+    printerCallCount++
+    return printerCallCount === 1 ? mainPrinter : coverPrinter
+  })
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    '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(() =>
+    paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), options)
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Paged.js'))
+  t.true(error.message.includes('cover PDF rendering'))
+  t.true(error.message.includes('Cover page timeout'))
+  // Verify cover printer was closed on error
+  t.true(coverPrinter.close.called)
+})
+
+test('throws PdfGenerationError when cover page map extraction fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  // Main printer succeeds
+  const mainPrinter = createMockPrinter(sandbox)
+
+  // Cover printer PDF succeeds but pages() fails
+  const coverPrinter = createMockPrinter(sandbox, {
+    pages: sandbox.stub().rejects(new Error('Cover browser crashed'))
+  })
+
+  let printerCallCount = 0
+  const MockPrinter = sandbox.stub().callsFake(() => {
+    printerCallCount++
+    return printerCallCount === 1 ? mainPrinter : coverPrinter
+  })
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const options = {
+    pdfConfig: { pagePDF: { coverPage: true } }
+  }
+
+  const error = await t.throwsAsync(() =>
+    paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), options)
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Paged.js'))
+  t.true(error.message.includes('cover page map extraction'))
+  t.true(error.message.includes('Cover browser crashed'))
+  t.true(coverPrinter.close.called)
+})
+
+test('throws PdfGenerationError when PDF file write fails', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(false),
+    mkdirsSync: sandbox.stub().throws(new Error('EACCES: permission denied')),
+    promises: { writeFile: sandbox.stub() }
+  }
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager }
+  })
+
+  const error = await t.throwsAsync(() =>
+    paged.default(testPath('input.html'), testPath('covers.html'), testPath('restricted', 'output.pdf'), {})
+  )
+
+  t.is(error.code, 'PDF_FAILED')
+  t.true(error.message.includes('Paged.js'))
+  t.true(error.message.includes('PDF file write'))
+  t.true(error.message.includes('permission denied'))
+})
+
+test('closes printer on successful completion when not in debug mode', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager },
+    './split.js': { splitPdf: sandbox.stub().resolves({}) }
+  })
+
+  await paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), { debug: false })
+
+  t.true(mockPrinter.close.called)
+  t.true(mockProcessManager.onShutdownComplete.calledWith('pagedjs'))
+})
+
+test('keeps printer open when in debug mode', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager },
+    './split.js': { splitPdf: sandbox.stub().resolves({}) }
+  })
+
+  await paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), { debug: true })
+
+  t.false(mockPrinter.close.called)
+})
+
+test('registers console event handler for browser warnings and errors', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const mockDebug = sandbox.stub()
+  const mockCreateDebug = sandbox.stub().returns(mockDebug)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager },
+    '#debug': { default: mockCreateDebug },
+    './split.js': { splitPdf: sandbox.stub().resolves({}) }
+  })
+
+  await paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+
+  // Verify console handler was registered
+  const consoleHandler = mockPrinter.on.getCalls().find(call => call.args[0] === 'console')
+  t.truthy(consoleHandler, 'console event handler should be registered')
+
+  // Simulate console warning
+  const handler = consoleHandler.args[1]
+  handler('warning', 'CSS property not supported')
+
+  t.true(mockDebug.calledWith('browser %s: %s', 'warning', 'CSS property not supported'))
+})
+
+test('logs browser errors via debug', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const mockDebug = sandbox.stub()
+  const mockCreateDebug = sandbox.stub().returns(mockDebug)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager },
+    '#debug': { default: mockCreateDebug },
+    './split.js': { splitPdf: sandbox.stub().resolves({}) }
+  })
+
+  await paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+
+  // Get console handler
+  const consoleHandler = mockPrinter.on.getCalls().find(call => call.args[0] === 'console')
+  const handler = consoleHandler.args[1]
+
+  // Simulate console error
+  handler('error', 'Script error:', 'undefined is not a function')
+
+  t.true(mockDebug.calledWith('browser %s: %s', 'error', 'Script error: undefined is not a function'))
+})
+
+test('ignores non-warning/error console messages', async (t) => {
+  const { sandbox, mockReporter, mockProcessManager, mockFs } = t.context
+
+  const mockPrinter = createMockPrinter(sandbox)
+  const MockPrinter = sandbox.stub().returns(mockPrinter)
+
+  const mockDebug = sandbox.stub()
+  const mockCreateDebug = sandbox.stub().returns(mockDebug)
+
+  const paged = await esmock('./paged.js', {
+    'pagedjs-cli': MockPrinter,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter },
+    '#lib/process/manager.js': { default: mockProcessManager },
+    '#debug': { default: mockCreateDebug },
+    './split.js': { splitPdf: sandbox.stub().resolves({}) }
+  })
+
+  await paged.default(testPath('input.html'), testPath('covers.html'), testPath('output.pdf'), {})
+
+  // Get console handler
+  const consoleHandler = mockPrinter.on.getCalls().find(call => call.args[0] === 'console')
+  const handler = consoleHandler.args[1]
+
+  // Reset debug stub to check only calls after handler invocation
+  mockDebug.resetHistory()
+
+  // Simulate console log (should be ignored)
+  handler('log', 'Debug info')
+
+  // Should not have logged this message (info/log messages are ignored)
+  t.false(mockDebug.calledWith('browser %s: %s', 'log', 'Debug info'))
+})