@thegetty/quire-cli 1.0.0-pre-release.13 → 1.0.0-pre-release.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-pre-release.13",
+  "version": "1.0.0-pre-release.15",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -51,6 +51,7 @@
     "conf": "^10.2.0",
     "cross-env": "^7.0.3",
     "del": "^7.0.0",
+    "epubjs": "^0.4.2",
     "execa": "^6.1.0",
     "fs-extra": "^11.0.0",
     "hosted-git-info": "^6.1.1",
@@ -58,7 +59,9 @@
     "inquirer": "^9.1.4",
     "install-npm-version": "^1.0.8",
     "loglevel": "^1.8.0",
+    "open": "^8.4.0",
     "ora": "^6.1.2",
+    "pagedjs-cli": "^0.3.1",
     "semver": "^7.3.8",
     "simple-git": "^3.15.0",
     "update-notifier": "^6.0.2"

package/src/commands/build.js

@@ -19,10 +19,9 @@ export default class BuildCommand extends Command {
     version: '1.0.0',
     args: [
       // [
-      //   '[formats]', 'output formats',
+      //   '[formats...]', 'output formats',
       //   {
-      //     choices: ['html', 'pdf', 'epub'],
-      //     default: ['html', 'html only']
+      //     choices: ['pdf', 'epub'],
       //   }
       // ],
     ],

package/src/commands/clean.js

@@ -20,15 +20,7 @@ export default class CleanCommand extends Command {
     description: 'Remove build outputs',
     summary: 'remove build outputs',
     version: '1.0.0',
-    args: [
-      // [
-      //   '[formats]', 'output formats',
-      //   {
-      //     choices: ['html', 'pdf', 'epub'],
-      //     default: ['html', 'html only']
-      //   }
-      // ],
-    ],
+    args: [],
     options: [
       [ '-d', '--dry-run', 'show paths to be cleaned without deleting files' ],
       [ '-p', '--progress', 'display progress of removing files' ],
@@ -52,7 +44,7 @@ export default class CleanCommand extends Command {
       ? `the following files ${options.dryRun ? 'will be' : 'have been'} deleted:`
       : 'no files to delete'
 
-    console.debug(`[CLI] ${message} ${deletedPaths}`)
+    console.debug(`[CLI] ${message}\n${deletedPaths.join('\n')}`)
   }
 
   preAction(command) {

package/src/commands/epub.js

@@ -0,0 +1,67 @@
+import Command from '#src/Command.js'
+import { paths, projectRoot  } from '#lib/11ty/index.js'
+import fs from 'fs-extra'
+import libEpub from '#lib/epub/index.js'
+import open from 'open'
+import path from 'node:path'
+
+/**
+ * Quire CLI `build epub` Command
+ *
+ * Generate EPUB from Eleventy `build` output.
+ *
+ * @class      EpubCommand
+ * @extends    {Command}
+ */
+export default class EpubCommand extends Command {
+  static definition = {
+    name: 'epub',
+    description: 'Generate publication EPUB',
+    summary: 'run build epub',
+    version: '1.0.0',
+    args: [],
+    options: [
+      [
+        '--lib <module>', 'use the specified epub library', 'epubjs',
+        { choices: ['epubjs', 'pandoc'], default: 'epubjs' }
+      ],
+      [ '--open', 'open EPUB in default application' ],
+      [ '--debug', 'run epub with debug output' ],
+    ],
+  }
+
+  constructor() {
+    super(EpubCommand.definition)
+  }
+
+  async action(options, command) {
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    const input = path.join(projectRoot, paths.epub)
+
+    if (!fs.existsSync(input)) {
+      console.error(`Unable to find Epub input at ${input}\nPlease first run the 'quire build' command.`)
+      return
+    }
+
+    const output = path.join(projectRoot, `${options.lib}.epub`)
+
+    const epubLib = await libEpub(options.lib, { ...options.debug })
+    await epubLib(input, output, { ...options.debug })
+
+    if (fs.existsSync(output) && options.open) open(output)
+  }
+
+  /**
+   * test if build site has already be run and output can be reused
+   * @todo
+   */
+  preAction(command) {
+    const options = command.opts()
+    if (options.debug) {
+      console.debug('[CLI] Calling \'epub\' command pre-action with options', options)
+    }
+  }
+}

package/src/commands/index.js

@@ -1,5 +1,5 @@
-import { IS_WINDOWS } from '#helpers/os-utils.js'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dynamicImport } from '#helpers/os-utils.js'
+import { fileURLToPath } from 'node:url'
 import fs from 'fs-extra'
 import path from 'node:path'
 
@@ -15,10 +15,7 @@ const thisfile = path.basename(__filename)
 const commands = await Promise.all(
   fs.readdirSync(__dirname)
     .filter((file) => file !== thisfile && file.match(/^.*\.js$/))
-    .map((file) => IS_WINDOWS
-      ? import(pathToFileURL(path.resolve(__dirname, file)))
-      : import(path.resolve(__dirname, file))
-    )
+    .map(async (file) => await dynamicImport(path.resolve(__dirname, file)))
 ).then((modules) => {
   return modules.map(({ default: CommandClass }) => new CommandClass())
 })

package/src/commands/pdf.js

@@ -0,0 +1,70 @@
+import Command from '#src/Command.js'
+import { paths, projectRoot  } from '#lib/11ty/index.js'
+import fs from 'fs-extra'
+import libPdf from '#lib/pdf/index.js'
+import open from 'open'
+import path from 'node:path'
+// import testcwd from '#helpers/test-cwd.js'
+
+/**
+ * Quire CLI `pdf` Command
+ *
+ * Generate PDF from Eleventy `build` output.
+ *
+ * @class      PDFCommand
+ * @extends    {Command}
+ */
+export default class PDFCommand extends Command {
+  static definition = {
+    name: 'pdf',
+    description: 'Generate publication PDF',
+    summary: 'run build pdf',
+    version: '1.0.0',
+    args: [
+    ],
+    options: [
+      [
+        '--lib <module>', 'use the specified pdf module', 'pagedjs',
+        { choices: ['pagedjs', 'prince'], default: 'pagedjs' }
+      ],
+      [ '--open', 'open PDF in default application' ],
+      [ '--debug', 'run build with debug output to console' ],
+    ],
+  }
+
+  constructor() {
+    super(PDFCommand.definition)
+  }
+
+  async action(options, command) {
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    const input = path.join(projectRoot, paths.output, 'pdf.html')
+
+    if (!fs.existsSync(input)) {
+      console.error(`Unable to find PDF input at ${input}\nPlease first run the 'quire build' command.`)
+      return
+    }
+
+    const output = path.join(projectRoot, `${options.lib}.pdf`)
+
+    const pdfLib = await libPdf(options.lib, { ...options.debug })
+    await pdfLib(input, output, { ...options.debug })
+
+    try {
+      if (fs.existsSync(output) && options.open) open(output)
+    } catch (error) {
+      console.error(error)
+      process.exit(1)
+    }
+  }
+
+  /**
+   * @todo test if build has already be run and output can be reused
+   */
+  preAction(command) {
+    // testcwd(command)
+  }
+}

package/src/commands/preview.js

@@ -18,10 +18,9 @@ export default class PreviewCommand extends Command {
     version: '1.0.0',
     args: [
       // [
-      //   '[formats]', 'output formats',
+      //   '[formats...]', 'output formats',
       //   {
-      //     choices: ['html', 'pdf', 'epub'],
-      //     default: ['html', 'html only']
+      //     choices: ['pdf', 'epub'],
       //   }
       // ],
     ],
@@ -41,9 +40,9 @@ export default class PreviewCommand extends Command {
     super(PreviewCommand.definition)
   }
 
-  action(options = {}) {
+  async action(args, options, command) {
     if (options.debug) {
-      console.info('Command \'%s\' called with options %o', this.name(), options)
+      console.debug('[CLI] Command \'%s\' called with arguments [%o] and options %o', this.name(), args.join(', '), options)
     }
 
     if (options['11ty'] === 'cli') {

package/src/helpers/clean.js

@@ -9,8 +9,10 @@ import path from 'node:path'
  */
 export async function clean (projectRoot, paths, options = {}) {
   const pathsToClean = [
+    path.join(projectRoot, paths.epub),
     path.join(projectRoot, paths.output),
-    path.join(projectRoot, paths.public),
+    path.join(projectRoot, '*.epub'),
+    path.join(projectRoot, '*.pdf'),
   ]
 
   /**

package/src/helpers/os-utils.js

@@ -1,5 +1,25 @@
+import { pathToFileURL } from 'node:url'
+
 /**
  * Determine if the process is running on Windows operating system
  */
 export const IS_WINDOWS =
   process.platform === 'win32' || /^(cygwin|msys)$/.test(process.env.OSTYPE)
+
+/**
+ * Cross platform dynamic module import
+ * On the Windows platform ESM modules are loaded using the file:// scheme.
+ *
+ * Nota bene: a relative `path` argument is relative to this module!
+ *
+ *
+ * @param      {String}  path    An aboslute path for the module to import
+ * @return     {Object}  Imported module
+ */
+export const dynamicImport = async (path) => {
+  try {
+    return IS_WINDOWS ? await import(pathToFileURL(path)) : await import(path)
+  } catch (error) {
+    console.error(`[CLI] unable to import ${path}`, error)
+  }
+}

package/src/lib/11ty/api.js

@@ -32,7 +32,7 @@ const factory = async (options = {}) => {
    */
   const copyOptions = {
     debug: options.debug || false,
-    expand: true,
+    expand: false,
   }
 
   /**
@@ -83,11 +83,19 @@ const factory = async (options = {}) => {
           return addPassthroughCopy(entry, copyOptions)
         }
       }
+
+      /**
+       * Event callback when a build completes
+       * @see https://www.11ty.dev/docs/events/#eleventy.after
+       */
+      eleventyConfig.on('eleventy.after', async () => {
+        console.debug('[11ty:API] build complete')
+      })
+
       return eleventyConfig
     },
     configPath: options.config || config,
     quietMode: options.quiet || false,
-    // source: 'script',
   })
 
   return eleventy
@@ -111,9 +119,11 @@ export default {
 
     eleventy.setDryRun(options.dryrun)
 
-    await eleventy.executeBuild()
+    await eleventy.write()
   },
   serve: async (options = {}) => {
+    process.cwd(projectRoot)
+
     console.info('[CLI:11ty] running development server')
 
     process.env.ELEVENTY_ENV = 'development'

package/src/lib/11ty/cli.js

@@ -82,10 +82,10 @@ export default {
 
     command.push('--serve')
 
-    env.ELEVENTY_ENV = 'development'
-
     if (options.port) command.push(`--port=${options.port}`)
 
+    env.ELEVENTY_ENV = 'development'
+
     await execa('node', command, {
       all: true,
       cwd: projectRoot,

package/src/lib/11ty/paths.js

@@ -23,19 +23,8 @@ const cliRoot = path.resolve(__dirname, path.join('..', '..'))
 const eleventyConfig = '.eleventy.js'
 const version = 'latest'
 
-// Test project directory for an eleventy configuration file
-const hasEleventyConfig = (dir) => {
-  try {
-    return fs.readdirSync(dir).includes(eleventyConfig)
-  } catch (error) {
-    throw new Error(`[CLI:11ty] Unable to read project directory for eleventy config ${error}`)
-  }
-}
-
 export const projectRoot = process.cwd()
 
-const inputDir = path.join(projectRoot, 'content')
-
 /**
  * Absolute path to the latest installed version of `quire-11ty`
  * @todo use version read from the project `.quire-version` file
@@ -47,13 +36,55 @@ const libQuirePath = path.resolve(__dirname, path.join(cliRoot, 'lib', 'quire',
  * Nota bene: to get a relative path to the `eleventyRoot`,
  * for example when the version is specified is 'latest',
  * it must be set to the real path to the symlink target.
+ *
+ * @todo refactor how and *when* the eleventyRoot is determined:
+ *  - we only need eleventyRoot for cli commands that run 11ty
+ *  - paths module is a concern of the `quire` module
+ *  - global quire-cli installation
+ *  - local quire-cli installation
+ *
+ *  For an excellent developer experience, the quire-11ty code should be
+ *  installed into an `11ty` or `quire-11ty` directory in the `projectRoot`
+ *  this will allow us to more easily manage symlinks for local development
+ *  using unpublished `quire-11ty` code.
+ *  @example
+ *  ```sh
+ *  blargh/
+ *    .git/
+ *    .gitignore
+ *    .node-version
+ *    .quire-version
+ *    11ty@ --> /Users/mph/Code/Getty/quire/packages/11ty
+ *    content/
+ *    CHANGELOG.md
+ *    LICENSE
+ *    README.md
+ *    package.json
+ *    package-lock.json
+ *  ```
+ *  Installing to a directory will allow more cleanly `eject` and `uneject`
+ *  using a symlink or single directory `rm -rf`.
+ *  Should the `11ty` directory be a dot directory to hide the complexity from
+ *  users or should it be visible to be more explicit when project is ejected?
  */
-export const eleventyRoot = hasEleventyConfig(projectRoot)
-  ? projectRoot
-  : fs.realpathSync(libQuirePath)
+const getEleventyRoot = () => {
+  // try {
+  //   return fs.readdirSync(projectRoot).includes(eleventyConfig)
+  //     ? projectRoot
+  //     : fs.realpathSync(libQuirePath)
+  // } catch (error) {
+  //   throw new Error(`[CLI:11ty] Unable to read project directory for eleventy config ${error}`)
+  // }
+  return projectRoot
+}
+
+export const eleventyRoot = getEleventyRoot()
+
+const inputDir = path.join(projectRoot, 'content')
 
 export default {
   config: path.join(eleventyRoot, '.eleventy.js'),
+  epub: path.relative(eleventyRoot, path.join(projectRoot, '_epub')),
   input: path.relative(eleventyRoot, inputDir),
   output: path.relative(eleventyRoot, path.join(projectRoot, '_site')),
   data: path.relative(inputDir, path.join(eleventyRoot, '_computed')),

package/src/lib/epub/README.md

@@ -0,0 +1,7 @@
+## CLI lib/EPUB Module
+
+This module implements a façade for EPUB e-book file format generation libries. The module exports a single method that accepts a `lib` option and delegates to a façade for the specified EPUB library.
+
+### Epub.js Façade
+
+See the [`Epub.js` documentation](https://github.com/futurepress/epub.js).

package/src/lib/epub/epub.js

@@ -0,0 +1,9 @@
+// import epub from 'epubjs'
+
+/**
+ * A façade module for the EPUB.js library
+ * @see https://github.com/futurepress/epub.js
+ */
+export default async (input, output, options) => {
+  console.info('[CLI:lib/epubjs] integration with epub.js is not yet implemented.')
+}

package/src/lib/epub/index.js

@@ -0,0 +1,36 @@
+import { dynamicImport } from '#helpers/os-utils.js'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/**
+ * A façade delegation module for EPUB libraries
+ */
+export default async (lib = 'epubjs', options = {}) => {
+  let libName, libPath
+
+  switch (lib.toLowerCase()) {
+    case 'epubjs': {
+      libName = 'Epub.js'
+      libPath = path.join(__dirname, 'epub.js')
+      break
+    }
+    case 'pandoc': {
+      libName = 'Pandoc'
+      libPath = path.join(__dirname, 'pandoc.js')
+      break
+    }
+    default:
+      console.error(`[CLI:lib/pdf] Unrecognized EPUB library '${lib}'`)
+      return
+  }
+
+  const { default: epubLib } = await dynamicImport(libPath)
+
+  return async (input, output, options = {}) => {
+    console.info(`[CLI:lib/epub] generating EPUB using ${libName}`)
+    return await epubLib(input, output, options)
+  }
+}

package/src/lib/epub/pandoc.js

@@ -0,0 +1,42 @@
+import { execa } from 'execa'
+import fs from 'fs-extra'
+import path from 'node:path'
+import paths, { projectRoot } from '#lib/11ty/paths.js'
+import which from '#helpers/which.js'
+
+/**
+ * Filter directory entries for XHTML files
+ *
+ * @param    {fs.Dirent}  dirent  directory entry
+ * @return   {fs.Dirent}  XHTML entries
+ */
+const xhtmlFiles = (dirent) => {
+  const stats = fs.lstatSync(dirent)
+  const { ext } = path.parse(dirent)
+  return stats.isFile() && ext === '.xhtml'
+}
+
+/**
+ * A façade module for interacting with Pandoc CLI.
+ * @see https://pandoc.org/MANUAL.html#general-options
+ */
+export default async (input, output, options) => {
+  which('pandoc')
+
+  const inputs = fs.readdirSync(input)
+    .map((entry) => path.join(input, entry))
+    .filter(xhtmlFiles)
+
+  const cmdOptions = [
+    `--from=html-native_divs+native_spans`,
+    `--to=epub`,
+    `--output=${output}`,
+    // `--epub-metadata=${path.join(input, 'dc.xml')}`,
+    // `--epub-cover-image=${coverImage}`,
+    // `--template=${path.join(input, 'template.xhtml')}`,
+    `--css=${path.join(input, '_assets', 'epub.css')}`,
+    `--standalone`,
+  ]
+
+  await execa('pandoc', [...cmdOptions, ...inputs])
+}

package/src/lib/pdf/README.md

@@ -0,0 +1,12 @@
+## 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.
+
+### Paged.js Façade
+
+See the [`Paged.js` documentation](https://gitlab.coko.foundation/pagedjs/).
+
+### Prince XML Façade
+
+See the [Prince Command-line Reference](https://www.princexml.com/doc/command-line/).

package/src/lib/pdf/index.js

@@ -0,0 +1,38 @@
+import { dynamicImport } from '#helpers/os-utils.js'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/**
+ * A façade delegation module for PDF generation libraries
+ */
+export default async (lib = 'pagedjs', options = {}) => {
+  let libName, libPath
+
+  switch (lib.toLowerCase()) {
+    case 'paged':
+    case 'pagedjs': {
+      libName = 'Paged.js'
+      libPath = path.join(__dirname, 'paged.js')
+      break
+    }
+    case 'prince':
+    case 'princexml': {
+      libName = 'Prince'
+      libPath = path.join(__dirname, 'prince.js')
+      break
+    }
+    default:
+      console.error(`[CLI:lib/pdf] Unrecognized PDF library '${lib}'`)
+      return
+  }
+
+  const { default: pdfLib } = await dynamicImport(libPath)
+
+  return async (input, output, options = {}) => {
+    console.info(`[CLI:lib/pdf] generating PDF using ${libName}`)
+    return await pdfLib(input, output, options)
+  }
+}

package/src/lib/pdf/paged.js

@@ -0,0 +1,42 @@
+import Printer from 'pagedjs-cli'
+import fs from 'fs-extra'
+
+/**
+ * A façade module for interacting with Paged.js
+ * @see https://gitlab.coko.foundation/pagedjs/
+ */
+export default async (input, output, options = {}) => {
+  /**
+   * Configure the Paged.js Printer options
+   * @see https://gitlab.coko.foundation/pagedjs/pagedjs-cli/-/blob/main/src/cli.js
+   */
+  const printerOptions = {
+    allowLocal: true,
+    debug: options.debug || false,
+  }
+
+  const printer = new Printer(printerOptions)
+
+  /**
+   * Configure the Paged.js PDF options
+   * @see
+   *
+   * @todo verify options before setting them
+   * @todo catch errors thrown by the printer
+   */
+  const pdfOptions = {
+    outlineTags: options.outlineTags || ['h1'],
+  }
+
+  try {
+    console.info(`[CLI:lib/pdf/pagedjs] printing ${input}`)
+    const file = await printer.pdf(input, pdfOptions)
+      .catch((error) => console.error(error))
+
+    if (file && output) {
+      fs.writeFile(output, file, (error) => { if (error) throw error })
+    }
+  } catch (ERR_FILE_NOT_FOUND) {
+    console.error(`[CLI:lib/pdf/pagedjs] file not found ${input}`)
+  }
+}

package/src/lib/pdf/prince.js

@@ -0,0 +1,17 @@
+import { execa } from 'execa'
+import which from '#helpers/which.js'
+
+/**
+ * A façade module for interacting with the Prince CLI.
+ * @see https://www.princexml.com/doc/command-line/
+ */
+export default async (input, output, options = {}) => {
+  which('prince')
+
+  const cmdOptions = [
+    `--output=${output}`,
+  ]
+
+  const { stderror, stdout } = await execa('prince', [...cmdOptions, input])
+  return { stderror, stdout }
+}

package/src/main.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander'
+import { Argument, Command, Option } from 'commander'
 import commands from './commands/index.js'
 import packageConfig from '../package.json' assert { type: 'json' }
 
@@ -37,9 +37,15 @@ commands.forEach((command) => {
     aliases.forEach((alias) => subCommand.alias(alias))
   }
 
+  /**
+   * @see https://github.com/tj/commander.js#more-configuration-1
+   */
   if (Array.isArray(args)) {
-    args.forEach(([ arg, value, callback ]) => {
-      subCommand.argument(arg, value, callback)
+    args.forEach(([ name, description, configuration = {} ]) => {
+      const argument = new Argument(name, description)
+      if (configuration.choices) argument.choices(configuration.choices)
+      if (configuration.default) argument.default(configuration.default)
+      subCommand.addArgument(argument)
     })
   }
 
@@ -47,16 +53,16 @@ commands.forEach((command) => {
    * @see https://github.com/tj/commander.js/#options
    */
   if (Array.isArray(options)) {
-    options.forEach((option) => {
-      if (Array.isArray(option)) {
+    options.forEach((entry) => {
+      if (Array.isArray(entry)) {
         // ensure we can join the first two attributes as the option name
         // when only the short or the long flag is defined in the array
-        if (option[0].startsWith('--')) option.unshift('\u0020'.repeat(4))
-        if (option[0].startsWith('-') && !option[1].startsWith('--')) {
-          option.splice(1, 0, '')
+        if (entry[0].startsWith('--')) entry.unshift('\u0020'.repeat(4))
+        if (entry[0].startsWith('-') && !entry[1].startsWith('--')) {
+          entry.splice(1, 0, '')
         }
         // assign attribute names to the array of option attributes
-        const [ short, long, description, defaultValue ] = option
+        const [ short, long, description, defaultValue ] = entry
         // join short and long flags as the option name attribute
         const name = /^-\w/.test(short) && /^--\w/.test(long)
           ? [short, long].join(', ')
@@ -64,11 +70,13 @@ commands.forEach((command) => {
         subCommand.option(name, description, defaultValue)
       } else {
         /**
-         * @todo allow option attributes to be defined using an object
+         * @todo allow options to be defined by a configuration object
          * @see https://github.com/tj/commander.js/#more-configuration
          */
-        // const option = new Option(name, description, defaultValue)
-        // if (attributes.blarg) option.blagh(attributes.blarg)
+        // const option = new Option(name, description)
+        // for (const property of configuration) {
+        //   option[property](configuration[property])
+        // }
         // subCommand.addOption(option)
         console.error('@TODO please use an array to define option attributes')
       }