@thegetty/quire-cli 1.0.0-rc.39 → 1.0.0-rc.41

package/bin/cli.js

@@ -20,7 +20,20 @@ process.removeAllListeners('warning')
 process.env.QUIRE_LOG_LEVEL = config.get('logLevel') || 'info'
 
 /**
- * Dynamic import ensures env var is set before logger modules are loaded
+ * Set NO_COLOR env var from config before importing CLI modules
+ *
+ * Chalk 5.x and ora read NO_COLOR at module load time.
+ * Setting it here ensures color is disabled before any styled imports.
+ * If NO_COLOR is already set in the shell environment, we do not override it.
+ *
+ * @see https://no-color.org/
+ */
+if (process.env.NO_COLOR === undefined && config.get('logUseColor') === false) {
+  process.env.NO_COLOR = '1'
+}
+
+/**
+ * Dynamic import ensures env vars are set before logger modules are loaded
  */
 const { default: cli } = await import('#src/main.js')
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.39",
+  "version": "1.0.0-rc.41",
   "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)
@@ -205,7 +192,7 @@ Examples:
     const output = formatSettings(this.config.store, {
       showInternal: options.debug,
       configPath: this.config.path,
-      useColor: this.config.get('logUseColor'),
+      useColor: this.config.get('logUseColor') && !process.env.NO_COLOR,
     })
     this.logger.info(output)
   }
@@ -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

@@ -10,6 +10,8 @@ import { Argument, Option } from 'commander'
 
 // Re-export shared option definitions
 export {
+  colorOption,
+  noColorOption,
   quietOption,
   verboseOption,
   debugOption,

package/src/lib/commander/options.js

@@ -124,6 +124,30 @@ export const debugOption = [
   { conflicts: ['quiet'] }
 ]
 
+/**
+ * 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)
  *

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 { quietOption, verboseOption, debugOption } from './options.js'
+import { colorOption, noColorOption, quietOption, verboseOption, debugOption } from './options.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Integration tests for option conflicts
@@ -16,6 +16,8 @@ import { quietOption, verboseOption, debugOption } from './options.js'
 function createTestProgram() {
   const program = new Command()
   program
+    .addOption(arrayToOption(colorOption))
+    .addOption(arrayToOption(noColorOption))
     .addOption(arrayToOption(quietOption))
     .addOption(arrayToOption(verboseOption))
     .addOption(arrayToOption(debugOption))
@@ -107,3 +109,46 @@ test('options order does not affect conflict detection', (t) => {
   t.throws(() => program1.parse(['node', 'test', '--quiet', '--verbose']))
   t.throws(() => program2.parse(['node', 'test', '--verbose', '--quiet']))
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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'])
+  })
+})

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/logger/index.js

@@ -162,7 +162,7 @@ export default function createLogger(name = 'quire', level) {
       const prefix = config.get('logPrefix')
       const prefixStyle = config.get('logPrefixStyle')
       const showLevel = config.get('logShowLevel')
-      const useColor = config.get('logUseColor')
+      const useColor = config.get('logUseColor') && !process.env.NO_COLOR
       const colorMessages = config.get('logColorMessages')
 
       const parts = []

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

@@ -475,3 +475,104 @@ test.serial('invalid env var value falls back to info', async (t) => {
     }
   }
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NO_COLOR environment variable tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.serial('logger disables color when NO_COLOR env var is set', async (t) => {
+  const { sandbox } = t.context
+  const consoleErrorStub = sandbox.stub(console, 'error')
+  const originalNoColor = process.env.NO_COLOR
+
+  try {
+    process.env.NO_COLOR = '1'
+
+    const mockConfig = {
+      get: sandbox.stub().callsFake((key) => ({
+        logPrefix: 'quire',
+        logPrefixStyle: 'bracket',
+        logShowLevel: true,
+        logUseColor: true, // Config says use color, but NO_COLOR overrides
+        logColorMessages: true,
+      })[key])
+    }
+
+    const { default: createLoggerMocked } = await esmock('./index.js', {
+      '#lib/conf/config.js': { default: mockConfig }
+    })
+
+    const log = createLoggerMocked('test:nocolor', 'error')
+    log.error('Error message')
+
+    t.true(consoleErrorStub.calledOnce)
+    const output = consoleErrorStub.firstCall.args.join(' ')
+    // Should not contain ANSI escape sequences when NO_COLOR is set
+    t.false(/\u001b\[/.test(output), 'output should not contain ANSI escape codes')
+    // Should still contain the actual text
+    t.true(output.includes('[quire]'))
+    t.true(output.includes('ERROR'))
+    t.true(output.includes('Error message'))
+  } finally {
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR
+    } else {
+      process.env.NO_COLOR = originalNoColor
+    }
+  }
+})
+
+test.serial('logger uses color when NO_COLOR env var is not set and config enables color', async (t) => {
+  const { sandbox } = t.context
+  const consoleErrorStub = sandbox.stub(console, 'error')
+  const originalNoColor = process.env.NO_COLOR
+
+  try {
+    delete process.env.NO_COLOR
+
+    const mockConfig = {
+      get: sandbox.stub().callsFake((key) => ({
+        logPrefix: 'quire',
+        logPrefixStyle: 'bracket',
+        logShowLevel: true,
+        logUseColor: true,
+        logColorMessages: true,
+      })[key])
+    }
+
+    // Create a mock chalk that always applies ANSI styling regardless of TTY/env
+    const ansiRed = (s) => `\u001b[91m${s}\u001b[39m`
+    const ansiRedInverse = (s) => `\u001b[91m\u001b[7m${s}\u001b[27m\u001b[39m`
+    const ansiBold = (s) => `\u001b[1m${s}\u001b[22m`
+    const mockChalk = {
+      bold: ansiBold,
+      gray: (s) => s,
+      yellow: (s) => s,
+      magenta: (s) => s,
+      red: ansiRed,
+      redBright: { inverse: ansiRedInverse },
+      'yellow.inverse': (s) => s,
+    }
+    // Support chained properties
+    mockChalk.yellow.inverse = (s) => s
+
+    const { default: createLoggerMocked } = await esmock('./index.js', {
+      '#lib/conf/config.js': { default: mockConfig },
+      'chalk': { default: mockChalk }
+    })
+
+    const log = createLoggerMocked('test:withcolor', 'error')
+    log.error('Error message')
+
+    t.true(consoleErrorStub.calledOnce)
+    const output = consoleErrorStub.firstCall.args.join(' ')
+    // Should contain ANSI escape sequences when color is enabled and NO_COLOR not set
+    t.true(/\u001b\[/.test(output), 'output should contain ANSI escape codes')
+  } finally {
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR
+    } else {
+      process.env.NO_COLOR = originalNoColor
+    }
+  }
+})

package/src/main.js

@@ -2,6 +2,8 @@ import { Command, Argument, Option } from 'commander'
 import {
   arrayToArgument,
   arrayToOption,
+  colorOption,
+  noColorOption,
   quietOption,
   verboseOption,
   debugOption
@@ -34,12 +36,20 @@ Output Modes:
 
   Set defaults: quire settings set verbose 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:
+  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
@@ -50,6 +60,8 @@ Examples:
   $ quire build                  Build the publication
   $ quire build --verbose        Build with detailed progress
   $ quire build --debug          Build with debug output
+  $ 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
 `
 
@@ -66,6 +78,8 @@ 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))
@@ -88,6 +102,8 @@ program
  * - --quiet: Suppress progress spinners (for CI/scripts)
  * - --verbose: Show detailed progress (paths, timing, steps)
  * - --debug: Enable DEBUG namespace + tool debug modes (for developers)
+ * - --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.
@@ -95,6 +111,16 @@ program
 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')) {