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

package/src/main.js

@@ -1,10 +1,50 @@
-import { Argument, Command, Option } from 'commander'
+import { Command, Argument, Option } from 'commander'
+import {
+  arrayToArgument,
+  arrayToOption,
+  quietOption,
+  verboseOption,
+  debugOption
+} from '#lib/commander/index.js'
 import commands from '#src/commands/index.js'
 import config from '#lib/conf/config.js'
+import { handleError } from '#lib/error/handler.js'
+import { docsUrl, DOCS_BASE } from '#helpers/docs-url.js'
 import packageConfig from '#src/packageConfig.js'
+import { enableDebug } from '#lib/logger/debug.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
+
+  Set defaults: quire settings set verbose true
+
+Environment Variables:
+  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
+  $ DEBUG=quire:* quire pdf      Generate PDF with debug output
+`
+
 /**
  * Quire CLI implements the command pattern.
  *
@@ -17,29 +57,67 @@ const program = new Command()
 program
   .name('quire')
   .description('Quire command-line interface')
-  .version(version,  '-v, --version', 'output quire version number')
+  .version(version, '-V, --version', 'output quire version number')
+  .addOption(arrayToOption(quietOption))
+  .addOption(arrayToOption(verboseOption))
+  .addOption(arrayToOption(debugOption))
+  .addHelpText('after', mainHelpText)
   .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)
+    },
   })
 
 /**
- * Register each command as a subcommand of this program
+ * Handle global options before any command runs
  *
- * @todo refactor command definition to allow for per-command custom help text
+ * 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)
+ *
+ * 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()
+
+  // --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:*')
+  }
+})
+
+/**
+ * Register each command as a subcommand of this program
  * @see https://github.com/tj/commander.js?tab=readme-ov-file#automated-help
  */
 commands.forEach((command) => {
-  const { action, alias, aliases, args, description, name, options } = command
+  const { action, alias, aliases, args, description, docsLink, helpText, hidden, name, options, summary } = command
 
   const subCommand = program
-    .command(name)
+    .command(name, { hidden })
     .description(description)
+    .summary(summary || description)
     .addHelpCommand()
     .showHelpAfterError()
 
-  if (alias instanceof String) {
+  // 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') {
     subCommand.alias(alias)
   }
 
@@ -48,71 +126,80 @@ commands.forEach((command) => {
   }
 
   /**
-   * @see https://github.com/tj/commander.js#more-configuration-1
+   * Register arguments with the subcommand
    */
   if (Array.isArray(args)) {
-    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)
+    args.forEach((entry) => {
+      const argument = entry instanceof Argument ? entry : arrayToArgument(entry)
       subCommand.addArgument(argument)
     })
   }
 
   /**
-   * @see https://github.com/tj/commander.js/#options
+   * Register options with the subcommand
    */
   if (Array.isArray(options)) {
     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 (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')
-      }
+      const option = entry instanceof Option ? entry : arrayToOption(entry)
+      subCommand.addOption(option)
     })
   }
 
+  /**
+   * 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', (thisCommand, actionCommand) => {
-      command.postAction.call(command, thisCommand, actionCommand)
+    subCommand.hook('postAction', async (thisCommand, actionCommand) => {
+      try {
+        await command.postAction.call(command, thisCommand, actionCommand)
+      } catch (error) {
+        const { debug } = program.opts()
+        handleError(error, { debug })
+      }
     })
   }
 
+  /**
+   * 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', (thisCommand, actionCommand) => {
-      command.preAction.call(command, thisCommand, actionCommand)
+    subCommand.hook('preAction', async (thisCommand, actionCommand) => {
+      try {
+        await command.preAction.call(command, thisCommand, actionCommand)
+      } catch (error) {
+        const { debug } = program.opts()
+        handleError(error, { debug })
+      }
     })
   }
 
+  /**
+   * 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', (thisCommand, theSubcommand) => {
-      command.preSubcommand.call(command, thisCommand, theSubcommand)
+    subCommand.hook('preSubcommand', async (thisCommand, theSubcommand) => {
+      try {
+        await command.preSubcommand.call(command, thisCommand, theSubcommand)
+      } catch (error) {
+        const { debug } = program.opts()
+        handleError(error, { debug })
+      }
     })
   }
 
-  // subCommand.action((args) => action.apply(command, args))
-  subCommand.action(action)
+  // Wrap action in centralized error handler
+  // Using apply() preserves `this` context for `this.debug` and `this.logger`
+  subCommand.action(async (...args) => {
+    try {
+      await action.apply(command, args)
+    } catch (error) {
+      const { debug } = program.opts()
+      handleError(error, { debug })
+    }
+  })
 
   /**
    * Inject the CLI configuration into commands

package/src/main.spec.js

@@ -0,0 +1,61 @@
+import { Command } from 'commander'
+import program from './main.js'
+import test from 'ava'
+
+/**
+ * Main Program Unit Tests
+ *
+ * Tests the CLI program configuration and setup.
+ * Command registration is tested indirectly through command spec files.
+ */
+
+test('program exports a Commander.js Command instance', (t) => {
+  t.truthy(program)
+  t.true(program instanceof Command, 'program should be a Commander.js Command')
+})
+
+test('program has correct name and description', (t) => {
+  t.is(program.name(), 'quire')
+  t.truthy(program.description(), 'program should have a description')
+  t.regex(program.description(), /quire/i, 'description should mention Quire')
+})
+
+test('program has version option with correct flags', (t) => {
+  // Commander stores _version and the version option in the options array
+  t.truthy(program._version, 'program should have version set')
+
+  // Find the version option
+  const versionOption = program.options.find((opt) => opt.long === '--version')
+  t.truthy(versionOption, '--version option should exist')
+  t.is(versionOption.short, '-v', 'version option should have -v short flag')
+  t.truthy(versionOption.description, 'version option should have description')
+})
+
+test('program help is configured with correct width', (t) => {
+  // Access the help configuration
+  const helpConfig = program._helpConfiguration
+
+  t.truthy(helpConfig, 'help configuration should exist')
+  t.is(helpConfig.helpWidth, 80, 'help width should be 80')
+})
+
+test('program registers commands from commands/index.js', (t) => {
+  // Verify commands are registered
+  t.true(program.commands.length > 0, 'program should have registered commands')
+
+  // Verify expected commands exist
+  const commandNames = program.commands.map((cmd) => cmd.name())
+  t.true(commandNames.includes('build'), 'build command should be registered')
+  t.true(commandNames.includes('new'), 'new command should be registered')
+  t.true(commandNames.includes('preview'), 'preview command should be registered')
+  t.true(commandNames.includes('info'), 'info command should be registered')
+})
+
+test('program injects config into subcommands', (t) => {
+  // Pick a registered command and verify dependency injection of the config
+  const buildCommand = program.commands.find((cmd) => cmd.name() === 'build')
+
+  t.truthy(buildCommand, 'build command should exist')
+  t.truthy(buildCommand.config, 'subcommand should have config injected')
+  t.is(typeof buildCommand.config.get, 'function', 'config should have get method')
+})

package/src/main.test.js

@@ -0,0 +1,347 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+import QuireError from '#src/errors/quire-error.js'
+
+/**
+ * Main Program Integration Tests
+ *
+ * Tests the runtime behavior of the CLI program, including
+ * error handling in command lifecycle hooks.
+ */
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+/**
+ * Helper to create a mock command with configurable hooks
+ */
+function createMockCommand(overrides = {}) {
+  return {
+    name: 'mock-command',
+    description: 'Mock command for integration tests',
+    summary: 'mocked command',
+    action: async () => {},
+    ...overrides
+  }
+}
+
+test('preAction hook errors are passed to handleError', async (t) => {
+  const { sandbox } = t.context
+
+  const testError = new QuireError('Test preAction error', {
+    code: 'TEST_ERROR',
+    exitCode: 42
+  })
+
+  const mockHandleError = sandbox.stub()
+
+  const mockCommand = createMockCommand({
+    preAction: () => {
+      throw testError
+    }
+  })
+
+  // Use esmock to inject our mock command and handleError
+  await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: mockHandleError
+    }
+  })
+
+  // The program is created at import time, so we need to trigger the hook
+  // by parsing a command. Import the mocked program.
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: mockHandleError
+    }
+  })
+
+  // Configure Commander to not exit on error during tests
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  // Parse the test command to trigger preAction
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Commander may throw after our error is handled
+  }
+
+  t.true(mockHandleError.called, 'handleError should be called for preAction errors')
+  t.is(mockHandleError.firstCall.args[0], testError, 'handleError should receive the thrown error')
+})
+
+test('postAction hook errors are passed to handleError', async (t) => {
+  const { sandbox } = t.context
+
+  const testError = new QuireError('Test postAction error', {
+    code: 'TEST_POST_ERROR',
+    exitCode: 43
+  })
+
+  const mockHandleError = sandbox.stub()
+
+  const mockCommand = createMockCommand({
+    action: async () => {
+      // Action succeeds
+    },
+    postAction: () => {
+      throw testError
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: mockHandleError
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Commander may throw after our error is handled
+  }
+
+  t.true(mockHandleError.called, 'handleError should be called for postAction errors')
+  t.is(mockHandleError.firstCall.args[0], testError, 'handleError should receive the thrown error')
+})
+
+test('action errors are passed to handleError', async (t) => {
+  const { sandbox } = t.context
+
+  const testError = new QuireError('Test action error', {
+    code: 'TEST_ACTION_ERROR',
+    exitCode: 44
+  })
+
+  const mockHandleError = sandbox.stub()
+
+  const mockCommand = createMockCommand({
+    action: async () => {
+      throw testError
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: mockHandleError
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Commander may throw after our error is handled
+  }
+
+  t.true(mockHandleError.called, 'handleError should be called for action errors')
+  t.is(mockHandleError.firstCall.args[0], testError, 'handleError should receive the thrown error')
+})
+
+test('preAction hook preserves this context for command methods', async (t) => {
+  const { sandbox } = t.context
+
+  const debugSpy = sandbox.spy()
+  let thisContext = null
+
+  const mockCommand = createMockCommand({
+    debug: debugSpy,
+    preAction: function () {
+      thisContext = this
+      this.debug('preAction called')
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: sandbox.stub()
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Ignore Commander errors
+  }
+
+  t.is(thisContext, mockCommand, 'this should be bound to the command instance')
+  t.true(debugSpy.called, 'this.debug should be callable')
+})
+
+test('postAction hook preserves this context for command methods', async (t) => {
+  const { sandbox } = t.context
+
+  const debugSpy = sandbox.spy()
+  let thisContext = null
+
+  const mockCommand = createMockCommand({
+    debug: debugSpy,
+    action: async () => {},
+    postAction: function () {
+      thisContext = this
+      this.debug('postAction called')
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: sandbox.stub()
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Ignore Commander errors
+  }
+
+  t.is(thisContext, mockCommand, 'this should be bound to the command instance')
+  t.true(debugSpy.called, 'this.debug should be callable')
+})
+
+test('async preAction hooks are awaited before action runs', async (t) => {
+  const { sandbox } = t.context
+
+  const callOrder = []
+
+  const mockCommand = createMockCommand({
+    preAction: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      callOrder.push('preAction')
+    },
+    action: async () => {
+      callOrder.push('action')
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: sandbox.stub()
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Ignore Commander errors
+  }
+
+  t.deepEqual(callOrder, ['preAction', 'action'], 'preAction should complete before action starts')
+})
+
+test('async postAction hooks are awaited after action completes', async (t) => {
+  const { sandbox } = t.context
+
+  const callOrder = []
+
+  const mockCommand = createMockCommand({
+    action: async () => {
+      callOrder.push('action')
+    },
+    postAction: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      callOrder.push('postAction')
+    }
+  })
+
+  const { default: program } = await esmock('./main.js', {
+    '#src/commands/index.js': {
+      default: [mockCommand]
+    },
+    '#lib/error/handler.js': {
+      handleError: sandbox.stub()
+    }
+  })
+
+  program.exitOverride()
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {}
+  })
+
+  try {
+    await program.parseAsync(['node', 'quire', 'mock-command'])
+  } catch {
+    // Ignore Commander errors
+  }
+
+  t.deepEqual(callOrder, ['action', 'postAction'], 'postAction should run after action completes')
+})
+
+/**
+ * Nota bene: preSubcommand hook tests are skipped because:
+ * 1. `main` does not process a `subcommands` array in command definitions
+ * 2. No commands in the CLI currently use nested subcommands
+ * 3. The wrapped error handler pattern is identical to preAction/postAction
+ *
+ * @todo When nested subcommands are added, these tests should be implemented.
+ */
+test.skip('preSubcommand hook errors are passed to handleError', async (t) => {
+  // Requires main.js to support nested subcommands in command definitions
+  t.pass()
+})
+
+test.skip('preSubcommand hook preserves this context for command methods', async (t) => {
+  // Requires main.js to support nested subcommands in command definitions
+  t.pass()
+})

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 { projectRoot  } from '#lib/11ty/index.js'
+import { paths as eleventyPaths } from '#lib/11ty/index.js'
 
 const IMAGE_KEYS = new Set(['src', 'image', 'logo'])
 
@@ -37,6 +37,7 @@ 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)