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

package/src/lib/commander/index.js

@@ -1,103 +0,0 @@
-/**
- * Commander.js utilities
- *
- * Provides helper functions for converting array-based definitions
- * to Commander.js Argument and Option objects, plus shared option definitions.
- *
- * @module lib/commander
- */
-import { Argument, Option } from 'commander'
-
-// Re-export shared option definitions
-export {
-  colorOption,
-  noColorOption,
-  quietOption,
-  verboseOption,
-  debugOption,
-  reducedMotionOption,
-  outputModeOptions,
-  outputModeHelpText,
-  withOutputModes,
-} from './options.js'
-
-/**
- * Convert array argument definition to Argument object
- *
- * @param {Array} entry - Argument definition array [name, description, { choices, default }]
- * @returns {Argument} Commander Argument object
- * @see https://github.com/tj/commander.js#more-configuration-1
- *
- * @example
- * // Required argument
- * arrayToArgument(['<version>', 'quire-11ty version to use'])
- *
- * @example
- * // Optional argument with default
- * arrayToArgument(['[starter]', 'starter template', { default: 'default' }])
- */
-export function arrayToArgument(entry) {
-  const [name, description, config = {}] = entry
-  const argument = new Argument(name, description)
-  if (config.choices) argument.choices(config.choices)
-  if (config.default) argument.default(config.default)
-  return argument
-}
-
-/**
- * Convert array option definition to Option object
- *
- * Supports two array formats:
- * - Separate flags: ['-s', '--long <value>', 'description', default, { choices, default }]
- * - Combined flags: ['--long <value>', 'description', default, { choices, default }]
- *
- * @param {Array} entry - Option definition array
- * @returns {Option} Commander Option object
- * @see https://github.com/tj/commander.js/#options
- * @see https://github.com/tj/commander.js/#more-configuration
- *
- * @example
- * // Long-only option
- * arrayToOption(['--debug', 'enable debug output'])
- *
- * @example
- * // Short and long flags
- * arrayToOption(['-v', '--verbose', 'enable verbose output'])
- *
- * @example
- * // Option with choices
- * arrayToOption(['--lib <module>', 'library to use', { choices: ['a', 'b'], default: 'a' }])
- */
-export function arrayToOption(entry) {
-  const lastElement = entry[entry.length - 1]
-  const configObj = typeof lastElement === 'object' && lastElement !== null ? lastElement : null
-
-  let flags, description, defaultValue
-  if (entry[0]?.startsWith('-') && entry[1]?.startsWith('--')) {
-    // Array has separate elements for short and long option flags
-    // @example ['-s', '--long <value>', 'desc', ...]
-    flags = `${entry[0]}, ${entry[1]}`
-    description = entry[2]
-    defaultValue = entry[3]
-  } else {
-    // Array has a single element with option flags
-    // @example ['--long <value>', 'desc', ...]
-    flags = entry[0]
-    description = entry[1]
-    defaultValue = entry[2]
-  }
-
-  const option = new Option(flags, description)
-
-  if (configObj) {
-    if (configObj.choices) option.choices(configObj.choices)
-    if (configObj.conflicts) option.conflicts(configObj.conflicts)
-    if (configObj.default !== undefined) option.default(configObj.default)
-    if (configObj.hidden) option.hideHelp()
-    if (configObj.implies) option.implies(configObj.implies)
-  } else if (defaultValue !== undefined) {
-    option.default(defaultValue)
-  }
-
-  return option
-}

package/src/lib/commander/index.test.js

@@ -1,86 +0,0 @@
-import test from 'ava'
-import { Argument, Option } from 'commander'
-import { arrayToArgument, arrayToOption } from './index.js'
-
-// ─────────────────────────────────────────────────────────────────────────────
-// arrayToArgument tests
-// ─────────────────────────────────────────────────────────────────────────────
-
-test('arrayToArgument creates Argument from basic array', (t) => {
-  const arg = arrayToArgument(['<version>', 'the version to use'])
-
-  t.true(arg instanceof Argument)
-  t.is(arg.name(), 'version')
-  t.is(arg.description, 'the version to use')
-  t.true(arg.required)
-})
-
-test('arrayToArgument creates optional Argument', (t) => {
-  const arg = arrayToArgument(['[starter]', 'starter template'])
-
-  t.true(arg instanceof Argument)
-  t.is(arg.name(), 'starter')
-  t.false(arg.required)
-})
-
-test('arrayToArgument applies choices from config', (t) => {
-  const arg = arrayToArgument(['<format>', 'output format', { choices: ['pdf', 'epub'] }])
-
-  t.true(arg instanceof Argument)
-  t.deepEqual(arg.argChoices, ['pdf', 'epub'])
-})
-
-test('arrayToArgument applies default from config', (t) => {
-  const arg = arrayToArgument(['[starter]', 'starter template', { default: 'default' }])
-
-  t.true(arg instanceof Argument)
-  t.is(arg.defaultValue, 'default')
-})
-
-// ─────────────────────────────────────────────────────────────────────────────
-// arrayToOption tests
-// ─────────────────────────────────────────────────────────────────────────────
-
-test('arrayToOption creates Option from combined flags', (t) => {
-  const opt = arrayToOption(['--debug', 'enable debug output'])
-
-  t.true(opt instanceof Option)
-  t.is(opt.long, '--debug')
-  t.is(opt.description, 'enable debug output')
-})
-
-test('arrayToOption creates Option from separate short/long flags', (t) => {
-  const opt = arrayToOption(['-v', '--verbose', 'enable verbose output'])
-
-  t.true(opt instanceof Option)
-  t.is(opt.short, '-v')
-  t.is(opt.long, '--verbose')
-  t.is(opt.description, 'enable verbose output')
-})
-
-test('arrayToOption applies choices from config object', (t) => {
-  const opt = arrayToOption([
-    '--lib <module>',
-    'library to use',
-    { choices: ['pagedjs', 'prince'], default: 'pagedjs' }
-  ])
-
-  t.true(opt instanceof Option)
-  t.deepEqual(opt.argChoices, ['pagedjs', 'prince'])
-  t.is(opt.defaultValue, 'pagedjs')
-})
-
-test('arrayToOption applies default from positional argument', (t) => {
-  const opt = arrayToOption(['--port <number>', 'port to use', 8080])
-
-  t.true(opt instanceof Option)
-  t.is(opt.defaultValue, 8080)
-})
-
-test('arrayToOption handles option with value placeholder', (t) => {
-  const opt = arrayToOption(['--output <path>', 'output directory'])
-
-  t.true(opt instanceof Option)
-  t.is(opt.long, '--output')
-  t.true(opt.required) // option requires a value
-})

package/src/lib/commander/options.js

@@ -1,237 +0,0 @@
-/**
- * Shared option definitions for CLI commands
- *
- * Provides consistent option definitions that can be imported by commands.
- * This ensures uniform help text, flags, and behavior across the CLI.
- *
- * ## Recommended Usage
- *
- * Use `withOutputModes()` to wrap your command definition:
- *
- * ```javascript
- * import { withOutputModes } from '#lib/commander/index.js'
- *
- * export default class MyCommand extends Command {
- *   static definition = withOutputModes({
- *     name: 'my-command',
- *     description: 'Do something useful',
- *     helpText: `
- * Examples:
- *   quire my-command --verbose
- * `,
- *     options: [
- *       ['--custom', 'my custom option'],
- *     ],
- *   })
- * }
- * ```
- *
- * This automatically adds --quiet, --verbose, --debug options and prepends
- * the standard output mode help text.
- *
- * ## Selective Options
- *
- * For commands that need only specific output options:
- *
- * ```javascript
- * import { quietOption, verboseOption } from '#lib/commander/index.js'
- *
- * options: [
- *   quietOption,
- *   verboseOption,
- *   // No --debug for this command
- * ]
- * ```
- *
- * ## Commander.js Boolean Negation
- *
- * Boolean options automatically support negation via Commander.js.
- * For example, `--verbose` automatically supports `--no-verbose`.
- *
- * This enables the config fallback pattern:
- * - `--verbose` → options.verbose = true
- * - `--no-verbose` → options.verbose = false
- * - (no flag) → options.verbose = undefined (falls back to config)
- *
- * @see https://github.com/tj/commander.js#other-option-types-negatable-boolean-and-booleanvalue
- * @module lib/commander/options
- */
-
-/**
- * Quiet mode option - suppress progress output
- *
- * Use for CI/CD pipelines and automated scripts where spinner
- * output would clutter logs. Exit codes still indicate success/failure.
- *
- * Conflicts with --verbose and --debug since quiet mode suppresses
- * the output those modes would show.
- *
- * @type {Array}
- */
-export const quietOption = [
-  '-q, --quiet', 'suppress progress output',
-  { conflicts: ['verbose', 'debug'] }
-]
-
-/**
- * Verbose mode option - show detailed progress
- *
- * Shows additional information like file paths, timing data,
- * and step-by-step progress. Useful when users want more
- * visibility into what the CLI is doing.
- *
- * Respects config default: `quire settings set verbose true`
- * Conflicts with --quiet since quiet mode suppresses output.
- *
- * @type {Array}
- */
-export const verboseOption = [
-  '-v, --verbose', 'show detailed progress output',
-  { conflicts: ['quiet'] }
-]
-
-/**
- * Progress option - hidden alias for --verbose
- *
- * Provides a familiar `--progress` flag as an alternative to `--verbose`.
- * Many users expect `--progress` to show detailed output during long-running
- * operations like builds and file deletions.
- *
- * Hidden from help output since --verbose is the canonical flag.
- * Uses `implies` to set verbose=true when --progress is used.
- *
- * @type {Array}
- */
-const progressOption = [
-  '--progress', 'show detailed progress (alias for --verbose)',
-  { hidden: true, implies: { verbose: true } }
-]
-
-/**
- * Debug mode option - enable debug output
- *
- * Enables the DEBUG=quire:* namespace for internal logging.
- * Outputs technical debugging information intended for developers
- * and maintainers troubleshooting issues.
- *
- * Respects config default: `quire settings set debug true`
- * Conflicts with --quiet since quiet mode suppresses output.
- *
- * @type {Array}
- */
-export const debugOption = [
-  '--debug', 'enable debug output for troubleshooting',
-  { conflicts: ['quiet'] }
-]
-
-/**
- * Reduced motion option - disable spinner animation and line overwriting
- *
- * When enabled, the reporter outputs static text on new lines instead of
- * animated spinners that overwrite the current line. This is useful for:
- * - Screen reader users (animated overwriting disrupts reading flow)
- * - Users who prefer reduced motion
- * - Environments where terminal animation is problematic
- *
- * Respects config default: `quire settings set reducedMotion true`
- * Also respects REDUCED_MOTION environment variable.
- *
- * @type {Array}
- */
-export const reducedMotionOption = [
-  '--reduced-motion', 'disable spinner animation and line overwriting',
-]
-
-/**
- * Color options - enable/disable colored output
- *
- * Commander.js requires separate option definitions for --color and --no-color
- * to support both the positive and negative forms. When --color has no default,
- * the three-state semantics are:
- *
- * - `--color` → options.color = true (force color on)
- * - `--no-color` → options.color = false (force color off)
- * - (no flag) → options.color = undefined (falls back to env/config)
- *
- * Respects the NO_COLOR environment variable (https://no-color.org/).
- * Respects config default: `quire settings set logUseColor false`
- *
- * @type {Array[]}
- */
-export const colorOption = [
-  '--color', 'force colored output (overrides NO_COLOR env var)',
-]
-
-export const noColorOption = [
-  '--no-color', 'disable colored output',
-]
-
-/**
- * Standard output mode options (quiet, verbose, debug, progress)
- *
- * Most commands should include all three options for consistent UX.
- * Spread this array into your command's options:
- *
- * ```javascript
- * options: [
- *   ...outputModeOptions,
- *   ['--my-option', 'custom option'],
- * ]
- * ```
- *
- * @type {string[][]}
- */
-export const outputModeOptions = [
-  quietOption,
-  verboseOption,
-  progressOption,
-  debugOption,
-]
-
-/**
- * Standard help text for output modes
- *
- * @type {string}
- */
-export const outputModeHelpText = `Output Modes:
-  -q, --quiet      Suppress progress output (for CI/scripts)
-  -v, --verbose    Show detailed progress (paths, timing)
-  --progress       Alias for --verbose
-  --debug          Enable debug output for troubleshooting`
-
-/**
- * Add output mode options to a command definition
- *
- * Injects --quiet, --verbose, --debug options and prepends the
- * standard output mode help text to the command's helpText.
- *
- * @param {Object} definition - Command definition object
- * @param {string} [definition.helpText] - Existing help text (output modes prepended)
- * @param {Array} [definition.options] - Existing options (output modes appended)
- * @returns {Object} Modified definition with output mode options
- *
- * @example
- * static definition = withOutputModes({
- *   name: 'build',
- *   description: 'Generate publication outputs',
- *   helpText: `
- * Examples:
- *   quire build --verbose
- * `,
- *   options: [
- *     ['--custom', 'my option'],
- *   ],
- * })
- */
-export function withOutputModes(definition) {
-  return {
-    ...definition,
-    helpText: definition.helpText
-      ? `\n${outputModeHelpText}\n${definition.helpText}`
-      : `\n${outputModeHelpText}`,
-    options: [
-      ...(definition.options || []),
-      ...outputModeOptions,
-    ],
-  }
-}

package/src/lib/commander/options.test.js

@@ -1,205 +0,0 @@
-import test from 'ava'
-import { Command } from 'commander'
-import { arrayToOption } from './index.js'
-import { colorOption, noColorOption, quietOption, verboseOption, debugOption, reducedMotionOption } from './options.js'
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Integration tests for option conflicts
-//
-// These tests verify that Commander.js correctly enforces the option conflicts
-// at parse time.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Helper to create a test program with the shared options
- */
-function createTestProgram() {
-  const program = new Command()
-  program
-    .addOption(arrayToOption(colorOption))
-    .addOption(arrayToOption(noColorOption))
-    .addOption(arrayToOption(quietOption))
-    .addOption(arrayToOption(verboseOption))
-    .addOption(arrayToOption(debugOption))
-    .addOption(arrayToOption(reducedMotionOption))
-    .action(() => {})
-    .exitOverride() // Throw instead of process.exit
-    .configureOutput({
-      writeErr: () => {}, // Suppress error output
-    })
-  return program
-}
-
-test('--quiet alone is valid', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--quiet'])
-  })
-})
-
-test('--verbose alone is valid', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--verbose'])
-  })
-})
-
-test('--debug alone is valid', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--debug'])
-  })
-})
-
-test('--verbose --debug together is valid', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--verbose', '--debug'])
-  })
-})
-
-test('--quiet --verbose throws conflict error', (t) => {
-  const program = createTestProgram()
-
-  const error = t.throws(() => {
-    program.parse(['node', 'test', '--quiet', '--verbose'])
-  })
-
-  t.true(error.message.includes('cannot be used with'))
-})
-
-test('--quiet --debug throws conflict error', (t) => {
-  const program = createTestProgram()
-
-  const error = t.throws(() => {
-    program.parse(['node', 'test', '--quiet', '--debug'])
-  })
-
-  t.true(error.message.includes('cannot be used with'))
-})
-
-test('--quiet --verbose --debug throws conflict error', (t) => {
-  const program = createTestProgram()
-
-  const error = t.throws(() => {
-    program.parse(['node', 'test', '--quiet', '--verbose', '--debug'])
-  })
-
-  t.true(error.message.includes('cannot be used with'))
-})
-
-test('-q -v (short flags) throws conflict error', (t) => {
-  const program = createTestProgram()
-
-  const error = t.throws(() => {
-    program.parse(['node', 'test', '-q', '-v'])
-  })
-
-  t.true(error.message.includes('cannot be used with'))
-})
-
-test('options order does not affect conflict detection', (t) => {
-  const program1 = createTestProgram()
-  const program2 = createTestProgram()
-
-  // Both orders should throw
-  t.throws(() => program1.parse(['node', 'test', '--quiet', '--verbose']))
-  t.throws(() => program2.parse(['node', 'test', '--verbose', '--quiet']))
-})
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Reduced motion option tests
-// ─────────────────────────────────────────────────────────────────────────────
-
-test('--reduced-motion alone is valid', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--reduced-motion'])
-  })
-})
-
-test('--reduced-motion sets opts.reducedMotion to true', (t) => {
-  const program = createTestProgram()
-  program.parse(['node', 'test', '--reduced-motion'])
-
-  t.is(program.opts().reducedMotion, true)
-})
-
-test('no flag leaves opts.reducedMotion as undefined', (t) => {
-  const program = createTestProgram()
-  program.parse(['node', 'test'])
-
-  t.is(program.opts().reducedMotion, undefined)
-})
-
-test('--reduced-motion combines with --verbose without conflict', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--reduced-motion', '--verbose'])
-  })
-})
-
-test('--reduced-motion combines with --quiet without conflict', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--reduced-motion', '--quiet'])
-  })
-})
-
-test('--reduced-motion combines with --debug without conflict', (t) => {
-  const program = createTestProgram()
-
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--reduced-motion', '--debug'])
-  })
-})
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Color option tests
-// ─────────────────────────────────────────────────────────────────────────────
-
-test('--no-color sets color to false', (t) => {
-  const program = createTestProgram()
-  program.parse(['node', 'test', '--no-color'])
-  t.is(program.opts().color, false)
-})
-
-test('--color sets color to true', (t) => {
-  const program = createTestProgram()
-  program.parse(['node', 'test', '--color'])
-  t.is(program.opts().color, true)
-})
-
-test('no color flag leaves color undefined', (t) => {
-  const program = createTestProgram()
-  program.parse(['node', 'test'])
-  t.is(program.opts().color, undefined)
-})
-
-test('--no-color can be combined with --verbose', (t) => {
-  const program = createTestProgram()
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--no-color', '--verbose'])
-  })
-})
-
-test('--no-color can be combined with --quiet', (t) => {
-  const program = createTestProgram()
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--no-color', '--quiet'])
-  })
-})
-
-test('--no-color can be combined with --debug', (t) => {
-  const program = createTestProgram()
-  t.notThrows(() => {
-    program.parse(['node', 'test', '--no-color', '--debug'])
-  })
-})