@thegetty/quire-cli 1.0.0-rc.44 → 1.0.0-rc.46

package/src/main.js

@@ -1,87 +1,14 @@
-import { Command, Argument, Option } from 'commander'
-import {
-  arrayToArgument,
-  arrayToOption,
-  colorOption,
-  noColorOption,
-  quietOption,
-  verboseOption,
-  debugOption,
-  reducedMotionOption,
-} from '#lib/commander/index.js'
+import { Argument, Command, Option } from 'commander'
 import commands from '#src/commands/index.js'
 import config from '#lib/conf/config.js'
-import { handleError } from '#lib/error/handler.js'
-import reporter from '#lib/reporter/index.js'
-import { docsUrl, DOCS_BASE } from '#helpers/docs-url.js'
 import packageConfig from '#src/packageConfig.js'
-import { enableDebug } from '#lib/logger/debug.js'
-import { formatPrefix } from '#lib/logger/index.js'
 
 const { version } = packageConfig
 
-const mainHelpText = `
-Docs: ${DOCS_BASE}
-
-Common Workflows:
-  New project     quire new my-book && cd my-book && quire preview
-  Build for web   quire build
-  Generate PDF    quire pdf --build
-  Generate EPUB   quire epub --build
-
-  Run 'quire help workflows' for detailed workflow documentation.
-
-Output Modes:
-  -q, --quiet          Suppress progress output (for CI/scripts)
-  -v, --verbose        Show detailed progress (paths, timing, steps)
-  --debug              Enable debug output for developers/troubleshooting
-  --reduced-motion      Disable spinner animation and line overwriting
-
-  Set defaults: quire settings set verbose true
-
-Accessibility:
-  --reduced-motion disables animated spinners and line overwriting.
-  Each stage prints on a new line as static text, making output
-  compatible with screen readers and reduced-motion preferences.
-
-  Set default: quire settings set reducedMotion true
-
-Color Output:
-  --no-color       Disable colored output
-  --color          Force colored output (overrides NO_COLOR env var)
-
-  Respects NO_COLOR environment variable (https://no-color.org/)
-  Set default: quire settings set logUseColor false
-
-Paging:
-  --no-pager             Disable paging for long output
-  NO_PAGER=1             Disable paging via environment variable
-  PAGER=cat              Traditional Unix alternative (passes output through)
-
-Environment Variables:
-  REDUCED_MOTION          Disable spinner animation and line overwriting
-  NO_COLOR               Disable colored output (https://no-color.org/)
-  NO_PAGER=1             Disable paging for long output
-  PAGER=<program>        Set pager program (default: less). Use PAGER=cat to disable
-  DEBUG=quire:*          Enable debug output for all modules
-  DEBUG=quire:lib:pdf    Enable debug output for PDF module only
-  DEBUG=quire:lib:*      Enable debug output for all lib modules
-
-Examples:
-  $ quire build                  Build the publication
-  $ quire build --verbose        Build with detailed progress
-  $ quire build --debug          Build with debug output
-  $ quire build --reduced-motion  Build without animated spinners
-  $ REDUCED_MOTION=1 quire build  Build without animated spinners
-  $ quire build --no-color       Build without colored output
-  $ NO_COLOR=1 quire build       Build without colored output
-  $ DEBUG=quire:* quire pdf      Generate PDF with debug output
-`
-
 /**
  * Quire CLI implements the command pattern.
  *
- * The \`main\` module acts as the _receiver_, parsing input from the client,
+ * The `main` module acts as the _receiver_, parsing input from the client,
  * calling the appropriate command module(s), managing messages between modules,
  * and sending formatted messages to the client for display.
  */
@@ -90,107 +17,29 @@ const program = new Command()
 program
   .name('quire')
   .description('Quire command-line interface')
-  .version(version, '-V, --version', 'output quire version number')
-  .addOption(arrayToOption(colorOption))
-  .addOption(arrayToOption(noColorOption))
-  .addOption(arrayToOption(quietOption))
-  .addOption(arrayToOption(verboseOption))
-  .addOption(arrayToOption(debugOption))
-  .addOption(arrayToOption(reducedMotionOption))
-  .option('--no-pager', 'disable paging for long output')
-  .addHelpText('after', mainHelpText)
+  .version(version,  '-v, --version', 'output quire version number')
   .configureHelp({
     helpWidth: 80,
     sortOptions: false,
     sortSubcommands: false,
-    styleOptionTerm: (term) => {
-      // Add spacing to long-only options to align with short-flag options
-      return /^-\w/.test(term) ? term : term.padStart(term.length + 4)
-    },
   })
 
-/**
- * Handle global options before any command runs
- *
- * Output mode semantics:
- * - --quiet: Suppress progress spinners (for CI/scripts)
- * - --verbose: Show detailed progress (paths, timing, steps)
- * - --debug: Enable DEBUG namespace + tool debug modes (for developers)
- * - --reduced-motion: Disable animated spinners, use static text on new lines
- * - --no-color: Disable colored output (sets NO_COLOR env var)
- * - --color: Force colored output (overrides NO_COLOR env var)
- *
- * These global options are passed through to commands via opts()
- * and should be merged with command-level options.
- */
-program.hook('preAction', (thisCommand) => {
-  const opts = thisCommand.opts()
-
-  // Handle --no-color / --color flag
-  // Sets NO_COLOR env var for chalk, ora, and logger to read
-  if (opts.color === false) {
-    process.env.NO_COLOR = '1'
-    delete process.env.FORCE_COLOR
-  } else if (opts.color === true) {
-    delete process.env.NO_COLOR
-    process.env.FORCE_COLOR = '1'
-  }
-
-  // --debug or config.debug enables the quire:* DEBUG namespace for internal logging
-  // CLI flag takes precedence, then config setting
-  if (opts.debug ?? config.get('debug')) {
-    enableDebug('quire:*')
-  }
-
-  // --reduced-motion sets REDUCED_MOTION env var for reporter to read
-  // CLI flag takes precedence over env var and config setting
-  if (opts.reducedMotion) {
-    process.env.REDUCED_MOTION = '1'
-  }
-
-  // --no-pager sets pager to false; propagate via env var for pager utility
-  if (opts.pager === false) {
-    process.env.NO_PAGER = '1'
-  }
-
-  // Log prefix and level label visibility for quire-11ty's chalk logger
-  process.env.QUIRE_LOG_PREFIX = formatPrefix(config.get('logPrefixStyle'), config.get('logPrefix'))
-  process.env.QUIRE_LOG_SHOW_LEVEL = String(config.get('logShowLevel'))
-})
-
-/**
- * Stop the reporter after every command to clear any active setInterval timers
- * (e.g. elapsed time display) that would otherwise keep the event loop alive.
- */
-program.hook('postAction', () => {
-  reporter.stop()
-})
-
 /**
  * Register each command as a subcommand of this program
+ *
+ * @todo refactor command definition to allow for per-command custom help text
  * @see https://github.com/tj/commander.js?tab=readme-ov-file#automated-help
  */
 commands.forEach((command) => {
-  const { action, alias, aliases, args, description, docsLink, helpText, hidden, name, options, summary } = command
+  const { action, alias, aliases, args, description, name, options } = command
 
   const subCommand = program
-    .command(name, { hidden })
+    .command(name)
     .description(description)
-    .summary(summary || description)
     .addHelpCommand()
     .showHelpAfterError()
 
-  // Append docs link and/or custom help text after built-in help
-  const customHelpText = [
-    docsLink && `Docs: ${docsUrl(docsLink)}`,
-    helpText?.trim()
-  ].filter(Boolean).join('\n\n')
-
-  if (customHelpText) {
-    subCommand.addHelpText('after', '\n' + customHelpText)
-  }
-
-  if (typeof alias === 'string') {
+  if (alias instanceof String) {
     subCommand.alias(alias)
   }
 
@@ -199,93 +48,71 @@ commands.forEach((command) => {
   }
 
   /**
-   * Register arguments with the subcommand
+   * @see https://github.com/tj/commander.js#more-configuration-1
    */
   if (Array.isArray(args)) {
-    args.forEach((entry) => {
-      const argument = entry instanceof Argument ? entry : arrayToArgument(entry)
+    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)
     })
   }
 
   /**
-   * Register options with the subcommand
+   * @see https://github.com/tj/commander.js/#options
    */
   if (Array.isArray(options)) {
     options.forEach((entry) => {
-      const option = entry instanceof Option ? entry : arrayToOption(entry)
-      subCommand.addOption(option)
+      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 (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 ] = entry
+        // join short and long flags as the option name attribute
+        const name = /^-\w/.test(short) && /^--\w/.test(long)
+          ? [short, long].join(', ')
+          : [short, long].join('')
+        subCommand.option(name, description, defaultValue)
+      } else {
+        /**
+         * @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)
+        // for (const property of configuration) {
+        //   option[property](configuration[property])
+        // }
+        // subCommand.addOption(option)
+        console.error('@TODO please use an array to define option attributes')
+      }
     })
   }
 
-  /**
-   * Command lifecycle hook: called after action handler and nested subcommands
-   * @see https://github.com/tj/commander.js?tab=readme-ov-file#life-cycle-hooks
-   */
   if (command.postAction) {
-    subCommand.hook('postAction', async (thisCommand, actionCommand) => {
-      try {
-        await command.postAction.call(command, thisCommand, actionCommand)
-      } catch (error) {
-        const { debug } = program.opts()
-        handleError(error, { debug })
-      }
+    subCommand.hook('postAction', (thisCommand, actionCommand) => {
+      command.postAction.call(command, thisCommand, actionCommand)
     })
   }
 
-  /**
-   * Command lifecycle hook: called before action handler and nested subcommands
-   * @see https://github.com/tj/commander.js?tab=readme-ov-file#life-cycle-hooks
-   */
   if (command.preAction) {
-    subCommand.hook('preAction', async (thisCommand, actionCommand) => {
-      try {
-        await command.preAction.call(command, thisCommand, actionCommand)
-      } catch (error) {
-        const { debug } = program.opts()
-        handleError(error, { debug })
-      }
+    subCommand.hook('preAction', (thisCommand, actionCommand) => {
+      command.preAction.call(command, thisCommand, actionCommand)
     })
   }
 
-  /**
-   * Subcommand lifecyle hook: called before parsing direct subcommand
-   * @see https://github.com/tj/commander.js?tab=readme-ov-file#life-cycle-hooks
-   */
   if (command.preSubcommand) {
-    subCommand.hook('preSubcommand', async (thisCommand, theSubcommand) => {
-      try {
-        await command.preSubcommand.call(command, thisCommand, theSubcommand)
-      } catch (error) {
-        const { debug } = program.opts()
-        handleError(error, { debug })
-      }
+    subCommand.hook('preSubcommand', (thisCommand, theSubcommand) => {
+      command.preSubcommand.call(command, thisCommand, theSubcommand)
     })
   }
 
-  /**
-   * Wrap action in centralized error handler.
-   * Using apply() preserves `this` context for `this.debug` and `this.logger`.
-   *
-   * Nota bene: Commander passes subcommand-local opts as the options argument,
-   * but global options (--verbose, --quiet, --debug) defined on the parent
-   * program are only available via optsWithGlobals(). We replace the options
-   * argument with the merged set so action handlers see all options uniformly.
-   */
-  subCommand.action(async (...args) => {
-    try {
-      // Commander Command instance is the last element in args array
-      // @see https://github.com/tj/commander.js#action-handler
-      const cmd = args[args.length - 1]
-      const mergedOpts = cmd.optsWithGlobals()
-      args[args.length - 2] = mergedOpts
-      await action.apply(command, args)
-    } catch (error) {
-      reporter.stop()
-      const { debug } = program.opts()
-      handleError(error, { debug })
-    }
-  })
+  // subCommand.action((args) => action.apply(command, args))
+  subCommand.action(action)
 
   /**
    * Inject the CLI configuration into commands

package/src/packageConfig.js

@@ -1,7 +1,6 @@
 import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readPackageUpSync } from 'read-package-up'
-import which from '#helpers/which.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -13,20 +12,4 @@ const __dirname = dirname(__filename)
  */
 const { packageJson } = readPackageUpSync({ cwd: __dirname, normalize: true })
 
-/**
- * Resolve the full filesystem path to the quire CLI executable
- *
- * Uses the `which` helper to find the first `quire` executable in PATH.
- * Returns null if the executable is not found.
- *
- * @returns {string|null} Absolute path to the quire executable, or null
- */
-export function binPath() {
-  try {
-    return which('quire')
-  } catch {
-    return null
-  }
-}
-
 export default packageJson

package/src/validators/utils.js

@@ -2,7 +2,7 @@ import YamlDuplicateIdError from '../errors/validation/yaml-duplicate-error.js'
 import { fileURLToPath } from 'url'
 import fs from 'node:fs'
 import path from 'path'
-import { paths as eleventyPaths } from '#lib/11ty/index.js'
+import { projectRoot  } from '#lib/11ty/index.js'
 
 const IMAGE_KEYS = new Set(['src', 'image', 'logo'])
 
@@ -37,7 +37,6 @@ function collectImagePaths(node, paths=[]) {
 function validateImage(label, src) {
   if(!src) return
 
-  const projectRoot = eleventyPaths.getProjectRoot()
   let assetPath = ''
   if(src.endsWith('.html')) {
     assetPath = path.join(projectRoot, 'content', '_assets', src)

package/schemas/config.schema.json

@@ -1,194 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Quire Config Schema",
-  "type": "object",
-  "properties": {
-    "accordion": {
-      "type": "object",
-      "properties": {
-        "controls": {
-          "type": "string",
-          "enum": ["arrow", "plus-minus"]
-        },
-        "copyButton": {
-          "type": "object",
-          "properties": {
-            "ariaLabel": { "type": "string" },
-            "successText": { "type": "string" },
-            "symbol": { "type": "string" }
-          },
-          "required": ["ariaLabel", "successText", "symbol"]
-        },
-        "globalControls": {
-          "type": "object",
-          "properties": {
-            "collapseText": { "type": "string" },
-            "expandText": { "type": "string" }
-          },
-          "required": ["collapseText", "expandText"]
-        }
-      },
-      "required": ["controls", "copyButton", "globalControls"]
-    },
-    "analytics": {
-      "type": "object",
-      "properties": {
-        "googleId": { "type": "string" }
-      },
-      "required": ["googleId"]
-    },
-    "bylineFormat": {
-      "oneOf": [
-        { "type": "string", "enum": ["name", "name-title"] },
-        { "type": "boolean", "enum": [false] }
-      ]
-    },
-    "bibliography": {
-      "type": "object",
-      "properties": {
-        "displayOnPage": { "type": "boolean" },
-        "displayShort": { "type": "boolean" },
-        "heading": { "type": "string" }
-      },
-      "required": ["displayOnPage", "displayShort", "heading"]
-    },
-    "citations": {
-      "type": "object",
-      "properties": {
-        "divider": { "type": "string" },
-        "popupStyle": {
-          "type": "string",
-          "enum": ["text", "icon"]
-        }
-      },
-      "required": ["divider", "popupStyle"]
-    },
-    "entryPage": {
-      "type": "object",
-      "properties": {
-        "sideBySide": { "type": "boolean" },
-        "objectLinkText": { "type": "string" }
-      },
-      "required": ["sideBySide", "objectLinkText"]
-    },
-    "epub": {
-      "type": "object",
-      "properties": {
-        "defaultCoverImage": { "type": "string" },
-        "outputDir": { "type": "string" }
-      },
-      "required": ["defaultCoverImage", "outputDir"]
-    },
-    "footnotes": {
-      "type": "object",
-      "properties": {
-        "backlinkSymbol": { "type": "string" }
-      },
-      "required": ["backlinkSymbol"]
-    },
-    "figures": {
-      "type": "object",
-      "properties": {
-        "assetDir": { "type": "string" },
-        "enableModal": { "type": "boolean" },
-        "imageDir": { "type": "string" }
-      },
-      "required": ["assetDir", "enableModal", "imageDir"]
-    },
-    "licenseIcons": { "type": "boolean" },
-    "localization": {
-      "type": "object",
-      "properties": {
-        "defaultLocale": { "type": "string" }
-      },
-      "required": ["defaultLocale"]
-    },
-    "menuType": {
-      "type": "string",
-      "enum": ["full", "brief"]
-    },
-    "navigation": {
-      "type": "object",
-      "properties": {
-        "nextButtonText": { "type": "string" },
-        "prevButtonText": { "type": "string" }
-      },
-      "required": ["nextButtonText", "prevButtonText"]
-    },
-    "pageTitle": {
-      "type": "object",
-      "properties": {
-        "labelDivider": { "type": "string" }
-      },
-      "required": ["labelDivider"]
-    },
-    "pdf": {
-      "type": "object",
-      "properties": {
-        "filename": { "type": "string" },
-        "outputDir": { "type": "string" },
-        "pagePDF": {
-          "type": "object",
-          "properties": {
-            "accessLinks": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "header": { "type": "boolean" },
-                  "footer": { "type": "boolean" },
-                  "label": { "type": "string" }
-                }
-              }
-            },
-            "coverPage": { "type": "boolean" },
-            "output": { "type": "boolean" }
-          },
-          "required": ["accessLinks", "coverPage", "output"]
-        },
-        "publicationPDF": {
-          "type": "object",
-          "properties": {
-            "output": { "type": "boolean" }
-          },
-          "required": ["output"]
-        }
-      },
-      "required": ["filename", "outputDir", "pagePDF", "publicationPDF"]
-    },
-    "ref": {
-      "type": "object",
-      "properties": {
-        "sequenceTransition": { "type": "number" }
-      },
-      "required": ["sequenceTransition"]
-    },
-    "searchEnabled": { "type": "boolean" },
-    "tableOfContents": {
-      "type": "object",
-      "properties": {
-        "contributorDivider": { "type": "string" }
-      },
-      "required": ["contributorDivider"]
-    }
-  },
-  "required": [
-    "accordion",
-    "bylineFormat",
-    "bibliography",
-    "citations",
-    "entryPage",
-    "epub",
-    "footnotes",
-    "figures",
-    "licenseIcons",
-    "localization",
-    "menuType",
-    "navigation",
-    "pageTitle",
-    "pdf",
-    "ref",
-    "searchEnabled",
-    "tableOfContents"
-  ]
-}

package/schemas/figures.schema.json

@@ -1,56 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Figures YAML Schema",
-  "type": "object",
-  "properties": {
-    "figure_list": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id"],
-        "properties": {
-          "id": { "type": "string" },
-          "label": { "type": "string" },
-          "src": { "type": "string" },
-          "caption": { "type": "string" },
-          "credit": { "type": ["string", "null"] },
-          "alt": { "type": ["string", "null"] },
-          "poster": { "type": "string" },
-          "download": { "type": "boolean" },
-          "zoom": { "type": "boolean" },
-          "media_id": { "type": "string" },
-          "media_type": {
-            "type": "string",
-            "enum": ["youtube", "soundcloud", "table"]
-          },
-          "annotations": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["input", "items"],
-              "properties": {
-                "input": {
-                  "type": "string",
-                  "enum": ["radio", "checkbox"]
-                },
-                "items": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "src": { "type": "string" },
-                      "label": { "type": "string" },
-                      "selected": { "type": "boolean" }
-                    },
-                    "required": ["src"]
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  },
-  "required": ["figure_list"]
-}

package/schemas/layout.schema.json

@@ -1,5 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Layout Schema",
-  "type": "string"
-}