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

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

@@ -0,0 +1,109 @@
+import test from 'ava'
+import { Command } from 'commander'
+import { arrayToOption } from './index.js'
+import { quietOption, verboseOption, debugOption } 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(quietOption))
+    .addOption(arrayToOption(verboseOption))
+    .addOption(arrayToOption(debugOption))
+    .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']))
+})

package/src/lib/conf/README.md

@@ -1,104 +1,115 @@
-## CLI Configuration Manager
+## CLI Configuration Module
 
-This `quire-cli/lib/config` module manages reading and writing (persisting) options for the Quire CLI using the [`conf`](https://github.com/sindresorhus/conf) package.
+The `conf/` module manages reading and writing (persisting) settings for the Quire CLI using the [`conf`](https://github.com/sindresorhus/conf) package.
 
 `conf` stores the config in the system default [user config directory](https://github.com/sindresorhus/env-paths#pathsconfig). For example, on macOS, the config file will be stored in the `~/Library/Preferences/@thegetty/quire-cli` directory.
 
 > Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config.
 
-### Configuration
+### Module Structure
 
-`logLevel` The default logging level for the Quire CLI output; default `'info'`.
-
-`projectTemplate` A default project starter template to use when creating new projects; default `'quire-starter-default'`.
-
-`quirePath` The relative path to `quire-11ty` installed in the project directory; default `./11ty`. When set to `null`, `quire-11ty` is installed to the CLI `lib/quire/versions/<version>/` directory.
-
-```sh
-❯ quire config quire-path '.'
 ```
-
-`quireVersion` The default version of `quire-11ty` to install when creating new Quire projects; default `'latest'`.
-
-```sh
-❯ quire config quire-version '1.0.0'
+conf/
+├── index.js         Barrel export (config singleton + helpers + format)
+├── config.js        Conf singleton instance
+├── helpers.js       Pure schema-aware validation and coercion
+├── format.js        Display formatting with optional chalk styling
+├── defaults.js      Default configuration values
+├── schema.js        JSON Schema definitions
+├── migrations.js    Version migration functions
+├── config.test.js   Integration tests for Conf instance
+├── helpers.test.js  Unit tests for validation/coercion helpers
+└── format.test.js   Unit tests for display formatting
 ```
 
-`telemetry` Send anonymous data about Quire usage; default `false`.
-
-```sh
-❯ quire config telemetry --enabled
-```
+### Architecture: Barrel Export vs Singleton Wrapper
 
-```sh
-❯ quire config telemetry --disabled
-```
+The module uses a **barrel export** pattern (`index.js`) rather than wrapping the `Conf` singleton in a class. This is a deliberate design choice:
 
-`updateChannels` A list of distribution tags to use when checking for version updates; default `['latest']`. To show notifications for pre-releases version updates include `'pre-release'` in the array of channels. This can be set using the configuration `--pre-release` command flag.
+- **`config.js`** exports the `Conf` singleton that owns mutable state (the on-disk JSON store, file watching, schema validation, migrations). This is a thin wrapper around the `conf` package.
+- **`helpers.js`** exports pure functions (`isValidKey`, `coerceValue`, `formatValidationError`, etc.) for schema-aware validation and coercion. These import only `schema.js` and `defaults.js` (pure data), keeping them free of transitive dependencies.
+- **`format.js`** exports display formatting functions (`formatSettings`, `getKeyDescription`) that depend on `chalk` for optional coloured output. Separated from `helpers.js` to isolate the chalk dependency from the pure validation/coercion functions.
+- **`index.js`** re-exports all three, providing a single import path for consumers.
 
-```sh
-❯ quire config update-channels
-Quire configured to check for updates tagged 'latest'
-```
+A wrapper class was considered but rejected for three reasons:
 
-```sh
-❯ quire config update-channels --add 'pre-release'
-Quire configured to check for updates tagged 'latest', 'pre-release'
-```
+1. **No shared state.** The helpers operate on schema/defaults (static data), not the config store (runtime state). Binding them to the singleton would create a false coupling.
+2. **Circular dependency avoidance.** The logger imports `config.js`. If helpers were methods on the config singleton, importing them would trigger the full `Conf` instantiation chain. By depending only on `schema.js` and `defaults.js` (pure data modules), `helpers.js` stays free of transitive dependencies.
+3. **Testability.** Pure functions are directly testable with simple import + assert — no esmock, no sinon, no constructor stubbing. Compare `helpers.test.js` (pure function tests) with `config.test.js` (integration tests requiring esmock to mock the `Conf` constructor).
 
-```sh
-❯ quire config update-channels --rm 'pre-release'
-Quire configured to check for updates tagged 'latest'
-```
+### Exports
 
-`updateInterval` Interval at which to check for updates to the Quire CLI and project's `quire-11ty` version; default `'DAILY'`.
+```javascript
+// Barrel import — config singleton + named helpers
+import config, { isValidKey, coerceValue } from '#lib/conf/index.js'
 
-```sh
-❯ quire config update-interval
-Quire configured to check for updates DAILY
+// Direct import — config singleton only (used by logger, etc.)
+import config from '#lib/conf/config.js'
 ```
 
-```sh
-❯ quire config update-interval WEEKLY
-```
+| Export | Source | Description |
+|--------|--------|-------------|
+| `default` | `config.js` | `Conf` singleton instance |
+| `isValidKey(key)` | `helpers.js` | Check if key exists in schema |
+| `getValidKeys()` | `helpers.js` | Sorted array of all schema keys |
+| `coerceValue(key, value)` | `helpers.js` | Coerce CLI string to schema type |
+| `formatValidationError(key, value)` | `helpers.js` | Format error with enum/description hints |
+| `getDefault(key)` | `helpers.js` | Get default value for a key |
+| `getKeyDescription(key)` | `format.js` | Get schema description for a key |
+| `formatSettings(store, options)` | `format.js` | Format all settings for display (with optional chalk styling) |
 
-`versionFile ['.quire-version']` The default file name for the `quire-11ty` version file.
+### Display Formatting
 
-```sh
-❯ quire config version-file '.blargh'
-```
+`formatSettings` accepts an options object controlling output:
 
-### Quire CLI `config` Command
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `configPath` | string | — | Path shown in header (e.g. `quire-cli configuration /path/to/config`) |
+| `showInternal` | boolean | `false` | Include `__internal__`-prefixed keys |
+| `useColor` | boolean | `false` | Apply chalk styling (bold header, cyan keys, dim descriptions) |
 
-Running the `config` command without any arguments will start an interactive prompt to configure Quire.
+When `useColor` is `true`, output uses:
+- **Bold** for the header line
+- **Cyan** for key names
+- **Dim** for descriptions and the help hint
 
-To view an individual configuration value and its default value use:
+When `useColor` is `false` (default), no ANSI escape codes are emitted.
 
-```sh
-❯ quire config [key]
-```
+The settings command reads `logUseColor` from the config to determine whether to pass `useColor: true`.
 
-To view the current `logLevel` setting for example:
+### Settings Reference
 
-```sh
-❯ quire config logLevel
-loglevel: 'debug' (default 'info')
-```
-
-To set an individual configuration value, use the `set` argument:
-
-```sh
-❯ quire config set <key> <value>
-```
-
-To reset *all* keys to their default values, use the `reset` argument:
+Use `quire settings` to view all settings with descriptions, or manage individual values:
 
 ```sh
-❯ quire config reset
+quire settings                     # Show all settings (coloured if logUseColor is true)
+quire settings get <key>           # Get a single value
+quire settings set <key> <value>   # Set a value
+quire settings delete <key>        # Delete (reset to default)
+quire settings reset [key]         # Reset all or single key
+quire settings path                # Show settings file path
+quire settings --json              # Output all settings as JSON
+quire settings get <key> --json    # Output single value as JSON
+quire settings --json --debug      # Include __internal__ keys in JSON output
 ```
 
-To reset an individual key to its default value:
-
-```sh
-❯ quire config reset [key]
-```
+The `--json` flag outputs raw JSON to stdout (bypassing the logger), suitable for piping to `jq` or other tools. `__internal__` keys are excluded from JSON output unless `--debug` is also passed, consistent with the plain-text display.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `debug` | boolean | `false` | Enable debug output by default |
+| `epubEngine` | string | `'epubjs'` | EPUB engine (`epubjs`, `pandoc`) |
+| `logLevel` | string | `'info'` | Log level (`trace`, `debug`, `info`, `warn`, `error`, `silent`) |
+| `logPrefix` | string | `'quire'` | Prefix text for log messages |
+| `logPrefixStyle` | string | `'bracket'` | Prefix style (`bracket`, `emoji`, `plain`, `none`) |
+| `logShowLevel` | boolean | `false` | Show level label in output |
+| `logUseColor` | boolean | `true` | Use colored output |
+| `logColorMessages` | boolean | `true` | Color message text by level |
+| `pdfEngine` | string | `'pagedjs'` | PDF engine (`pagedjs`, `prince`) |
+| `projectTemplate` | string | (GitHub URL) | Default starter template |
+| `quire11tyPath` | string | `'.'` | Path to quire-11ty package |
+| `quireVersion` | string | `'latest'` | Version of quire-11ty to install |
+| `updateChannel` | string | `'rc'` | Release channel (`stable`, `rc`, `beta`, `alpha`) |
+| `updateInterval` | string | `'DAILY'` | Update check frequency (`DAILY`, `WEEKLY`, `MONTHLY`, `NEVER`) |
+| `verbose` | boolean | `false` | Enable verbose output by default |
+| `versionFile` | string | `'.quire'` | Filename to identify Quire projects |

package/src/lib/conf/config.js

@@ -1,14 +1,16 @@
 import Conf from 'conf'
+import packageConfig from '#src/packageConfig.js'
 import defaults from './defaults.js'
 import migrations from './migrations.js'
-import packageConfig from '#src/packageConfig.js'
 import schema from './schema.js'
 
 const { name, version } = packageConfig
 
-const beforeEachMigration = (store, context) => {
+const beforeEachMigration = (_store, context) => {
   const { fromVersion, toVersion } = context
-  console.info(`quire-cli migrating config from ${fromVersion} → ${toVersion}`)
+  // Call console directly to avoid circular dependency (logger imports config)
+  // Migration messages are rare, so the simpler formatting is acceptable
+  console.info(`[quire] Migrating config from ${fromVersion} → ${toVersion}`)
 }
 
 /**

package/src/lib/conf/config.test.js

@@ -0,0 +1,281 @@
+import esmock from 'esmock'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Configuration Module Integration Tests
+ *
+ * Tests the Quire CLI configuration module behavior with mocked dependencies.
+ * Uses esmock to isolate the module from the actual Conf library and filesystem.
+ */
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration instantiation tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('config is created with correct project name and version', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    '#src/packageConfig.js': { name: '@thegetty/quire-cli', version: '1.0.0' }
+  })
+
+  t.true(MockConf.calledOnce)
+  t.is(capturedOptions.projectName, '@thegetty/quire-cli')
+  t.is(capturedOptions.projectVersion, '1.0.0')
+  t.is(capturedOptions.projectSuffix, '')
+})
+
+test('config is created with correct options', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  t.true(capturedOptions.clearInvalidConfig)
+  t.true(capturedOptions.watch)
+  t.is(typeof capturedOptions.beforeEachMigration, 'function')
+})
+
+test('config passes defaults to Conf constructor', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  const mockDefaults = {
+    logLevel: 'debug',
+    quireVersion: '2.0.0'
+  }
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    './defaults.js': { default: mockDefaults },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  t.deepEqual(capturedOptions.defaults, mockDefaults)
+})
+
+test('config passes schema to Conf constructor', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  const mockSchema = {
+    logLevel: { type: 'string' },
+    quireVersion: { type: 'string' }
+  }
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    './schema.js': { default: mockSchema },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  t.deepEqual(capturedOptions.schema, mockSchema)
+})
+
+test('config passes migrations to Conf constructor', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  const mockMigrations = {
+    '1.0.0': () => {},
+    '2.0.0': () => {}
+  }
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    './migrations.js': { default: mockMigrations },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  t.deepEqual(capturedOptions.migrations, mockMigrations)
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Migration callback tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.serial('beforeEachMigration logs migration info', async (t) => {
+  const { sandbox } = t.context
+
+  let capturedOptions = null
+  const MockConf = sandbox.stub().callsFake(function (options) {
+    capturedOptions = options
+    return {
+      get: sandbox.stub(),
+      set: sandbox.stub()
+    }
+  })
+
+  const consoleInfoStub = sandbox.stub(console, 'info')
+
+  await esmock('./config.js', {
+    conf: { default: MockConf },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  // Call the beforeEachMigration callback
+  const mockStore = { get: sandbox.stub(), set: sandbox.stub() }
+  const mockContext = { fromVersion: '0.9.0', toVersion: '1.0.0' }
+  capturedOptions.beforeEachMigration(mockStore, mockContext)
+
+  t.true(consoleInfoStub.calledOnce)
+  t.true(consoleInfoStub.firstCall.args[0].includes('0.9.0'))
+  t.true(consoleInfoStub.firstCall.args[0].includes('1.0.0'))
+  t.true(consoleInfoStub.firstCall.args[0].includes('Migrating'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Module export tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('config module exports Conf instance as default', async (t) => {
+  const { sandbox } = t.context
+
+  const mockInstance = {
+    get: sandbox.stub().returns('value'),
+    set: sandbox.stub(),
+    has: sandbox.stub().returns(true),
+    delete: sandbox.stub()
+  }
+
+  const MockConf = sandbox.stub().returns(mockInstance)
+
+  const config = await esmock('./config.js', {
+    conf: { default: MockConf },
+    '#src/packageConfig.js': { name: 'test', version: '1.0.0' }
+  })
+
+  t.is(config.default, mockInstance)
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default values tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('defaults module exports expected configuration keys', async (t) => {
+  const defaults = await import('./defaults.js')
+
+  t.true('logLevel' in defaults.default)
+  t.true('projectTemplate' in defaults.default)
+  t.true('quire11tyPath' in defaults.default)
+  t.true('quireVersion' in defaults.default)
+  t.true('updateChannel' in defaults.default)
+  t.true('updateInterval' in defaults.default)
+  t.true('versionFile' in defaults.default)
+})
+
+test('defaults module has reasonable default values', async (t) => {
+  const defaults = await import('./defaults.js')
+
+  t.is(defaults.default.logLevel, 'info')
+  t.is(defaults.default.quireVersion, 'latest')
+  t.is(defaults.default.versionFile, '.quire')
+  t.true(defaults.default.projectTemplate.includes('github.com'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('schema module defines types for all default keys', async (t) => {
+  const schema = await import('./schema.js')
+  const defaults = await import('./defaults.js')
+
+  const schemaKeys = Object.keys(schema.default)
+  const defaultKeys = Object.keys(defaults.default)
+
+  // All default keys should have schema definitions
+  for (const key of defaultKeys) {
+    t.true(schemaKeys.includes(key), `Schema should define ${key}`)
+  }
+})
+
+test('schema module defines valid types for all properties', async (t) => {
+  const schema = await import('./schema.js')
+
+  const validTypes = ['string', 'boolean', 'number', 'object', 'array']
+  for (const [key, value] of Object.entries(schema.default)) {
+    t.true(validTypes.includes(value.type), `${key} should have a valid type`)
+  }
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Migrations tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('migrations module exports migration functions', async (t) => {
+  const migrations = await import('./migrations.js')
+
+  t.is(typeof migrations.default, 'object')
+  t.true('1.0.0' in migrations.default)
+})
+
+test('migrations 1.0.0 sets updateChannel', async (t) => {
+  const { sandbox } = t.context
+
+  const migrations = await import('./migrations.js')
+
+  const mockStore = {
+    get: sandbox.stub(),
+    set: sandbox.stub()
+  }
+
+  migrations.default['1.0.0'](mockStore)
+
+  t.true(mockStore.set.calledOnce)
+  t.true(mockStore.set.calledWith('updateChannel', 'latest'))
+})

package/src/lib/conf/defaults.js

@@ -5,10 +5,49 @@
  * @see https://github.com/sindresorhus/conf#defaults
  */
 export default {
+  /**
+   * Enable debug output by default (DEBUG=quire:* namespace logging).
+   * Can be overridden per-command with --debug or --no-debug.
+   */
+  debug: false,
+  /**
+   * Default EPUB engine for quire epub command.
+   */
+  epubEngine: 'epubjs',
   /**
    * Logging level for the Quire CLI output.
    */
   logLevel: 'info',
+  /**
+   * Prefix text for log output messages.
+   */
+  logPrefix: 'quire',
+  /**
+   * Style of the log prefix.
+   * - 'bracket': [quire] message
+   * - 'emoji': 📖 message
+   * - 'plain': quire: message
+   * - 'none': message (no prefix)
+   */
+  logPrefixStyle: 'bracket',
+  /**
+   * Whether to show log level labels (INFO, WARN, ERROR).
+   * Defaults to false for cleaner user output.
+   */
+  logShowLevel: false,
+  /**
+   * Whether to use colored output in terminal.
+   */
+  logUseColor: true,
+  /**
+   * Whether to color message text by log level (e.g., red for errors).
+   * Requires logUseColor to be enabled.
+   */
+  logColorMessages: true,
+  /**
+   * Default PDF engine for quire pdf command.
+   */
+  pdfEngine: 'pagedjs',
   /**
    * Project starter template to use when creating new projects.
    */
@@ -30,6 +69,11 @@ export default {
    * and to quire-11ty version for a prject.
    */
   updateInterval: 'DAILY',
+  /**
+   * Enable verbose output by default (detailed progress with paths, timing).
+   * Can be overridden per-command with --verbose or --no-verbose.
+   */
+  verbose: false,
   /**
    * File name for the quire-11ty version file.
    */