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

package/src/lib/pdf/README.md

@@ -2,6 +2,66 @@
 
 This module provides an abstraction to ease PDF generation across PrinceXML and Paged.js. The exported module dynamically loads a wrapper to align the libraries' JS APIs by exporting a single method that accepts a `lib` option and returns an async function that takes input, output, and option params.
 
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      lib/pdf/index.js                       │
+│  • Façade: resolves engine, validates prerequisites         │
+│  • Checks engine availability (fail-fast before reporter)   │
+│  • Owns reporter lifecycle (start/succeed/fail)             │
+└─────────────────┬─────────────────────────┬─────────────────┘
+                  │                         │
+        ┌─────────┴─────────┐     ┌─────────┴─────────┐
+        │   paged.js        │     │    prince.js      │
+        │   (Paged.js CLI)  │     │   (Prince CLI)    │
+        └─────────┬─────────┘     └─────────┬─────────┘
+                  │                         │
+                  └───────────┬─────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    │     split.js      │
+                    │  (pdf-lib logic)  │
+                    └───────────────────┘
+```
+
+### Usage
+
+```javascript
+import generatePdf from '#lib/pdf/index.js'
+
+// Basic usage (uses project config for output path)
+const pdfPath = await generatePdf({ lib: 'pagedjs' })
+
+// With custom output path
+const pdfPath = await generatePdf({
+  lib: 'prince',
+  output: 'downloads/my-book.pdf'  // relative to project root
+})
+
+// With absolute path
+const pdfPath = await generatePdf({
+  lib: 'pagedjs',
+  output: '/tmp/publication.pdf'
+})
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `lib` | string | `'pagedjs'` | PDF engine: `'pagedjs'` or `'prince'` |
+| `output` | string | from config | Output path (overrides project config) |
+| `debug` | boolean | `false` | Enable debug output |
+
+### Output Path Resolution
+
+1. If `options.output` is provided, it is used (relative paths resolved against project root)
+2. Otherwise, uses `config.pdf.outputDir` + `config.pdf.filename` from project config
+3. If no config, falls back to `{projectRoot}/{libName}.pdf`
+
+### Page Mapping
+
 The module also provides plugins for Prince and Paged.js to map quire webpages to PDF pages. In both cases this is achieved after PDF rendering by querying the HTML document that was printed for `.quire-page` elements and using the PDF generator's APIs to determine content page ids, page data like titles and contributors, and first / last pages. They then use a simple stripping algorithm with `pdf-lib` to split the pages for `--page-pdf` flagged runs.
 
 ### Paged.js Façade
@@ -17,3 +77,74 @@ The Prince abstraction wraps the command line execution of the Prince executable
 See the [Prince Command-line Reference](https://www.princexml.com/doc/command-line/). Prince's [scripting documentation](https://www.princexml.com/doc/javascript/) has details on its runtime Javascript implementation, *which is only compatible up to ES5*.
 
 The Prince plugin passes page map data as JSON to STDOUT.
+
+### Test Strategy
+
+The PDF module uses a layered testing approach:
+
+| Layer | Test Type | Coverage |
+|-------|-----------|----------|
+| `index.js` | Unit tests | Engine resolution, path resolution, availability checks |
+| `paged.js` | Integration tests | Error paths (Puppeteer failures, file write errors) |
+| `prince.js` | Integration tests | Error paths (Prince failures, cancellation handling) |
+| `split.js` | Unit tests | Pure PDF manipulation logic with mocked pdf-lib |
+| Full flow | E2E tests | Happy paths with real tools |
+
+#### Why This Strategy?
+
+**Façade (`index.js`)** - Unit tests verify:
+- Engine name normalization (`pagedjs`, `paged`, `paged.js` → same engine)
+- Output path resolution priority (CLI > config > fallback)
+- Engine availability checking (Prince binary in PATH)
+- Error handling for missing prerequisites
+
+**Engine implementations (`paged.js`, `prince.js`)** - Integration tests for error paths:
+- These are orchestration code that wire external tools (Puppeteer, Prince CLI) with reporter updates
+- Happy paths are well-covered by E2E tests with real tools
+- Error paths (tool crashes, permission errors, cancellation) are hard to trigger in E2E
+- Tests mock `execa`/`pagedjs-cli` to verify error wrapping and cleanup
+
+**PDF splitting (`split.js`)** - Unit tests:
+- Pure logic that manipulates PDFs using pdf-lib
+- No external tool dependencies
+- Tests mock pdf-lib's `PDFDocument` to verify page extraction, cover insertion, and error handling
+
+**E2E tests** - Full integration:
+- Test the complete `quire pdf` command with real publications
+- Verify actual PDF output with both engines (when available)
+- Cover the happy path that unit/integration tests intentionally skip
+
+#### Running Tests
+
+```bash
+# All PDF module tests
+npm run test:unit -- src/lib/pdf/
+
+# Specific test files
+npm run test:unit -- src/lib/pdf/index.test.js    # façade tests
+npm run test:unit -- src/lib/pdf/paged.test.js    # Paged.js error paths
+npm run test:unit -- src/lib/pdf/prince.test.js   # Prince error paths
+npm run test:unit -- src/lib/pdf/split.test.js    # PDF splitting logic
+```
+
+### Error Handling
+
+All errors are wrapped in typed `PdfGenerationError` with:
+- Tool name (`'Prince'`, `'Paged.js'`)
+- Operation that failed (`'PDF rendering'`, `'page map extraction'`, etc.)
+- Underlying error details
+
+Example error flow:
+```
+Prince CLI fails → execa rejects with stderr
+  → prince.js catches, wraps in PdfGenerationError
+    → index.js catches, calls reporter.fail(), re-throws
+      → Command handler displays formatted error to user
+```
+
+### Graceful Shutdown
+
+Both engines support Ctrl+C cancellation:
+- `prince.js` uses `execa`'s `cancelSignal` option
+- `paged.js` registers cleanup with `processManager.onShutdown()`
+- On cancellation, `reporter.warn('PDF generation cancelled')` notifies the user

package/src/lib/pdf/engines.js

@@ -0,0 +1,46 @@
+/**
+ * PDF Engine Registry
+ *
+ * Centralized metadata for PDF engines. Each engine module re-exports
+ * its metadata from here, ensuring single source of truth.
+ *
+ * The façade imports this registry to:
+ * 1. Resolve engine names to implementations
+ * 2. Check binary availability before loading heavy modules
+ * 3. Provide helpful error messages with install URLs
+ */
+import { docsUrl } from '#helpers/docs-url.js'
+
+/**
+ * @typedef {Object} EngineMetadata
+ * @property {string} name - Human-readable display name
+ * @property {string} module - Module filename (e.g., 'paged.js')
+ * @property {string|null} requiresBinary - CLI binary name, or null if built-in
+ * @property {Object} [toolInfo] - Error metadata (only for engines requiring binaries)
+ * @property {string} [toolInfo.displayName] - Display name for error messages
+ * @property {string} [toolInfo.installUrl] - URL to download the tool
+ * @property {string} [toolInfo.docsUrl] - Quire docs URL
+ * @property {string} [toolInfo.fallback] - Alternative suggestion
+ */
+
+/** @type {Record<string, EngineMetadata>} */
+const ENGINES = {
+  pagedjs: {
+    name: 'Paged.js',
+    module: 'paged.js',
+    requiresBinary: null, // Built-in Node.js library
+  },
+  prince: {
+    name: 'Prince',
+    module: 'prince.js',
+    requiresBinary: 'prince',
+    toolInfo: {
+      displayName: 'PrinceXML',
+      installUrl: 'https://www.princexml.com/download/',
+      docsUrl: docsUrl('pdf-output'),
+      fallback: 'Or use the default PDF engine: quire pdf --engine pagedjs',
+    },
+  },
+}
+
+export default ENGINES

package/src/lib/pdf/index.js

@@ -1,42 +1,145 @@
 import { dynamicImport } from '#helpers/os-utils.js'
+import which from '#helpers/which.js'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
+import fs from 'fs-extra'
+import paths, { loadProjectConfig } from '#lib/project/index.js'
+import reporter from '#lib/reporter/index.js'
+import { InvalidPdfLibraryError, MissingBuildOutputError } from '#src/errors/index.js'
+import ENGINE_METADATA from './engines.js'
+import createDebug from '#debug'
+import { ENGINES } from './schema.js'
+
+export { ENGINES }
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+const debug = createDebug('lib:pdf')
+
 /**
- * A façade delegation module for PDF generation libraries
+ * Resolve the PDF library implementation
+ *
+ * @param {string} name - Library name to resolve
+ * @returns {Object} Resolved engine with absolute module path
+ * @throws {InvalidPdfLibraryError} When library name is not recognized
  */
-export default async (name = 'pagedjs', options = {}) => {
-  const lib = { name, options, path }
-
+function resolveLibrary(name) {
   const normalizedName = name.replace(/[-_.\s]/g, '').toLowerCase()
 
   switch (normalizedName) {
     case 'paged':
-    case 'pagedjs': {
-      lib.name = 'Paged.js'
-      lib.options = options
-      lib.path = path.join(__dirname, 'paged.js')
-      break
-    }
+    case 'pagedjs':
+      return { ...ENGINE_METADATA.pagedjs, path: path.join(__dirname, ENGINE_METADATA.pagedjs.module) }
     case 'prince':
-    case 'princexml': {
-      lib.name = 'Prince'
-      lib.options = options
-      lib.path = path.join(__dirname, 'prince.js')
-      break
-    }
+    case 'princexml':
+      return { ...ENGINE_METADATA.prince, path: path.join(__dirname, ENGINE_METADATA.prince.module) }
     default:
-      console.error(`[CLI:lib/pdf] Unrecognized PDF library '${name}'`)
-      return
+      throw new InvalidPdfLibraryError(name)
+  }
+}
+
+/**
+ * Check if the required binary for an engine is available
+ *
+ * @param {Object} engine - Engine definition from ENGINES
+ * @throws {ToolNotFoundError} When required binary is not in PATH
+ */
+function checkEngineAvailable(engine) {
+  if (!engine.requiresBinary) {
+    return // No binary required (e.g., pagedjs uses Node.js)
+  }
+
+  const result = which(engine.requiresBinary, engine.toolInfo)
+  debug('found %s at %s', engine.requiresBinary, result)
+}
+
+/**
+ * Construct the default output path for the PDF from project config
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {string} outputDir - Build output directory
+ * @param {Object} [pdfConfig] - PDF configuration from project config
+ * @param {string} libName - Library name for fallback filename
+ * @returns {string} Default output path
+ */
+function getDefaultOutputPath(projectRoot, outputDir, pdfConfig, libName) {
+  if (pdfConfig) {
+    return path.join(projectRoot, outputDir, pdfConfig.outputDir, `${pdfConfig.filename}.pdf`)
+  }
+  return path.join(projectRoot, `${libName}.pdf`)
+}
+
+/**
+ * Resolve the final output path, allowing CLI override
+ *
+ * @param {string} [userOutput] - User-specified output path from --output option
+ * @param {string} defaultPath - Default path from project config
+ * @param {string} projectRoot - Project root for resolving relative paths
+ * @returns {string} Resolved absolute output path
+ */
+function resolveOutputPath(userOutput, defaultPath, projectRoot) {
+  if (!userOutput) {
+    return defaultPath
+  }
+
+  // Resolve relative paths against project root
+  if (path.isAbsolute(userOutput)) {
+    return userOutput
+  }
+
+  return path.join(projectRoot, userOutput)
+}
+
+/**
+ * Generate a PDF from the built publication
+ *
+ * @param {Object} options - Generation options
+ * @param {string} [options.lib='pagedjs'] - PDF library to use ('pagedjs' or 'prince')
+ * @param {string} [options.output] - Custom output path (overrides project config)
+ * @param {boolean} [options.debug] - Enable debug output
+ * @returns {Promise<string>} Absolute path to the generated PDF file
+ */
+export default async function generatePdf(options = {}) {
+  const libName = options.lib || 'pagedjs'
+  const lib = resolveLibrary(libName)
+
+  debug('resolved library: %s → %s', libName, lib.name)
+
+  // Check engine availability BEFORE starting reporter (fail fast with clean error)
+  checkEngineAvailable(lib)
+
+  const projectRoot = paths.getProjectRoot()
+  const buildOutputDir = paths.getOutputDir()
+  const config = await loadProjectConfig(projectRoot)
+
+  const publicationInput = path.join(projectRoot, buildOutputDir, 'pdf.html')
+  const coversInput = path.join(projectRoot, buildOutputDir, 'pdf-covers.html')
+
+  debug('input: %s', publicationInput)
+  debug('covers: %s', coversInput)
+
+  if (!fs.existsSync(publicationInput)) {
+    throw new MissingBuildOutputError('pdf.html', publicationInput)
   }
 
+  const defaultPath = getDefaultOutputPath(projectRoot, buildOutputDir, config.pdf, libName)
+  const pdfPath = resolveOutputPath(options.output, defaultPath, projectRoot)
+  debug('output: %s (user: %s, default: %s)', pdfPath, options.output || 'none', defaultPath)
+
   const { default: pdfLib } = await dynamicImport(lib.path)
 
-  return async (publicationInput, coversInput, output) => {
-    console.info(`[CLI:lib/pdf] generating PDF using ${lib.name}`)
-    return await pdfLib(publicationInput, coversInput, output, lib.options)
+  reporter.start(`Generating PDF using ${lib.name}...`, { showElapsed: true })
+  reporter.detail(`Input: ${publicationInput}`)
+  reporter.detail(`Output: ${pdfPath}`)
+
+  try {
+    await pdfLib(publicationInput, coversInput, pdfPath, { ...options, pdfConfig: config.pdf })
+    reporter.succeed(`PDF saved to ${pdfPath}`)
+  } catch (error) {
+    reporter.fail(`PDF generation failed`)
+    throw error
   }
+
+  return pdfPath
 }