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

package/bin/cli.js

@@ -19,6 +19,20 @@ process.removeAllListeners('warning')
  */
 process.env.QUIRE_LOG_LEVEL = config.get('logLevel') || 'info'
 
+/**
+ * Set REDUCED_MOTION env var from config before importing CLI modules
+ *
+ * The reporter reads REDUCED_MOTION to decide whether to use animated
+ * spinners or static text output. Setting it here ensures the reporter
+ * picks up the config value at module load time.
+ * If REDUCED_MOTION is already set in the shell environment, we do not override it.
+ *
+ * @see lib/reporter/index.js
+ */
+if (process.env.REDUCED_MOTION === undefined && config.get('reducedMotion') === true) {
+  process.env.REDUCED_MOTION = '1'
+}
+
 /**
  * Set NO_COLOR env var from config before importing CLI modules
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.40",
+  "version": "1.0.0-rc.42",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {

package/src/commands/config.js

@@ -7,6 +7,7 @@ import {
   getDefault,
   formatSettings,
 } from '#lib/conf/index.js'
+import { UnknownConfigKeyError, UnknownConfigOperationError } from '#src/errors/index.js'
 
 /**
  * Valid operations for the settings command
@@ -77,16 +78,6 @@ Examples:
     super(SettingsCommand.definition)
   }
 
-  /**
-   * Log an unknown key error with valid keys hint
-   *
-   * @param {string} key - The unknown configuration key
-   */
-  #logUnknownKey(key) {
-    this.logger.error(`Unknown configuration key: ${key}`)
-    this.logger.info(`Valid keys: ${getValidKeys().join(', ')}`)
-  }
-
   /**
    * Get a single configuration value
    *
@@ -100,8 +91,7 @@ Examples:
     }
 
     if (!isValidKey(key) && !key.startsWith('__internal__')) {
-      this.#logUnknownKey(key)
-      return
+      throw new UnknownConfigKeyError(key, getValidKeys())
     }
 
     const value = this.config.get(key)
@@ -131,8 +121,7 @@ Examples:
     }
 
     if (!isValidKey(key)) {
-      this.#logUnknownKey(key)
-      return
+      throw new UnknownConfigKeyError(key, getValidKeys())
     }
 
     const coercedValue = coerceValue(key, value)
@@ -157,8 +146,7 @@ Examples:
     }
 
     if (!isValidKey(key)) {
-      this.#logUnknownKey(key)
-      return
+      throw new UnknownConfigKeyError(key, getValidKeys())
     }
 
     this.config.delete(key)
@@ -174,8 +162,7 @@ Examples:
   #reset(key) {
     if (key) {
       if (!isValidKey(key)) {
-        this.#logUnknownKey(key)
-        return
+        throw new UnknownConfigKeyError(key, getValidKeys())
       }
       this.config.reset(key)
       const defaultValue = getDefault(key)
@@ -229,9 +216,7 @@ Examples:
 
     // Validate operation if provided
     if (operation && !OPERATIONS.includes(operation)) {
-      this.logger.error(`Unknown operation: ${operation}`)
-      this.logger.info(`Valid operations: ${OPERATIONS.join(', ')}`)
-      return
+      throw new UnknownConfigOperationError(operation, [...OPERATIONS])
     }
 
     // Dispatch to operation handler

package/src/commands/config.test.js

@@ -200,7 +200,7 @@ test('conf get should show error when key is missing', async (t) => {
   t.true(mockLogger.error.calledWith('Usage: quire conf get <key>'))
 })
 
-test('conf get should show error for unknown key', async (t) => {
+test('conf get should throw UnknownConfigKeyError for unknown key', async (t) => {
   const { sandbox, mockLogger, mockConfig } = t.context
 
   const { default: ConfCommand } = await esmock('./config.js', {}, {
@@ -214,12 +214,55 @@ test('conf get should show error for unknown key', async (t) => {
   command.logger = mockLogger
   command.debug = sandbox.stub()
 
-  await command.action('get', 'unknownKey', undefined, {})
+  const error = await t.throwsAsync(
+    () => command.action('get', 'unknownKey', undefined, {}),
+    { code: 'UNKNOWN_CONFIG_KEY' }
+  )
+  t.true(error.message.includes('Unknown configuration key: unknownKey'))
+  t.true(error.suggestion.includes('Valid keys:'))
+})
 
-  t.true(mockLogger.error.calledOnce)
-  t.true(mockLogger.error.calledWith('Unknown configuration key: unknownKey'))
-  t.true(mockLogger.info.calledOnce)
-  t.true(mockLogger.info.firstCall.args[0].includes('Valid keys:'))
+test('conf get should suggest similar key for close misspelling', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const error = await t.throwsAsync(
+    () => command.action('get', 'logLeve', undefined, {}),
+    { code: 'UNKNOWN_CONFIG_KEY' }
+  )
+  t.true(error.message.includes('Unknown configuration key: logLeve'))
+  t.true(error.suggestion.includes('Did you mean: logLevel?'))
+})
+
+test('conf get should suggest similar key for case difference', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const error = await t.throwsAsync(
+    () => command.action('get', 'loglevel', undefined, {}),
+    { code: 'UNKNOWN_CONFIG_KEY' }
+  )
+  t.true(error.suggestion.includes('Did you mean: logLevel?'))
 })
 
 // =============================================================================
@@ -420,7 +463,7 @@ test('conf delete should show error when key is missing', async (t) => {
   t.false(mockConfig.delete.called)
 })
 
-test('conf delete should show error for unknown key', async (t) => {
+test('conf delete should throw UnknownConfigKeyError for unknown key', async (t) => {
   const { sandbox, mockLogger, mockConfig } = t.context
 
   const { default: ConfCommand } = await esmock('./config.js', {}, {
@@ -434,9 +477,10 @@ test('conf delete should show error for unknown key', async (t) => {
   command.logger = mockLogger
   command.debug = sandbox.stub()
 
-  await command.action('delete', 'unknownKey', undefined, {})
-
-  t.true(mockLogger.error.calledOnce)
+  await t.throwsAsync(
+    () => command.action('delete', 'unknownKey', undefined, {}),
+    { code: 'UNKNOWN_CONFIG_KEY' }
+  )
   t.false(mockConfig.delete.called)
 })
 
@@ -485,7 +529,7 @@ test('conf reset should reset all config when no key provided', async (t) => {
   t.true(mockLogger.info.calledWith('Configuration reset to defaults'))
 })
 
-test('conf reset should show error for unknown key', async (t) => {
+test('conf reset should throw UnknownConfigKeyError for unknown key', async (t) => {
   const { sandbox, mockLogger, mockConfig } = t.context
 
   const { default: ConfCommand } = await esmock('./config.js', {}, {
@@ -499,9 +543,10 @@ test('conf reset should show error for unknown key', async (t) => {
   command.logger = mockLogger
   command.debug = sandbox.stub()
 
-  await command.action('reset', 'unknownKey', undefined, {})
-
-  t.true(mockLogger.error.calledOnce)
+  await t.throwsAsync(
+    () => command.action('reset', 'unknownKey', undefined, {}),
+    { code: 'UNKNOWN_CONFIG_KEY' }
+  )
   t.false(mockConfig.reset.called)
 })
 
@@ -533,7 +578,7 @@ test('conf path should show config file path', async (t) => {
 // Invalid operation
 // =============================================================================
 
-test('conf should show error for unknown operation', async (t) => {
+test('conf should throw UnknownConfigOperationError for unknown operation', async (t) => {
   const { sandbox, mockLogger, mockConfig } = t.context
 
   const { default: ConfCommand } = await esmock('./config.js', {}, {
@@ -547,12 +592,56 @@ test('conf should show error for unknown operation', async (t) => {
   command.logger = mockLogger
   command.debug = sandbox.stub()
 
-  await command.action('unknownOp', undefined, undefined, {})
+  const error = await t.throwsAsync(
+    () => command.action('unknownOp', undefined, undefined, {}),
+    { code: 'UNKNOWN_CONFIG_OPERATION' }
+  )
+  t.true(error.message.includes('Unknown operation: unknownOp'))
+  t.true(error.suggestion.includes('Valid operations:'))
+})
 
-  t.true(mockLogger.error.calledOnce)
-  t.true(mockLogger.error.calledWith('Unknown operation: unknownOp'))
-  t.true(mockLogger.info.calledOnce)
-  t.true(mockLogger.info.firstCall.args[0].includes('Valid operations:'))
+test('conf should suggest similar operation for close misspelling', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const error = await t.throwsAsync(
+    () => command.action('gt', undefined, undefined, {}),
+    { code: 'UNKNOWN_CONFIG_OPERATION' }
+  )
+  t.true(error.message.includes('Unknown operation: gt'))
+  t.true(error.suggestion.includes('Did you mean: get?'))
+})
+
+test('conf should suggest similar operation for transposition', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const error = await t.throwsAsync(
+    () => command.action('ste', undefined, undefined, {}),
+    { code: 'UNKNOWN_CONFIG_OPERATION' }
+  )
+  t.true(error.message.includes('Unknown operation: ste'))
+  t.true(error.suggestion.includes('Did you mean: set?'))
 })
 
 // =============================================================================

package/src/errors/help/help-topic-not-found-error.js

@@ -1,11 +1,18 @@
 import InvalidInputError from '../input/invalid-input-error.js'
-import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+import { suggestSimilar, formatSuggestion } from '#helpers/suggest-similar.js'
 
 /**
  * Error thrown when a requested help topic does not exist
+ *
+ * @param {string} topic - The unrecognized topic name
+ * @param {string[]} validTopics - Array of available topic names
  */
 export default class HelpTopicNotFoundError extends InvalidInputError {
-  constructor(topic) {
+  constructor(topic, validTopics = []) {
+    const suggestion = formatSuggestion(suggestSimilar(topic, validTopics))
+      || 'Run "quire help --list" to see available topics'
+
     super(
       `Unknown help topic: ${topic}`,
       {
@@ -13,8 +20,9 @@ export default class HelpTopicNotFoundError extends InvalidInputError {
         exitCode: 2,
         inputValue: topic,
         inputName: 'topic',
-        suggestion: 'Run "quire help --list" to see available topics',
-        docsUrl: `${QuireError.DOCS_BASE}/quire-commands/`
+        suggestion,
+        docsUrl: docsUrl('quire-commands/'),
+        showDebugHint: false
       }
     )
     this.topic = topic

package/src/errors/index.js

@@ -45,7 +45,11 @@ export {
 } from './install/index.js'
 
 // Validation errors (exit code: 4)
-export { default as ValidationError } from './validation/validation-error.js'
+export {
+  ValidationError,
+  UnknownConfigKeyError,
+  UnknownConfigOperationError
+} from './validation/index.js'
 
 // Input errors (exit code: 2)
 export { InvalidInputError } from './input/index.js'

package/src/errors/validation/index.js

@@ -0,0 +1,3 @@
+export { default as ValidationError } from './validation-error.js'
+export { default as UnknownConfigKeyError } from './unknown-config-key-error.js'
+export { default as UnknownConfigOperationError } from './unknown-config-operation-error.js'

package/src/errors/validation/unknown-config-key-error.js

@@ -0,0 +1,27 @@
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+import { suggestSimilar, formatSuggestion } from '#helpers/suggest-similar.js'
+
+/**
+ * Error thrown when an unrecognized configuration key is used
+ *
+ * @param {string} key - The unrecognized key
+ * @param {string[]} validKeys - Array of valid configuration keys
+ */
+export default class UnknownConfigKeyError extends QuireError {
+  constructor(key, validKeys) {
+    const suggestion = formatSuggestion(suggestSimilar(key, validKeys))
+      || `Valid keys: ${validKeys.join(', ')}`
+
+    super(
+      `Unknown configuration key: ${key}`,
+      {
+        code: 'UNKNOWN_CONFIG_KEY',
+        exitCode: 4,
+        suggestion,
+        docsUrl: docsUrl('quire-commands/'),
+        showDebugHint: false
+      }
+    )
+  }
+}

package/src/errors/validation/unknown-config-operation-error.js

@@ -0,0 +1,24 @@
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+import { suggestSimilar, formatSuggestion } from '#helpers/suggest-similar.js'
+
+/**
+ * Error thrown when an unrecognized settings operation is used
+ */
+export default class UnknownConfigOperationError extends QuireError {
+  constructor(operation, validOperations) {
+    const suggestion = formatSuggestion(suggestSimilar(operation, validOperations))
+      || `Valid operations: ${validOperations.join(', ')}`
+
+    super(
+      `Unknown operation: ${operation}`,
+      {
+        code: 'UNKNOWN_CONFIG_OPERATION',
+        exitCode: 4,
+        suggestion,
+        docsUrl: docsUrl('quire-commands/'),
+        showDebugHint: false
+      }
+    )
+  }
+}

package/src/helpers/suggest-similar.js

@@ -0,0 +1,124 @@
+/**
+ * Fuzzy string matching for CLI suggestions
+ *
+ * Uses Damerau-Levenshtein distance (optimal string alignment variant)
+ * to find close matches for misspelled user input. The algorithm and
+ * parameters match Commander.js's built-in suggestion implementation
+ * for consistency.
+ *
+ * @module helpers/suggest-similar
+ */
+
+const MAX_DISTANCE = 3
+const MIN_SIMILARITY = 0.4
+
+/**
+ * Calculate Damerau-Levenshtein distance between two strings
+ *
+ * Supports insertions, deletions, substitutions, and transpositions
+ * of adjacent characters. Each substring is edited at most once
+ * (optimal string alignment variant).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Edit distance
+ * @private
+ */
+function editDistance(a, b) {
+  if (Math.abs(a.length - b.length) > MAX_DISTANCE) {
+    return Math.max(a.length, b.length)
+  }
+
+  const d = []
+
+  for (let i = 0; i <= a.length; ++i) d[i] = [i]
+  for (let j = 0; j <= b.length; ++j) d[0][j] = j
+
+  for (let j = 1; j <= b.length; ++j) {
+    for (let i = 1; i <= a.length; ++i) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1,        // deletion
+        d[i][j - 1] + 1,        // insertion
+        d[i - 1][j - 1] + cost, // substitution
+      )
+      // transposition
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1)
+      }
+    }
+  }
+
+  return d[a.length][b.length]
+}
+
+/**
+ * Find similar strings from a list of candidates
+ *
+ * Returns the closest matches by edit distance, filtered by a minimum
+ * similarity threshold (40%). Only returns matches at the best distance
+ * found (does not mix distances).
+ *
+ * @param {string} word - The misspelled input
+ * @param {string[]} candidates - Valid values to match against
+ * @returns {string[]} Sorted array of best matches (empty if none close enough)
+ *
+ * @example
+ * suggestSimilar('gt', ['get', 'set', 'delete', 'reset', 'path'])
+ * // → ['get']
+ *
+ * @example
+ * suggestSimilar('logLeve', ['logLevel', 'logPrefix', 'verbose'])
+ * // → ['logLevel']
+ */
+export function suggestSimilar(word, candidates) {
+  if (!word || !candidates?.length) return []
+
+  const unique = [...new Set(candidates)]
+  let similar = []
+  let bestDistance = MAX_DISTANCE
+
+  for (const candidate of unique) {
+    if (candidate.length <= 1) continue
+
+    const distance = editDistance(word, candidate)
+    const length = Math.max(word.length, candidate.length)
+    const similarity = (length - distance) / length
+
+    if (similarity > MIN_SIMILARITY) {
+      if (distance < bestDistance) {
+        bestDistance = distance
+        similar = [candidate]
+      } else if (distance === bestDistance) {
+        similar.push(candidate)
+      }
+    }
+  }
+
+  return similar.sort((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Format suggestion matches into a user-facing string
+ *
+ * @param {string[]} matches - Array of suggested matches
+ * @returns {string|undefined} Formatted suggestion or undefined if no matches
+ *
+ * @example
+ * formatSuggestion(['logLevel'])
+ * // → 'Did you mean: logLevel?'
+ *
+ * @example
+ * formatSuggestion(['get', 'set'])
+ * // → 'Did you mean one of: get, set?'
+ *
+ * @example
+ * formatSuggestion([])
+ * // → undefined
+ */
+export function formatSuggestion(matches) {
+  if (!matches?.length) return undefined
+  return (matches.length === 1)
+    ? `Did you mean: ${matches[0]}?`
+    : `Did you mean one of: ${matches.join(', ')}?`
+}

package/src/helpers/suggest-similar.test.js

@@ -0,0 +1,108 @@
+import test from 'ava'
+import { suggestSimilar, formatSuggestion } from './suggest-similar.js'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// suggestSimilar
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('suggestSimilar returns match for single-character deletion', (t) => {
+  const result = suggestSimilar('gt', ['get', 'set', 'delete', 'reset', 'path'])
+  t.deepEqual(result, ['get'])
+})
+
+test('suggestSimilar returns match for single-character insertion', (t) => {
+  const result = suggestSimilar('geet', ['get', 'set', 'delete'])
+  t.deepEqual(result, ['get'])
+})
+
+test('suggestSimilar returns match for single-character substitution', (t) => {
+  const result = suggestSimilar('gat', ['get', 'set', 'delete'])
+  t.deepEqual(result, ['get'])
+})
+
+test('suggestSimilar returns match for transposition', (t) => {
+  const result = suggestSimilar('gte', ['get', 'set', 'delete'])
+  t.deepEqual(result, ['get'])
+})
+
+test('suggestSimilar returns match for camelCase near-miss', (t) => {
+  const result = suggestSimilar('logLeve', ['logLevel', 'logPrefix', 'verbose'])
+  t.deepEqual(result, ['logLevel'])
+})
+
+test('suggestSimilar returns match for case difference', (t) => {
+  // 'loglevel' vs 'logLevel' differs by one character (L vs l)
+  const result = suggestSimilar('loglevel', ['logLevel', 'logPrefix', 'verbose'])
+  t.deepEqual(result, ['logLevel'])
+})
+
+test('suggestSimilar returns empty array when no candidates are similar', (t) => {
+  const result = suggestSimilar('xyzabc', ['get', 'set', 'delete', 'reset', 'path'])
+  t.deepEqual(result, [])
+})
+
+test('suggestSimilar returns empty array for empty input', (t) => {
+  t.deepEqual(suggestSimilar('', ['get', 'set']), [])
+})
+
+test('suggestSimilar returns empty array for null input', (t) => {
+  t.deepEqual(suggestSimilar(null, ['get', 'set']), [])
+})
+
+test('suggestSimilar returns empty array for empty candidates', (t) => {
+  t.deepEqual(suggestSimilar('get', []), [])
+})
+
+test('suggestSimilar returns empty array for null candidates', (t) => {
+  t.deepEqual(suggestSimilar('get', null), [])
+})
+
+test('suggestSimilar excludes single-character candidates', (t) => {
+  // 'g' is distance 0 from 'g', but should be excluded
+  const result = suggestSimilar('g', ['g', 'get', 'set'])
+  t.deepEqual(result, [])
+})
+
+test('suggestSimilar deduplicates candidates', (t) => {
+  const result = suggestSimilar('gt', ['get', 'get', 'get'])
+  t.deepEqual(result, ['get'])
+})
+
+test('suggestSimilar returns multiple matches sorted alphabetically', (t) => {
+  // 'bild' is distance 1 from 'bind' and 'build' — both should match
+  // but 'build' is distance 1 (deletion), 'bind' is distance 2 (substitution + deletion)
+  // Let's use a case where two candidates have equal distance
+  const result = suggestSimilar('delet', ['delete', 'reset'])
+  // 'delet' → 'delete' distance 1, 'delet' → 'reset' distance 2
+  t.deepEqual(result, ['delete'])
+})
+
+test('suggestSimilar returns multiple equally-close matches', (t) => {
+  // Both 'bar' and 'baz' are distance 1 from 'bax'
+  const result = suggestSimilar('bax', ['bar', 'baz', 'foo'])
+  t.deepEqual(result, ['bar', 'baz'])
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// formatSuggestion
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('formatSuggestion returns undefined for empty array', (t) => {
+  t.is(formatSuggestion([]), undefined)
+})
+
+test('formatSuggestion returns undefined for null', (t) => {
+  t.is(formatSuggestion(null), undefined)
+})
+
+test('formatSuggestion returns undefined for undefined', (t) => {
+  t.is(formatSuggestion(undefined), undefined)
+})
+
+test('formatSuggestion formats single match', (t) => {
+  t.is(formatSuggestion(['logLevel']), 'Did you mean: logLevel?')
+})
+
+test('formatSuggestion formats multiple matches', (t) => {
+  t.is(formatSuggestion(['bar', 'baz']), 'Did you mean one of: bar, baz?')
+})

package/src/lib/commander/index.js

@@ -15,6 +15,7 @@ export {
   quietOption,
   verboseOption,
   debugOption,
+  reducedMotionOption,
   outputModeOptions,
   outputModeHelpText,
   withOutputModes,

package/src/lib/commander/options.js

@@ -124,6 +124,24 @@ export const debugOption = [
   { 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
  *