@thegetty/quire-cli 1.0.0-rc.35 → 1.0.0-rc.37

package/src/lib/conf/format.js

@@ -0,0 +1,60 @@
+/**
+ * Display formatting functions for Quire configuration
+ *
+ * Provides human-readable formatting with optional chalk styling.
+ * Separated from helpers.js to isolate the chalk dependency
+ * from the pure validation/coercion functions.
+ *
+ * @see ./helpers.js for schema-aware validation and coercion
+ */
+import chalk from 'chalk'
+import schema from './schema.js'
+
+/**
+ * Get the description for a configuration key from the schema
+ *
+ * @param {string} key - Configuration key
+ * @returns {string|undefined} Description string, or undefined if not found
+ */
+export function getKeyDescription(key) {
+  return schema[key]?.description
+}
+
+/**
+ * Format all settings as a human-readable string
+ *
+ * @param {Object} store - Configuration store (key-value pairs)
+ * @param {Object} [options]
+ * @param {string} [options.configPath] - Path to the config file (shown in header)
+ * @param {boolean} [options.showInternal=false] - Include __internal__ keys
+ * @param {boolean} [options.useColor=false] - Apply chalk styling to output
+ * @returns {string} Formatted multiline settings display
+ */
+export function formatSettings(store, { configPath, showInternal = false, useColor = false } = {}) {
+  const style = useColor
+    ? { bold: chalk.bold, cyan: chalk.cyan, dim: chalk.dim }
+    : { bold: (s) => s, cyan: (s) => s, dim: (s) => s }
+
+  const lines = []
+
+  if (configPath) {
+    lines.push(style.bold(`quire-cli configuration ${configPath}`))
+  } else {
+    lines.push(style.bold('quire-cli configuration'))
+  }
+  lines.push('')
+
+  for (const [key, value] of Object.entries(store)) {
+    if (key.startsWith('__internal__') && !showInternal) continue
+    const description = getKeyDescription(key)
+    lines.push(`  ${style.cyan(key)}: ${JSON.stringify(value)}`)
+    if (description) {
+      lines.push(`    ${style.dim(description)}`)
+    }
+  }
+
+  lines.push('')
+  lines.push(style.dim('Use "quire settings set <key> <value>" to change a setting'))
+
+  return lines.join('\n')
+}

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

@@ -0,0 +1,106 @@
+import test from 'ava'
+import chalk from 'chalk'
+import {
+  getKeyDescription,
+  formatSettings,
+} from './format.js'
+
+// =============================================================================
+// getKeyDescription
+// =============================================================================
+
+test('getKeyDescription returns description for known key', (t) => {
+  const desc = getKeyDescription('logLevel')
+  t.is(typeof desc, 'string')
+  t.true(desc.length > 0)
+})
+
+test('getKeyDescription returns undefined for unknown key', (t) => {
+  t.is(getKeyDescription('unknownKey'), undefined)
+})
+
+// =============================================================================
+// formatSettings (plain, useColor=false)
+// =============================================================================
+
+test('formatSettings includes header with config path', (t) => {
+  const output = formatSettings({}, { configPath: '/mock/path' })
+  t.true(output.includes('quire-cli configuration /mock/path'))
+})
+
+test('formatSettings includes header without config path', (t) => {
+  const output = formatSettings({})
+  t.true(output.includes('quire-cli configuration'))
+})
+
+test('formatSettings includes key-value pairs', (t) => {
+  const store = { logLevel: 'info', logShowLevel: false }
+  const output = formatSettings(store)
+  t.true(output.includes('logLevel: "info"'))
+  t.true(output.includes('logShowLevel: false'))
+})
+
+test('formatSettings includes schema descriptions', (t) => {
+  const store = { logLevel: 'info' }
+  const output = formatSettings(store)
+  const desc = getKeyDescription('logLevel')
+  t.true(output.includes(desc))
+})
+
+test('formatSettings hides __internal__ keys by default', (t) => {
+  const store = { logLevel: 'info', __internal__secret: 'hidden' }
+  const output = formatSettings(store)
+  t.false(output.includes('__internal__secret'))
+})
+
+test('formatSettings shows __internal__ keys with showInternal', (t) => {
+  const store = { logLevel: 'info', __internal__secret: 'hidden' }
+  const output = formatSettings(store, { showInternal: true })
+  t.true(output.includes('__internal__secret'))
+  t.true(output.includes('"hidden"'))
+})
+
+test('formatSettings includes help hint', (t) => {
+  const output = formatSettings({})
+  t.true(output.includes('Use "quire settings set <key> <value>" to change a setting'))
+})
+
+// =============================================================================
+// formatSettings (useColor=true)
+// =============================================================================
+
+test('formatSettings with useColor applies bold to header', (t) => {
+  const output = formatSettings({}, { useColor: true })
+  t.true(output.includes(chalk.bold('quire-cli configuration')))
+})
+
+test('formatSettings with useColor applies bold to header with path', (t) => {
+  const output = formatSettings({}, { useColor: true, configPath: '/mock/path' })
+  t.true(output.includes(chalk.bold('quire-cli configuration /mock/path')))
+})
+
+test('formatSettings with useColor applies cyan to key names', (t) => {
+  const store = { logLevel: 'info' }
+  const output = formatSettings(store, { useColor: true })
+  t.true(output.includes(chalk.cyan('logLevel')))
+})
+
+test('formatSettings with useColor applies dim to descriptions', (t) => {
+  const store = { logLevel: 'info' }
+  const output = formatSettings(store, { useColor: true })
+  const desc = getKeyDescription('logLevel')
+  t.true(output.includes(chalk.dim(desc)))
+})
+
+test('formatSettings with useColor applies dim to help hint', (t) => {
+  const output = formatSettings({}, { useColor: true })
+  t.true(output.includes(chalk.dim('Use "quire settings set <key> <value>" to change a setting')))
+})
+
+test('formatSettings without useColor does not apply ANSI codes', (t) => {
+  const store = { logLevel: 'info' }
+  const output = formatSettings(store)
+  // Plain output should not contain ANSI escape sequences
+  // eslint-disable-next-line no-control-regex
+  t.false(/\u001b\[/.test(output))
+})

package/src/lib/conf/helpers.js

@@ -0,0 +1,91 @@
+/**
+ * Pure helper functions for Quire configuration
+ *
+ * Provides schema-aware validation and coercion
+ * without side effects or dependencies on the Conf instance.
+ *
+ * Nota bene: these functions import only schema and defaults (pure data),
+ * avoiding circular dependencies with the logger module.
+ *
+ * @see ./format.js for display formatting functions
+ */
+import schema from './schema.js'
+import defaults from './defaults.js'
+
+/**
+ * Check whether a key is a valid configuration key
+ *
+ * @param {string} key - Configuration key to check
+ * @returns {boolean} True if the key exists in the schema
+ */
+export function isValidKey(key) {
+  return Object.hasOwn(schema, key)
+}
+
+/**
+ * Get all valid configuration keys
+ *
+ * @returns {string[]} Sorted array of valid configuration keys
+ */
+export function getValidKeys() {
+  return Object.keys(schema).sort()
+}
+
+/**
+ * Coerce a CLI string value to the appropriate type based on schema
+ *
+ * @param {string} key - Configuration key
+ * @param {string} value - String value from CLI input
+ * @returns {*} Coerced value matching the schema type
+ */
+export function coerceValue(key, value) {
+  const keySchema = schema[key]
+  if (!keySchema) return value
+
+  switch (keySchema.type) {
+    case 'boolean':
+      if (value === 'true' || value === '1') return true
+      if (value === 'false' || value === '0') return false
+      return value
+    case 'number': {
+      const num = Number(value)
+      return isNaN(num) ? value : num
+    }
+    default:
+      return value
+  }
+}
+
+/**
+ * Format a validation error with helpful information from the schema
+ *
+ * @param {string} key - Configuration key
+ * @param {*} value - The invalid value
+ * @returns {string} Formatted multiline error message
+ */
+export function formatValidationError(key, value) {
+  const keySchema = schema[key]
+  const lines = [`Invalid value for '${key}': ${JSON.stringify(value)}`]
+
+  if (keySchema) {
+    if (keySchema.enum) {
+      lines.push(`Valid values: ${keySchema.enum.join(', ')}`)
+    }
+    if (keySchema.description) {
+      lines.push(`Description: ${keySchema.description}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Get the default value for a configuration key
+ *
+ * @param {string} key - Configuration key
+ * @returns {*} Default value, or undefined if key has no default
+ */
+export function getDefault(key) {
+  return defaults[key]
+}
+

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

@@ -0,0 +1,136 @@
+import test from 'ava'
+import {
+  isValidKey,
+  getValidKeys,
+  coerceValue,
+  formatValidationError,
+  getDefault,
+} from './helpers.js'
+
+// =============================================================================
+// isValidKey
+// =============================================================================
+
+test('isValidKey returns true for a known schema key', (t) => {
+  t.true(isValidKey('logLevel'))
+})
+
+test('isValidKey returns true for all schema keys', (t) => {
+  const keys = getValidKeys()
+  for (const key of keys) {
+    t.true(isValidKey(key), `${key} should be valid`)
+  }
+})
+
+test('isValidKey returns false for an unknown key', (t) => {
+  t.false(isValidKey('nonExistentKey'))
+})
+
+test('isValidKey returns false for __internal__ prefixed keys', (t) => {
+  t.false(isValidKey('__internal__secretKey'))
+})
+
+// =============================================================================
+// getValidKeys
+// =============================================================================
+
+test('getValidKeys returns an array', (t) => {
+  const keys = getValidKeys()
+  t.true(Array.isArray(keys))
+  t.true(keys.length > 0)
+})
+
+test('getValidKeys returns sorted keys', (t) => {
+  const keys = getValidKeys()
+  const sorted = [...keys].sort()
+  t.deepEqual(keys, sorted)
+})
+
+test('getValidKeys includes expected keys', (t) => {
+  const keys = getValidKeys()
+  t.true(keys.includes('logLevel'))
+  t.true(keys.includes('quireVersion'))
+  t.true(keys.includes('projectTemplate'))
+})
+
+// =============================================================================
+// coerceValue
+// =============================================================================
+
+test('coerceValue coerces "true" to boolean true', (t) => {
+  t.is(coerceValue('logShowLevel', 'true'), true)
+})
+
+test('coerceValue coerces "false" to boolean false', (t) => {
+  t.is(coerceValue('logShowLevel', 'false'), false)
+})
+
+test('coerceValue coerces "1" to boolean true for boolean schema', (t) => {
+  t.is(coerceValue('logShowLevel', '1'), true)
+})
+
+test('coerceValue coerces "0" to boolean false for boolean schema', (t) => {
+  t.is(coerceValue('logShowLevel', '0'), false)
+})
+
+test('coerceValue passes through non-boolean string for boolean schema', (t) => {
+  t.is(coerceValue('logShowLevel', 'maybe'), 'maybe')
+})
+
+test('coerceValue passes through string values for string schema', (t) => {
+  t.is(coerceValue('logLevel', 'debug'), 'debug')
+})
+
+test('coerceValue passes through value for unknown key', (t) => {
+  t.is(coerceValue('unknownKey', 'someValue'), 'someValue')
+})
+
+// =============================================================================
+// formatValidationError
+// =============================================================================
+
+test('formatValidationError includes invalid value', (t) => {
+  const error = formatValidationError('logLevel', 'invalid')
+  t.true(error.includes("Invalid value for 'logLevel'"))
+  t.true(error.includes('"invalid"'))
+})
+
+test('formatValidationError includes valid enum values', (t) => {
+  const error = formatValidationError('logLevel', 'invalid')
+  t.true(error.includes('Valid values:'))
+  t.true(error.includes('info'))
+  t.true(error.includes('debug'))
+})
+
+test('formatValidationError includes description', (t) => {
+  const error = formatValidationError('logLevel', 'invalid')
+  t.true(error.includes('Description:'))
+})
+
+test('formatValidationError handles key without enum', (t) => {
+  const error = formatValidationError('logPrefix', 123)
+  t.true(error.includes("Invalid value for 'logPrefix'"))
+  t.false(error.includes('Valid values:'))
+})
+
+test('formatValidationError handles unknown key', (t) => {
+  const error = formatValidationError('unknownKey', 'value')
+  t.true(error.includes("Invalid value for 'unknownKey'"))
+})
+
+// =============================================================================
+// getDefault
+// =============================================================================
+
+test('getDefault returns default value for known key', (t) => {
+  t.is(getDefault('logLevel'), 'info')
+})
+
+test('getDefault returns default for boolean key', (t) => {
+  t.is(getDefault('logShowLevel'), false)
+})
+
+test('getDefault returns undefined for unknown key', (t) => {
+  t.is(getDefault('unknownKey'), undefined)
+})
+

package/src/lib/conf/index.js

@@ -0,0 +1,22 @@
+/**
+ * Quire configuration module
+ *
+ * Exports the singleton Conf instance as the default export
+ * and named helper functions for schema-aware operations.
+ *
+ * @example
+ * import config from '#lib/conf/index.js'
+ * import { isValidKey, coerceValue } from '#lib/conf/index.js'
+ */
+export { default as default } from './config.js'
+export {
+  isValidKey,
+  getValidKeys,
+  coerceValue,
+  formatValidationError,
+  getDefault,
+} from './helpers.js'
+export {
+  getKeyDescription,
+  formatSettings,
+} from './format.js'

package/src/lib/conf/schema.js

@@ -2,29 +2,74 @@
  * Quire configuration schema
  * @see https://github.com/sindresorhus/conf#schema
  *
- * Nota bene: schema default values will are overwritten by `defaults.js` values
+ * Nota bene: default values here are overwritten by values in defaults.js
  * @see https://github.com/sindresorhus/conf#defaults
  */
+import { schema as epubEngineSchema } from '#lib/epub/schema.js'
+import { schema as pdfEngineSchema } from '#lib/pdf/schema.js'
+
 export default {
+  debug: {
+    type: 'boolean',
+    description: 'Enable debug output by default (equivalent to --debug flag)'
+  },
+  epubEngine: epubEngineSchema,
+  pdfEngine: pdfEngineSchema,
   logLevel: {
-    type: 'string'
+    type: 'string',
+    enum: ['trace', 'debug', 'info', 'warn', 'error', 'silent'],
+    description: 'Minimum log level to display (trace, debug, info, warn, error, silent)'
+  },
+  logPrefix: {
+    type: 'string',
+    description: 'Prefix text shown before log messages'
+  },
+  logPrefixStyle: {
+    type: 'string',
+    enum: ['bracket', 'emoji', 'plain', 'none'],
+    description: 'Style for displaying the log prefix (bracket: [quire], emoji: 📖, plain: quire:, none: no prefix)'
+  },
+  logShowLevel: {
+    type: 'boolean',
+    description: 'Show log level label (INFO, WARN, etc.) in output'
+  },
+  logUseColor: {
+    type: 'boolean',
+    description: 'Use colored output for log messages'
+  },
+  logColorMessages: {
+    type: 'boolean',
+    description: 'Color message text by log level (e.g., red for errors). Requires logUseColor'
   },
   projectTemplate: {
-    type: 'string'
+    type: 'string',
+    format: 'uri',
+    description: 'URL of the default project template for quire new'
   },
   quire11tyPath: {
-    type: 'string'
+    type: 'string',
+    description: 'Path to the quire-11ty package (use "." for local development)'
   },
   quireVersion: {
-    type: 'string'
+    type: 'string',
+    description: 'Version of quire-11ty to use ("latest" or specific version)'
   },
   updateChannel: {
-    type: 'string'
+    type: 'string',
+    enum: ['stable', 'rc', 'beta', 'alpha'],
+    description: 'Release channel for updates (stable, rc, beta, alpha)'
   },
   updateInterval: {
-    type: 'string'
+    type: 'string',
+    enum: ['DAILY', 'WEEKLY', 'MONTHLY', 'NEVER'],
+    description: 'How often to check for updates (DAILY, WEEKLY, MONTHLY, NEVER)'
+  },
+  verbose: {
+    type: 'boolean',
+    description: 'Enable verbose output by default (equivalent to --verbose flag)'
   },
   versionFile: {
-    type: 'string'
+    type: 'string',
+    description: 'Filename used to identify Quire projects'
   }
 }

package/src/lib/epub/README.md

@@ -1,7 +1,138 @@
 ## CLI lib/EPUB Module
 
-This module implements a façade for EPUB e-book file format generation libries. The module exports a single method that accepts a `lib` option and delegates to a façade for the specified EPUB library.
+This module provides an abstraction for EPUB e-book generation across Epub.js and Pandoc. The exported function accepts a `lib` option and dynamically loads the corresponding engine façade.
+
+### Architecture
+
+```
+┌───────────────────────────────────────────────────────────┐
+│                lib/epub/index.js (Façade)                 │
+│  • Resolve engine (epubjs/pandoc)                         │
+│  • Check engine availability (fail-fast)                  │
+│  • Resolve output path (CLI > default)                    │
+│  • Own reporter lifecycle (start/succeed/fail)            │
+│  • Dynamic import of engine implementation                │
+└───────────────────────────┬───────────────────────────────┘
+                            │
+              ┌─────────────┴─────────────────┐
+              │     lib/epub/engines.js       │
+              │  • Central engine registry    │
+              │  • Metadata (name, binary,    │
+              │    toolInfo for errors)       │
+              └─────────────┬─────────────────┘
+                            │
+           ┌────────────────┴────────────────────┐
+           │                                     │
+┌──────────▼───────────┐             ┌───────────▼────────────┐
+│  lib/epub/epub.js    │             │  lib/epub/pandoc.js    │
+│  • Epub.js wrapper   │             │  • Pandoc CLI wrapper  │
+│  • Load manifest     │             │  • Filter XHTML files  │
+│  • Generate EPUB     │             │  • Invoke pandoc       │
+│  • Write file        │             │  • Write file          │
+└──────────────────────┘             └────────────────────────┘
+```
+
+### Usage
+
+```javascript
+import generateEpub from '#lib/epub/index.js'
+
+// Generate EPUB with Epub.js (default)
+const output = await generateEpub({
+  lib: 'epubjs',
+  output: 'my-book.epub',
+  reporter,
+})
+
+// Generate EPUB with Pandoc
+const output = await generateEpub({
+  lib: 'pandoc',
+  output: 'my-book.epub',
+  reporter,
+})
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `lib` | string | `'epubjs'` | Engine to use: `'epubjs'` or `'pandoc'` |
+| `output` | string | `'{lib}.epub'` | Output file path |
+| `reporter` | object | required | Reporter instance for progress messages |
+| `debug` | boolean | `false` | Enable debug output |
+
+### Output Path Resolution
+
+The output path is resolved in priority order:
+1. CLI `--output` option value
+2. Default: `{lib}.epub` (e.g., `epubjs.epub` or `pandoc.epub`)
+
+Relative paths are resolved against the project root. The `.epub` extension is auto-added if missing.
 
 ### Epub.js Façade
 
-See the [`Epub.js` documentation](https://github.com/futurepress/epub.js).
+Wraps the [`epubjs-cli`](https://github.com/futurepress/epubjs-cli) package for EPUB generation.
+
+**How it works:**
+1. Loads `manifest.json` from the build output directory
+2. Uses `ManifestToEpub` to generate the EPUB content
+3. Writes the generated file to the output path
+
+See the [Epub.js documentation](https://github.com/futurepress/epub.js) for more details.
+
+### Pandoc Façade
+
+Wraps the [Pandoc](https://pandoc.org/) command-line tool for EPUB generation.
+
+**How it works:**
+1. Filters XHTML files from the build output
+2. Invokes `pandoc` with appropriate options
+3. Writes the generated EPUB to the output path
+
+**Requirements:** Pandoc must be installed and available in PATH.
+
+See the [Pandoc documentation](https://pandoc.org/MANUAL.html#creating-epubs-with-pandoc) for EPUB-specific options.
+
+### Engine Availability Check
+
+The façade performs a fail-fast check before starting the reporter:
+
+```javascript
+// Runs BEFORE reporter.start()
+checkEngineAvailable(engine)  // Throws ToolNotFoundError if binary missing
+```
+
+- **Epub.js:** No binary check needed (pure JavaScript)
+- **Pandoc:** Checks for `pandoc` in PATH
+
+If the engine is unavailable, a `ToolNotFoundError` is thrown with:
+- Install URL for the missing tool
+- Fallback suggestion (use default engine)
+- Link to documentation
+
+### Error Handling
+
+The module uses typed errors for consistent error handling:
+
+| Error | When Thrown |
+|-------|-------------|
+| `InvalidEpubLibraryError` | Unknown engine name provided |
+| `EpubGenerationError` | Generation fails (with tool/operation context) |
+| `ToolNotFoundError` | Required binary not found in PATH |
+
+### Test Strategy
+
+| Component | Test Type | Coverage |
+|-----------|-----------|----------|
+| `commands/epub.js` | spec + integration | CLI interface, option handling |
+| `lib/epub/index.js` | integration | Façade logic, path resolution, engine dispatch |
+| `lib/epub/epub.js` | E2E | Happy path via full generation |
+| `lib/epub/pandoc.js` | E2E | Happy path via full generation |
+
+The engine implementations (`epub.js`, `pandoc.js`) are thin wrappers with limited logic, so E2E tests provide sufficient coverage. Error path tests would have lower ROI compared to the PDF module's `split.js`.
+
+### Related Documentation
+
+- [EPUB Command](../../commands/epub.js) - CLI command implementation
+- [Reporter Pattern](../reporter/README.md) - Progress reporting ownership
+- [Error Classes](../../errors/output/) - Typed error definitions

package/src/lib/epub/engines.js

@@ -0,0 +1,46 @@
+/**
+ * EPUB Engine Registry
+ *
+ * Centralized metadata for EPUB engines. Each engine module re-exports
+ * its metadata from here, ensuring single source of truth.
+ *
+ * The façade imports this registry to:
+ * 1. Resolve engine names to implementations
+ * 2. Check binary availability before loading heavy modules
+ * 3. Provide helpful error messages with install URLs
+ */
+import QuireError from '#src/errors/quire-error.js'
+
+/**
+ * @typedef {Object} EngineMetadata
+ * @property {string} name - Human-readable display name
+ * @property {string} module - Module filename (e.g., 'epub.js')
+ * @property {string|null} requiresBinary - CLI binary name, or null if built-in
+ * @property {Object} [toolInfo] - Error metadata (only for engines requiring binaries)
+ * @property {string} [toolInfo.displayName] - Display name for error messages
+ * @property {string} [toolInfo.installUrl] - URL to download the tool
+ * @property {string} [toolInfo.docsUrl] - Quire docs URL
+ * @property {string} [toolInfo.fallback] - Alternative suggestion
+ */
+
+/** @type {Record<string, EngineMetadata>} */
+const ENGINES = {
+  epubjs: {
+    name: 'Epub.js',
+    module: 'epub.js',
+    requiresBinary: null, // Built-in Node.js library
+  },
+  pandoc: {
+    name: 'Pandoc',
+    module: 'pandoc.js',
+    requiresBinary: 'pandoc',
+    toolInfo: {
+      displayName: 'Pandoc',
+      installUrl: 'https://pandoc.org/installing.html',
+      docsUrl: `${QuireError.DOCS_BASE}/epub-output/`,
+      fallback: 'Or use the default EPUB engine: quire epub --engine epubjs',
+    },
+  },
+}
+
+export default ENGINES