@thegetty/quire-cli 1.0.0-rc.40 → 1.0.0-rc.42

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

@@ -1,7 +1,7 @@
 import test from 'ava'
 import { Command } from 'commander'
 import { arrayToOption } from './index.js'
-import { colorOption, noColorOption, quietOption, verboseOption, debugOption } from './options.js'
+import { colorOption, noColorOption, quietOption, verboseOption, debugOption, reducedMotionOption } from './options.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Integration tests for option conflicts
@@ -21,6 +21,7 @@ function createTestProgram() {
     .addOption(arrayToOption(quietOption))
     .addOption(arrayToOption(verboseOption))
     .addOption(arrayToOption(debugOption))
+    .addOption(arrayToOption(reducedMotionOption))
     .action(() => {})
     .exitOverride() // Throw instead of process.exit
     .configureOutput({
@@ -110,6 +111,56 @@ test('options order does not affect conflict detection', (t) => {
   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
 // ─────────────────────────────────────────────────────────────────────────────

package/src/lib/conf/defaults.js

@@ -48,6 +48,13 @@ export default {
    * Default PDF engine for quire pdf command.
    */
   pdfEngine: 'pagedjs',
+  /**
+   * Disable spinner animation and line overwriting.
+   * When enabled, progress output uses static text instead of animated spinners,
+   * and each stage prints on a new line rather than overwriting the current line.
+   * Can be overridden per-command with --reduced-motion.
+   */
+  reducedMotion: false,
   /**
    * Project starter template to use when creating new projects.
    */

package/src/lib/conf/schema.js

@@ -41,6 +41,10 @@ export default {
     type: 'boolean',
     description: 'Color message text by log level (e.g., red for errors). Requires logUseColor'
   },
+  reducedMotion: {
+    type: 'boolean',
+    description: 'Disable spinner animation and line overwriting (for screen readers and reduced-motion preferences)'
+  },
   projectTemplate: {
     type: 'string',
     format: 'uri',

package/src/lib/help/index.js

@@ -59,6 +59,16 @@ async function listTopics() {
   return topics.sort((a, b) => a.name.localeCompare(b.name))
 }
 
+/**
+ * Get available topic names from the topics directory
+ * @returns {Promise<string[]>} Topic names (filenames without .md)
+ */
+async function getTopicNames() {
+  if (!await fs.pathExists(TOPICS_DIR)) return []
+  const files = await fs.readdir(TOPICS_DIR)
+  return files.filter((f) => f.endsWith('.md')).map((f) => path.basename(f, '.md'))
+}
+
 /**
  * Load a help topic by name
  * @param {string} name - Topic name (without .md extension)
@@ -69,7 +79,8 @@ async function loadTopic(name) {
   const filePath = path.join(TOPICS_DIR, `${name}.md`)
 
   if (!await fs.pathExists(filePath)) {
-    throw new HelpTopicNotFoundError(name)
+    const validTopics = await getTopicNames()
+    throw new HelpTopicNotFoundError(name, validTopics)
   }
 
   const content = await fs.readFile(filePath, 'utf-8')

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

@@ -134,7 +134,10 @@ test('getTopicContent() throws HelpTopicNotFoundError for missing topic', async
   const { sandbox } = t.context
 
   const mockFs = {
-    pathExists: sandbox.stub().resolves(false)
+    pathExists: sandbox.stub()
+      .onFirstCall().resolves(false)   // topic file does not exist
+      .onSecondCall().resolves(true),  // topics directory exists
+    readdir: sandbox.stub().resolves(['epub.md', 'pdf.md', 'debugging.md'])
   }
 
   const { getTopicContent } = await esmock('./index.js', {
@@ -150,6 +153,31 @@ test('getTopicContent() throws HelpTopicNotFoundError for missing topic', async
   t.is(error.topic, 'nonexistent')
 })
 
+test('getTopicContent() suggests similar topic for typo', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub()
+      .onFirstCall().resolves(false)
+      .onSecondCall().resolves(true),
+    readdir: sandbox.stub().resolves([
+      'configuration.md', 'debugging.md', 'epub.md',
+      'pdf.md', 'publishing.md', 'workflows.md'
+    ])
+  }
+
+  const { getTopicContent } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const error = await t.throwsAsync(
+    () => getTopicContent('edub'),
+    { name: 'HelpTopicNotFoundError' }
+  )
+
+  t.is(error.suggestion, 'Did you mean: epub?')
+})
+
 test('getTopicsDir() returns the topics directory path', async (t) => {
   const { getTopicsDir } = await import('./index.js')
 

package/src/lib/reporter/index.js

@@ -14,14 +14,27 @@
  * | Default | (none) | Show spinner with basic status |
  * | Quiet | `-q, --quiet` | Suppress all output (for CI/scripts) |
  * | Verbose | `-v, --verbose` | Show detailed progress with paths, timing |
+ * | Reduced Motion | `--reduced-motion` | Static text, no animation, no line overwriting |
  *
  * Note: `--debug` is handled separately and enables DEBUG namespace logging,
  * not reporter output. Use verbose mode for detailed user-facing output.
  *
+ * ## Reduced Motion
+ *
+ * When reduced motion is enabled (via `--reduced-motion` flag, `REDUCED_MOTION`
+ * environment variable, or `reducedMotion` config setting), the reporter:
+ * - Prints static text instead of animated spinners
+ * - Outputs each stage on a new line (no line overwriting)
+ * - Still shows status symbols (✔ ✖ ⚠ ℹ) for completion states
+ *
+ * This mode is designed for screen reader users and environments where
+ * terminal animation is problematic.
+ *
  * ## Config Defaults
  *
  * Users can set default values via `quire settings`:
  * - `quire settings set verbose true` - Always run in verbose mode
+ * - `quire settings set reducedMotion true` - Disable spinner animation
  *
  * CLI flags override config settings. Use `--no-verbose` to disable verbose
  * mode even when enabled in config.
@@ -81,11 +94,27 @@ import config from '#lib/conf/config.js'
 
 const debug = createDebug('lib:reporter')
 
+/**
+ * Status symbols for reduced motion output
+ *
+ * These match the symbols used by ora for visual consistency,
+ * ensuring the same information is conveyed with or without animation.
+ * @private
+ */
+const STATUS_SYMBOLS = {
+  start: '–',
+  succeed: '✔',
+  fail: '✖',
+  warn: '⚠',
+  info: 'ℹ',
+}
+
 /**
  * Reporter class for CLI progress feedback
  *
  * Wraps ora spinner with additional features:
  * - Respects --quiet and --json flags
+ * - Supports reduced motion (static text, no line overwriting)
  * - Supports elapsed time display
  * - Provides consistent API across commands
  */
@@ -111,6 +140,22 @@ class Reporter {
   /** @type {string} */
   #baseText = ''
 
+  /**
+   * Check if reduced motion mode is active
+   *
+   * Reduced motion disables spinner animation and line overwriting.
+   * Reads from the REDUCED_MOTION environment variable, which is set by:
+   * - `--reduced-motion` CLI flag (via preAction hook)
+   * - `REDUCED_MOTION=1` shell environment variable
+   * - `reducedMotion: true` config setting (via bin/cli.js)
+   *
+   * @private
+   * @returns {boolean}
+   */
+  #isReducedMotion() {
+    return Boolean(process.env.REDUCED_MOTION)
+  }
+
   /**
    * Configure reporter for current command context
    *
@@ -134,7 +179,8 @@ class Reporter {
     this.#json = options.json || false
     // CLI flag takes precedence, then config setting, then default false
     this.#verbose = options.verbose ?? config.get('verbose') ?? false
-    debug('configured: quiet=%s, json=%s, verbose=%s', this.#quiet, this.#json, this.#verbose)
+    debug('configured: quiet=%s, json=%s, verbose=%s, reducedMotion=%s',
+      this.#quiet, this.#json, this.#verbose, this.#isReducedMotion())
     return this
   }
 
@@ -175,6 +221,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print static text on a new line, no spinner
+    if (this.#isReducedMotion()) {
+      debug('spinner start (reduced motion): %s', text)
+      console.log(`${STATUS_SYMBOLS.start} ${text}`)
+      return this
+    }
+
     debug('spinner start: %s', text)
     this.#spinner = ora({
       text,
@@ -235,6 +288,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print new line instead of overwriting
+    if (this.#isReducedMotion()) {
+      debug('spinner update (reduced motion): %s', text)
+      console.log(`${STATUS_SYMBOLS.start} ${text}`)
+      return this
+    }
+
     if (this.#spinner) {
       debug('spinner update: %s', text)
       this.#spinner.text = text
@@ -273,6 +333,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print static success line
+    if (this.#isReducedMotion()) {
+      debug('spinner succeed (reduced motion): %s', message)
+      console.log(`${STATUS_SYMBOLS.succeed} ${message}`)
+      return this
+    }
+
     if (this.#spinner) {
       debug('spinner succeed: %s', message)
       this.#spinner.succeed(message)
@@ -309,6 +376,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print static failure line
+    if (this.#isReducedMotion()) {
+      debug('spinner fail (reduced motion): %s', message)
+      console.log(`${STATUS_SYMBOLS.fail} ${message}`)
+      return this
+    }
+
     if (this.#spinner) {
       debug('spinner fail: %s', message)
       this.#spinner.fail(message)
@@ -343,6 +417,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print static warning line
+    if (this.#isReducedMotion()) {
+      debug('spinner warn (reduced motion): %s', message)
+      console.log(`${STATUS_SYMBOLS.warn} ${message}`)
+      return this
+    }
+
     if (this.#spinner) {
       debug('spinner warn: %s', message)
       this.#spinner.warn(message)
@@ -370,6 +451,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print static info line
+    if (this.#isReducedMotion()) {
+      debug('spinner info (reduced motion): %s', text)
+      console.log(`${STATUS_SYMBOLS.info} ${text}`)
+      return this
+    }
+
     if (this.#spinner) {
       debug('spinner info: %s', text)
       this.#spinner.info(text)
@@ -405,6 +493,13 @@ class Reporter {
       return this
     }
 
+    // Reduced motion: print detail directly (no spinner to stop/restart)
+    if (this.#isReducedMotion()) {
+      console.log(`  ${text}`)
+      debug('detail (reduced motion): %s', text)
+      return this
+    }
+
     // Print detail with indentation below spinner
     if (this.#spinner) {
       // Temporarily stop spinner to print detail

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

@@ -591,3 +591,272 @@ test('multi-phase workflow with different outcomes', (t) => {
 
   t.pass()
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Reduced motion tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.serial('reduced motion: start() does not create ora spinner', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Building...')
+
+    t.false(mockOra.called, 'ora should not be called in reduced motion mode')
+    t.true(consoleLog.calledOnce, 'console.log should be called once')
+    t.true(consoleLog.firstCall.args[0].includes('Building...'),
+      'output should include the text')
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: update() prints new line instead of overwriting', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Step 1...')
+    rep.update('Step 2...')
+
+    t.is(consoleLog.callCount, 2, 'should print two separate lines')
+    t.true(consoleLog.firstCall.args[0].includes('Step 1...'))
+    t.true(consoleLog.secondCall.args[0].includes('Step 2...'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: succeed() prints static success line', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Building...')
+    rep.succeed('Build complete')
+
+    t.is(consoleLog.callCount, 2)
+    // Second call is succeed
+    t.true(consoleLog.secondCall.args[0].includes('✔'))
+    t.true(consoleLog.secondCall.args[0].includes('Build complete'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: fail() prints static failure line', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Generating PDF...')
+    rep.fail('PDF generation failed')
+
+    t.is(consoleLog.callCount, 2)
+    t.true(consoleLog.secondCall.args[0].includes('✖'))
+    t.true(consoleLog.secondCall.args[0].includes('PDF generation failed'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: warn() prints static warning line', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Checking...')
+    rep.warn('Dependencies outdated')
+
+    t.is(consoleLog.callCount, 2)
+    t.true(consoleLog.secondCall.args[0].includes('⚠'))
+    t.true(consoleLog.secondCall.args[0].includes('Dependencies outdated'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: info() prints static info line', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.info('Using cached dependencies')
+
+    t.true(consoleLog.calledOnce)
+    t.true(consoleLog.firstCall.args[0].includes('ℹ'))
+    t.true(consoleLog.firstCall.args[0].includes('Using cached dependencies'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: multi-phase workflow outputs each phase on new line', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalIsTTY = process.stdout.isTTY
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.start('Cloning starter...')
+    rep.update('Installing dependencies...')
+    rep.succeed('Project created')
+
+    t.is(consoleLog.callCount, 3, 'each stage should print on a new line')
+    t.true(consoleLog.getCall(0).args[0].includes('Cloning starter...'))
+    t.true(consoleLog.getCall(1).args[0].includes('Installing dependencies...'))
+    t.true(consoleLog.getCall(2).args[0].includes('✔'))
+    t.true(consoleLog.getCall(2).args[0].includes('Project created'))
+    t.false(mockOra.called, 'ora should never be called')
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})
+
+test.serial('reduced motion: quiet mode takes precedence over reduced motion', async (t) => {
+  const { sandbox } = t.context
+  const mockOra = sandbox.stub()
+
+  const { Reporter: MockedReporter } = await esmock('./index.js', {
+    ora: { default: mockOra },
+  })
+
+  const originalReduceMotion = process.env.REDUCED_MOTION
+  const consoleLog = sandbox.stub(console, 'log')
+
+  try {
+    process.env.REDUCED_MOTION = '1'
+
+    const rep = new MockedReporter()
+    rep.configure({ quiet: true })
+    rep.start('Building...')
+    rep.succeed('Build complete')
+
+    t.false(consoleLog.called, 'quiet mode should suppress all output')
+    t.false(mockOra.called, 'ora should not be called')
+  } finally {
+    if (originalReduceMotion === undefined) {
+      delete process.env.REDUCED_MOTION
+    } else {
+      process.env.REDUCED_MOTION = originalReduceMotion
+    }
+  }
+})