@thegetty/quire-cli 1.0.0-rc.5 → 1.0.0-rc.50

package/src/lib/conf/README.md

@@ -0,0 +1,104 @@
+## CLI Configuration Manager
+
+This `quire-cli/lib/config` module manages reading and writing (persisting) options for the Quire CLI using the [`conf`](https://github.com/sindresorhus/conf) package.
+
+`conf` stores the config in the system default [user config directory](https://github.com/sindresorhus/env-paths#pathsconfig). For example, on macOS, the config file will be stored in the `~/Library/Preferences/@thegetty/quire-cli` directory.
+
+> Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config.
+
+### Configuration
+
+`logLevel` The default logging level for the Quire CLI output; default `'info'`.
+
+`projectTemplate` A default project starter template to use when creating new projects; default `'quire-starter-default'`.
+
+`quirePath` The relative path to `quire-11ty` installed in the project directory; default `./11ty`. When set to `null`, `quire-11ty` is installed to the CLI `lib/quire/versions/<version>/` directory.
+
+```sh
+❯ quire config quire-path '.'
+```
+
+`quireVersion` The default version of `quire-11ty` to install when creating new Quire projects; default `'latest'`.
+
+```sh
+❯ quire config quire-version '1.0.0'
+```
+
+`telemetry` Send anonymous data about Quire usage; default `false`.
+
+```sh
+❯ quire config telemetry --enabled
+```
+
+```sh
+❯ quire config telemetry --disabled
+```
+
+`updateChannels` A list of distribution tags to use when checking for version updates; default `['latest']`. To show notifications for pre-releases version updates include `'pre-release'` in the array of channels. This can be set using the configuration `--pre-release` command flag.
+
+```sh
+❯ quire config update-channels
+Quire configured to check for updates tagged 'latest'
+```
+
+```sh
+❯ quire config update-channels --add 'pre-release'
+Quire configured to check for updates tagged 'latest', 'pre-release'
+```
+
+```sh
+❯ quire config update-channels --rm 'pre-release'
+Quire configured to check for updates tagged 'latest'
+```
+
+`updateInterval` Interval at which to check for updates to the Quire CLI and project's `quire-11ty` version; default `'DAILY'`.
+
+```sh
+❯ quire config update-interval
+Quire configured to check for updates DAILY
+```
+
+```sh
+❯ quire config update-interval WEEKLY
+```
+
+`versionFile ['.quire-version']` The default file name for the `quire-11ty` version file.
+
+```sh
+❯ quire config version-file '.blargh'
+```
+
+### Quire CLI `config` Command
+
+Running the `config` command without any arguments will start an interactive prompt to configure Quire.
+
+To view an individual configuration value and its default value use:
+
+```sh
+❯ quire config [key]
+```
+
+To view the current `logLevel` setting for example:
+
+```sh
+❯ quire config logLevel
+loglevel: 'debug' (default 'info')
+```
+
+To set an individual configuration value, use the `set` argument:
+
+```sh
+❯ quire config set <key> <value>
+```
+
+To reset *all* keys to their default values, use the `reset` argument:
+
+```sh
+❯ quire config reset
+```
+
+To reset an individual key to its default value:
+
+```sh
+❯ quire config reset [key]
+```

package/src/lib/conf/config.js

@@ -0,0 +1,35 @@
+import Conf from 'conf'
+import defaults from './defaults.js'
+import migrations from './migrations.js'
+import packageConfig from '#src/packageConfig.js'
+import schema from './schema.js'
+
+const { name, version } = packageConfig
+
+const beforeEachMigration = (store, context) => {
+  const { fromVersion, toVersion } = context
+  console.info(`quire-cli migrating config from ${fromVersion} → ${toVersion}`)
+}
+
+/**
+ * Create quire-cli configuration instance
+ * @see https://github.com/sindresorhus/conf#confoptions
+ *
+ * @todo support yaml configuration files
+ * https://github.com/sindresorhus/conf?tab=readme-ov-file#can-i-use-yaml-or-another-serialization-format
+ *
+ * @type       {Conf}
+ */
+const config = new Conf({
+  beforeEachMigration,
+  clearInvalidConfig: true,
+  defaults,
+  migrations,
+  projectName: name,
+  projectSuffix: '',
+  projectVersion: version,
+  schema,
+  watch: true,
+})
+
+export default config

package/src/lib/conf/defaults.js

@@ -0,0 +1,37 @@
+/**
+ * Default values for Quire configuration properties
+ *
+ * Nota bene: these values will overwrite schema default values
+ * @see https://github.com/sindresorhus/conf#defaults
+ */
+export default {
+  /**
+   * Logging level for the Quire CLI output.
+   */
+  logLevel: 'info',
+  /**
+   * Project starter template to use when creating new projects.
+   */
+  projectTemplate: 'https://github.com/thegetty/quire-starter-default',
+  /**
+   * Relative path to quire-11ty installed in the project directory.
+   */
+  quire11tyPath: '.',
+  /**
+   * Version of quire-11ty to install when creating new projects.
+   */
+  quireVersion: 'latest',
+  /**
+   * Npm distribution tag to use when checking for version updates
+   */
+  updateChannel: 'rc',
+  /**
+   * Interval at which to check for updates to the Quire CLI
+   * and to quire-11ty version for a prject.
+   */
+  updateInterval: 'DAILY',
+  /**
+   * File name for the quire-11ty version file.
+   */
+  versionFile: '.quire',
+}

package/src/lib/conf/migrations.js

@@ -0,0 +1,11 @@
+/**
+ * Quire configuration migrations
+ * @see https://github.com/sindresorhus/conf#migrations
+ */
+const migrations = {
+  '1.0.0': (store) => {
+    store.set('updateChannel', 'latest')
+  }
+}
+
+export default migrations

package/src/lib/conf/schema.js

@@ -0,0 +1,30 @@
+/**
+ * Quire configuration schema
+ * @see https://github.com/sindresorhus/conf#schema
+ *
+ * Nota bene: schema default values will are overwritten by `defaults.js` values
+ * @see https://github.com/sindresorhus/conf#defaults
+ */
+export default {
+  logLevel: {
+    type: 'string'
+  },
+  projectTemplate: {
+    type: 'string'
+  },
+  quire11tyPath: {
+    type: 'string'
+  },
+  quireVersion: {
+    type: 'string'
+  },
+  updateChannel: {
+    type: 'string'
+  },
+  updateInterval: {
+    type: 'string'
+  },
+  versionFile: {
+    type: 'string'
+  }
+}

package/src/lib/epub/index.js

@@ -11,7 +11,9 @@ const __dirname = path.dirname(__filename)
 export default async (name = 'epubjs', options = {}) => {
   const lib = { name, options, path }
 
-  switch (lib.toLowerCase()) {
+  const normalizedName = name.replace(/[-_.\s]/g, '').toLowerCase()
+
+  switch (normalizedName) {
     case 'epubjs': {
       lib.name = 'Epub.js'
       lib.options = {}

package/src/lib/pdf/README.md

@@ -1,12 +1,19 @@
 ## CLI lib/PDF Module
 
-This module implements a façade for PDF generation libries.
-The module exports a single method that accepts a `lib` option and delegates to a façade for the specified PDF library.
+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.
+
+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
 
-See the [`Paged.js` documentation](https://gitlab.coko.foundation/pagedjs/).
+We use [`pagedjs-cli`](https://gitlab.coko.foundation/pagedjs/pagedjs-cli), which adds a headless to paged.js to facilitate serializing to PDF files.
+
+For more details on the PDF generating API see the [`Paged.js` documentation](https://gitlab.coko.foundation/pagedjs/). See paged.js's [hooks documentation](https://pagedjs.org/documentation/10-handlers-hooks-and-custom-javascript/) for details on the `afterRendered` hook that quire uses to generate the PDF page map.
 
 ### Prince XML Façade
 
-See the [Prince Command-line Reference](https://www.princexml.com/doc/command-line/).
+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.

package/src/lib/pdf/index.js

@@ -11,18 +11,20 @@ const __dirname = path.dirname(__filename)
 export default async (name = 'pagedjs', options = {}) => {
   const lib = { name, options, path }
 
-  switch (name.toLowerCase()) {
+  const normalizedName = name.replace(/[-_.\s]/g, '').toLowerCase()
+
+  switch (normalizedName) {
     case 'paged':
     case 'pagedjs': {
       lib.name = 'Paged.js'
-      lib.options = { debug: options.debug }
+      lib.options = options
       lib.path = path.join(__dirname, 'paged.js')
       break
     }
     case 'prince':
     case 'princexml': {
       lib.name = 'Prince'
-      lib.options = { debug: options.debug, verbose: options.verbose }
+      lib.options = options
       lib.path = path.join(__dirname, 'prince.js')
       break
     }
@@ -33,8 +35,8 @@ export default async (name = 'pagedjs', options = {}) => {
 
   const { default: pdfLib } = await dynamicImport(lib.path)
 
-  return async (input, output) => {
+  return async (publicationInput, coversInput, output) => {
     console.info(`[CLI:lib/pdf] generating PDF using ${lib.name}`)
-    return await pdfLib(input, output, lib.options)
+    return await pdfLib(publicationInput, coversInput, output, lib.options)
   }
 }

package/src/lib/pdf/paged.js

@@ -1,19 +1,38 @@
 import Printer from 'pagedjs-cli'
+
 import fs from 'fs-extra'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { splitPdf } from './split.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// FIXME: This module swallows errors currently.
 
 /**
- * A façade module for interacting with Paged.js
+ * A façade module for interacting with Paged.js and pagedjs-cli  
  * @see https://gitlab.coko.foundation/pagedjs/
  */
-export default async (input, output, options = {}) => {
+export default async (publicationInput, coversInput, output, 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') )
+
   const printerOptions = {
     allowLocal: true,
     debug: options.debug || false,
     enableWarnings: options.debug || false,
+    closeAfter: false,
+    additionalScripts,
   }
 
   if (options.debug) {
@@ -21,12 +40,12 @@ export default async (input, output, options = {}) => {
     console.debug(`[CLI:lib/pdf/pagedjs] Printer options\n${optionsOutput}`)
   }
 
-  const printer = new Printer(printerOptions)
+  let printer = new Printer(printerOptions)
 
-  printer.on('page', (page) => {
+  printer.on('page', (page,pageElement,breakToken) => {
     if (page.position === 0) {
       console.info(`[CLI:lib/pdf/pagedjs] loaded`)
-    }
+    } 
   })
 
   printer.on('rendered', (msg) => {
@@ -54,18 +73,78 @@ export default async (input, output, options = {}) => {
   }
 
   try {
-    console.info(`[CLI:lib/pdf/pagedjs] printing ${input}`)
+    console.info(`[CLI:lib/pdf/pagedjs] printing ${publicationInput}`)
 
-    const file = await printer.pdf(input, pdfOptions)
+    const file = await printer.pdf(publicationInput, pdfOptions)
       .catch((error) => console.error(error))
 
-    printer.close()
+    let pageMap
+
+    // 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`)
+    const pages = await printer.browser.pages()
+
+    if (pages.length > 0) {
+      pageMap = await pages[pages.length - 1].evaluate(() => {
+        // Retrieves the pageMap from our plugin
+        return window.pageMap ?? {} // eslint-disable-line no-undef
+      })
+    }
+
+    if ( pdfConfig?.pagePDF?.coverPage===true && fs.existsSync(coversInput) ) {
+      console.info(`[CLI:lib/pdf/pagedjs] printing ${coversInput}`)
+
+      const coverPrinter = new Printer(printerOptions)
+
+      coversFile = await coverPrinter.pdf(coversInput, pdfOptions)
+        .catch((error) => console.error(error))
+
+      const coverPages = await coverPrinter.browser.pages()
+
+      if (coverPages.length > 0) {
+        const coversMap = await coverPages[coverPages.length - 1].evaluate(() => {
+          // Retrieves the pageMap from our plugin
+          return window.pageMap ?? {} // eslint-disable-line no-undef
+        })
+
+        Object.values(coversMap).forEach( cov => {
+          if (cov.id in pageMap) {
+            pageMap[cov.id].coverPage = cov.startPage           
+          }
+        })
+
+      }
+
+      coverPrinter.close()
+    }      
+
+    // Leave the printer open for debug logs
+    if (!options.debug) {
+      printer.close()    
+    }
 
     if (file && output) {
+      console.info(`[CLI:lib/pdf/pagedjs] writing file(s)`)
+
+      const { dir } = path.parse(output)
+      if (!fs.existsSync(dir)) { 
+        fs.mkdirsSync(dir)
+      }
+
       await fs.promises.writeFile(output, file)
         .catch((error) => console.error(error))
+
+      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))
+      })
     }
+
   } catch (ERR_FILE_NOT_FOUND) {
-    console.error(`[CLI:lib/pdf/pagedjs] file not found ${input}`)
+    console.error(`[CLI:lib/pdf/pagedjs] file not found ${publicationInput}`)
   }
 }

package/src/lib/pdf/pagedPlugin.js

@@ -0,0 +1,49 @@
+/**
+ * @class pageTableMapper
+ * 
+ * Responds to [paged.js afterRender hook](https://pagedjs.org/documentation/10-handlers-hooks-and-custom-javascript/) to map the PDF's page table and store it in window.pageMap
+ * 
+ */
+class pageTableMapper extends Paged.Handler { // eslint-disable-line no-undef
+  constructor(chunker, polisher, caller) {
+    super(chunker, polisher, caller)
+  }
+
+  /**
+   * @function afterRendered - fires after all pages are laid out and PDF data is available
+   * 
+   * @param {Array<Page>} pages - Pages rendered from the document
+   */
+  afterRendered(pages) {
+    let pageMap = {}
+    let webpageKey
+
+    // Iterate pages, build lookup by finding the website page on each PDF page
+    for (const p of pages) {
+      const quirePageElement = p.element.querySelector('.quire-page')
+
+      if (!quirePageElement) { continue }
+      if (quirePageElement.dataset.pagePdf !== 'true') { continue }
+
+      const quirePageId = quirePageElement.dataset.id ?? quirePageElement.id
+
+      if (webpageKey !== quirePageId) {
+        webpageKey = quirePageId
+
+        const title = quirePageElement.dataset.pdfCoverPageTitle
+
+        let data = { id: webpageKey, startPage: p.position, endPage: p.position, title, }
+
+        pageMap[webpageKey] = data
+
+      } else {
+        pageMap[webpageKey].endPage = p.position
+      }
+    }
+
+    window.pageMap = pageMap // eslint-disable-line no-undef
+
+  }
+}
+
+Paged.registerHandlers(pageTableMapper) // eslint-disable-line no-undef

package/src/lib/pdf/prince.js

@@ -1,23 +1,98 @@
 import { execa } from 'execa'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { splitPdf } from './split.js'
+import fs from 'fs-extra'
+
 import which from '#helpers/which.js'
 
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
 /**
  * A façade module for interacting with the Prince CLI.
  * @see https://www.princexml.com/doc/command-line/
  */
-export default async (input, output, options = {}) => {
+export default async (publicationInput, coversInput, output, options = {}) => {
   which('prince')
 
   /**
    * @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}`,
+  ]
+
+  // These options are for the actual user-facing PDF
   const cmdOptions = [
     `--output=${output}`,
+    `--pdf-profile=PDF/UA-1`,
   ]
 
-  if (options.debug) cmdOptions.push('--debug')
-  if (options.verbose) cmdOptions.push('--verbose')
+  if (options.debug) {
+    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)
+  }
+  
+  // Execute the page mapping PDF build  
+  let pageMap = {}
+  try {
+    const pageMapOutput = await execa('prince', [...pageMapOptions, publicationInput])  
+    pageMap = JSON.parse(pageMapOutput.stdout)
+  } catch (err) {
+    console.error(`Generating the PDF page map failed with the error ${err.stderr}`)
+    process.exit(1)
+  }
+
+  let coversData
+
+  if (pdfConfig?.pagePDF?.coverPage === true && fs.existsSync(coversInput)) {
+
+    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(output,null)
+
+  }
+
+  let stderror,stdout
+
+  try {
+    ({ stderror, stdout } = await execa('prince', [...cmdOptions, publicationInput]))
+  } catch (err) {
+    console.error(`Printing the PDF failed with the error ${err.stderr}`)
+    process.exit(1)
+  }
+
+  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))
+  })
 
-  const { stderror, stdout } = await execa('prince', [...cmdOptions, input])
   return { stderror, stdout }
 }

package/src/lib/pdf/princePlugin.js

@@ -0,0 +1,35 @@
+/**
+ * @function generatePageMap()
+ * 
+ * Walks the PDF-HTML map after printing and serializes the mapped output to STDOUT
+ */
+function generatePageMap() {
+  
+  const els = document.querySelectorAll('.quire-page[data-page-pdf=true]') // eslint-disable-line no-undef
+  let pageMap = {}
+
+  for (let i=0;i < els.length;i++) {
+  
+    const el = els[i]
+    const boxes = el.getPrinceBoxes()
+
+    if (boxes.length < 1) { continue }
+
+    let data = { id: el.getAttribute('data-id') || el.id, title: el.getAttribute('data-footer-page-title'), startPage: boxes[0].pageNum - 1, endPage: boxes[boxes.length-1].pageNum - 1 }
+
+    let pageKey = el.getAttribute('data-id') || el.id
+
+    pageMap[pageKey] = data 
+
+    if ( el.getAttribute('data-pdf-cover-page') !== 'true' ) {
+      continue
+    }
+
+  }
+
+  console.log(JSON.stringify(pageMap))
+
+}
+
+Prince.trackBoxes = true // eslint-disable-line no-undef
+Prince.oncomplete = generatePageMap // eslint-disable-line no-undef

package/src/lib/pdf/split.js

@@ -0,0 +1,61 @@
+import path from 'node:path'
+
+import { PDFDocument } from 'pdf-lib'
+import { paths } from '#lib/11ty/index.js'
+  
+/**
+ * @function splitPdf(file,pageMap) -- sections out individual PDFs from `file` according to `pageMap`
+ * 
+ * @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
+ */
+
+export async function splitPdf(file,coversFile,pageMap,pdfConfig) {
+
+  if (!pdfConfig) { 
+    return {}
+  }
+
+  const { filename, outputDir } = pdfConfig
+
+  const pdfDoc = await PDFDocument.load(file)
+
+  const coversDoc = (coversFile !== undefined) ? await PDFDocument.load(coversFile) : undefined
+
+  let resultFiles = {}
+
+  for ( const [pageId, pageConfig] of Object.entries(pageMap) ) {
+    const { endPage, startPage, coverPage } = pageConfig
+
+    // TODO: Set the PDF's sectional doc metadata
+    
+    const sectionDoc = await pdfDoc.copy()
+
+    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) {
+      // 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])
+    }
+
+    const section = await sectionDoc.save()
+
+    const sectionId = pageId.replace(/^page-/g,'')
+    const sectionFn = `${filename}-${sectionId}.pdf`
+    const sectionFp = path.join( paths.output, outputDir, sectionFn )
+
+    resultFiles[sectionFp] = section
+  }
+
+  return resultFiles
+}
+