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

package/src/lib/README.md

@@ -0,0 +1,275 @@
+# CLI Library Modules
+
+This directory contains domain-specific modules that encapsulate the core functionality of the Quire CLI. Each module is designed around a single responsibility and provides a façade for its domain.
+
+## Architecture Overview
+
+```
+                            Commands Layer
+                ┌─────────────────────────────────────────┐
+                │  build  preview  new  pdf  epub  info   │
+                └──────────────────┬──────────────────────┘
+                                   │
+                ┌──────────────────┴──────────────────────┐
+                │              lib/ modules               │
+                └─────────────────────────────────────────┘
+
+     ┌─────────────────────────────────────────────────────────────────┐
+     │                        Domain Modules                           │
+     │  ┌────────────┐  ┌──────────┐  ┌────────────┐  ┌─────────────┐  │
+     │  │ project/   │  │  11ty/   │  │   pdf/     │  │   epub/     │  │
+     │  │            │  │          │  │            │  │             │  │
+     │  │ - paths    │  │ - api    │  │ - pagedjs  │  │ - epubjs    │  │
+     │  │ - config   │  │ - cli    │  │ - prince   │  │ - pandoc    │  │
+     │  │ - detect   │  │          │  │            │  │             │  │
+     │  │ - version  │  │          │  │            │  │             │  │
+     │  └────┬───────┘  └────┬─────┘  └────┬───────┘  └──────┬──────┘  │
+     └───────┼───────────────┼─────────────┼─────────────────┼─────────┘
+             │               │             │                 │
+             │      ┌────────┴─────────────┴─────────────────┘
+             │      │
+     ┌───────┴──────┴──────────────────────────────────────────────────┐
+     │                     Installation Module                         │
+     │  ┌──────────────────────────────────────────────────────────┐   │
+     │  │                      installer/                          │   │
+     │  │  - initStarter (clone starter, setup project)            │   │
+     │  │  - installInProject (install @thegetty/quire-11ty)       │   │
+     │  │  - latest (resolve version from npm)                     │   │
+     │  │  - versions (list published versions)                    │   │
+     │  └──────────────────────────────────────────────────────────┘   │
+     └───────────────────────────────┬─────────────────────────────────┘
+                                     │
+     ┌───────────────────────────────┴─────────────────────────────────┐
+     │                    Infrastructure Modules                       │
+     │  ┌────────┐  ┌────────┐  ┌────────┐  ┌─────────┐  ┌──────────┐  │
+     │  │  npm/  │  │  git/  │  │ conf/  │  │ error/  │  │ logger/  │  │
+     │  │        │  │        │  │        │  │         │  │          │  │
+     │  └────────┘  └────────┘  └────────┘  └─────────┘  └──────────┘  │
+     │  ┌───────────┐  ┌───────────┐                                   │
+     │  │ reporter/ │  │  ui/      │                                   │
+     │  │           │  │ (prompt)  │                                   │
+     │  └───────────┘  └───────────┘                                   │
+     └─────────────────────────────────────────────────────────────────┘
+```
+
+## Module Reference
+
+### Domain Modules
+
+These modules encapsulate specific business domains of Quire.
+
+#### `project/`
+**Purpose:** Project-level concerns including paths, detection, configuration, and version management.
+
+| Export | Description |
+|--------|-------------|
+| `paths` (default) | Singleton for path resolution |
+| `Paths` | Class for custom path instances |
+| `detect(dirpath)` | Check if directory is a Quire project |
+| `loadProjectConfig(projectRoot?)` | Load and validate project config |
+| `getVersion(projectPath?)` | Read `quire-11ty` version from project |
+| `setVersion(version, projectPath?)` | Write `quire-11ty` version to project |
+| `getVersionsFromStarter(projectPath)` | Read versions from starter package.json |
+| `readVersionFile(projectPath)` | Read raw version file contents |
+| `writeVersionFile(projectPath, info)` | Write version file contents |
+
+**Dependencies:** `conf/`, `fs-extra`
+
+#### `11ty/`
+**Purpose:** Eleventy build system integration via API or CLI.
+
+| Export | Description |
+|--------|-------------|
+| `api` | Programmatic Eleventy control |
+| `cli` | CLI-based Eleventy execution |
+| `paths` | Re-exported from `project/` |
+| `Paths` | Re-exported from `project/` |
+
+**Dependencies:** `project/`
+
+#### `pdf/`
+**Purpose:** PDF generation using Prince or Paged.js.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Factory returning configured PDF generator |
+
+**Implementations:** `prince.js`, `paged.js`
+
+**Dependencies:** `project/`
+
+#### `epub/`
+**Purpose:** EPUB generation using Pandoc.
+
+| Export | Description |
+|--------|-------------|
+| `default` | EPUB generator façade |
+
+**Dependencies:** `project/`
+
+#### `installer/`
+**Purpose:** Installation of `@thegetty/quire-11ty` into Quire projects.
+
+| Export | Description |
+|--------|-------------|
+| `installer` | Object with all installer methods |
+| `initStarter(starter, projectPath, options)` | Clone and setup starter project |
+| `installInProject(projectPath, version, options)` | Install `@thegetty/quire-11ty` package |
+| `latest(version?)` | Resolve version from npm registry |
+| `versions()` | List all published `@thegetty/quire-11ty` versions |
+
+**Dependencies:** `project/`, `npm/`, `git/`
+
+### Infrastructure Modules
+
+These modules provide cross-cutting concerns and external tool integrations.
+
+#### `npm/`
+**Purpose:** NPM operations façade.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Singleton npm façade |
+| `init(cwd, options?)` | Run `npm init` |
+| `install(cwd, options?)` | Run `npm install` |
+| `pack(spec, dest, options?)` | Run `npm pack` |
+| `cacheClean(cwd?)` | Run `npm cache clean` |
+| `view(pkg, field?)` | Query package info |
+| `show(pkg, field?)` | Query package versions |
+| `version()` | Get npm version |
+| `isAvailable()` | Check npm in PATH |
+| `fetchFromRegistry(pkg)` | Direct registry API call |
+| `getCompatibleVersion(pkg, range)` | Resolve semver range |
+
+**Dependencies:** `execa`, `node-fetch`
+
+#### `git/`
+**Purpose:** Git operations via simple-git.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Configured simple-git instance |
+
+**Dependencies:** `simple-git`
+
+#### `conf/`
+**Purpose:** CLI configuration persistence and schema-aware helpers.
+
+| 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)` | `helpers.js` | Get schema description for a key |
+| `formatSettings(store, options)` | `helpers.js` | Format all settings for display |
+
+Uses a barrel export (`index.js`) rather than a wrapper class to keep pure helper functions separate from the stateful `Conf` singleton. This avoids circular dependencies with the logger module and keeps helpers directly testable without mocking.
+
+**Dependencies:** `conf`
+
+#### `logger.js`
+**Purpose:** Logging abstraction.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Logger instance (loglevel) |
+
+**Dependencies:** `loglevel`
+
+#### `reporter/`
+**Purpose:** Progress reporting for long-running operations.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Reporter façade |
+
+#### `error/`
+**Purpose:** Centralized error handling and formatting.
+
+| Export | Description |
+|--------|-------------|
+| `formatError(error, options)` | Format error for display |
+| `handleError(error, options)` | Handle single error (format, log, exit) |
+| `handleErrors(errors, options)` | Handle multiple errors (batch validation) |
+
+**Features:**
+- Consistent error formatting with suggestion, docs URL, file path
+- Debug mode shows error codes and stack traces
+- Conditional `--debug` hint (controlled by `showDebugHint` property)
+- Exit code management per error category
+
+**Dependencies:** `logger/`
+
+#### `ui/`
+**Purpose:** Display and interactive prompt
+
+_Future feature: Not yet impemented._
+
+## Design Patterns
+
+### Singleton façade
+Most modules export a singleton instance as the default export:
+```javascript
+import npm from '#lib/npm/index.js'
+await npm.install('/path/to/project')
+```
+
+### Optional Parameters with Defaults
+Functions that operate on projects default to `cwd` when path not provided:
+```javascript
+// Uses current working directory
+setVersion('1.0.0')
+
+// Uses explicit path
+setVersion('1.0.0', '/path/to/project')
+```
+
+### Re-exports for Convenience
+Modules re-export commonly used dependencies:
+```javascript
+// 11ty/ re-exports paths from project/
+import { paths } from '#lib/11ty/index.js'
+```
+
+## Import Aliases
+
+Use these aliases for imports:
+
+| Alias | Path |
+|-------|------|
+| `#lib/` | `src/lib/` |
+| `#src/` | `src/` |
+| `#helpers/` | `src/helpers/` |
+
+Example:
+```javascript
+import npm from '#lib/npm/index.js'
+import { installer } from '#lib/installer/index.js'
+import paths, { loadProjectConfig } from '#lib/project/index.js'
+```
+
+## Testing
+
+Each module has associated test files:
+
+| Pattern | Purpose |
+|---------|---------|
+| `*.spec.js` | Unit tests (interface contracts) |
+| `*.test.js` | Integration tests (with mocked dependencies) |
+
+Tests use:
+- **AVA** for test runner
+- **esmock** for ESM module mocking
+- **sinon** for stubs and spies
+- **memfs** for in-memory filesystem
+
+## Adding a New Module
+
+1. Create directory: `lib/<module-name>/`
+2. Create entry point: `index.js` with façade pattern
+3. Export singleton or factory as default
+4. Add tests: `index.spec.js` and/or `index.test.js`
+5. Update this README with module documentation

package/src/lib/commander/index.js

@@ -0,0 +1,100 @@
+/**
+ * Commander.js utilities
+ *
+ * Provides helper functions for converting array-based definitions
+ * to Commander.js Argument and Option objects, plus shared option definitions.
+ *
+ * @module lib/commander
+ */
+import { Argument, Option } from 'commander'
+
+// Re-export shared option definitions
+export {
+  quietOption,
+  verboseOption,
+  debugOption,
+  outputModeOptions,
+  outputModeHelpText,
+  withOutputModes,
+} from './options.js'
+
+/**
+ * Convert array argument definition to Argument object
+ *
+ * @param {Array} entry - Argument definition array [name, description, { choices, default }]
+ * @returns {Argument} Commander Argument object
+ * @see https://github.com/tj/commander.js#more-configuration-1
+ *
+ * @example
+ * // Required argument
+ * arrayToArgument(['<version>', 'quire-11ty version to use'])
+ *
+ * @example
+ * // Optional argument with default
+ * arrayToArgument(['[starter]', 'starter template', { default: 'default' }])
+ */
+export function arrayToArgument(entry) {
+  const [name, description, config = {}] = entry
+  const argument = new Argument(name, description)
+  if (config.choices) argument.choices(config.choices)
+  if (config.default) argument.default(config.default)
+  return argument
+}
+
+/**
+ * Convert array option definition to Option object
+ *
+ * Supports two array formats:
+ * - Separate flags: ['-s', '--long <value>', 'description', default, { choices, default }]
+ * - Combined flags: ['--long <value>', 'description', default, { choices, default }]
+ *
+ * @param {Array} entry - Option definition array
+ * @returns {Option} Commander Option object
+ * @see https://github.com/tj/commander.js/#options
+ * @see https://github.com/tj/commander.js/#more-configuration
+ *
+ * @example
+ * // Long-only option
+ * arrayToOption(['--debug', 'enable debug output'])
+ *
+ * @example
+ * // Short and long flags
+ * arrayToOption(['-v', '--verbose', 'enable verbose output'])
+ *
+ * @example
+ * // Option with choices
+ * arrayToOption(['--lib <module>', 'library to use', { choices: ['a', 'b'], default: 'a' }])
+ */
+export function arrayToOption(entry) {
+  const lastElement = entry[entry.length - 1]
+  const configObj = typeof lastElement === 'object' && lastElement !== null ? lastElement : null
+
+  let flags, description, defaultValue
+  if (entry[0]?.startsWith('-') && entry[1]?.startsWith('--')) {
+    // Array has separate elements for short and long option flags
+    // @example ['-s', '--long <value>', 'desc', ...]
+    flags = `${entry[0]}, ${entry[1]}`
+    description = entry[2]
+    defaultValue = entry[3]
+  } else {
+    // Array has a single element with option flags
+    // @example ['--long <value>', 'desc', ...]
+    flags = entry[0]
+    description = entry[1]
+    defaultValue = entry[2]
+  }
+
+  const option = new Option(flags, description)
+
+  if (configObj) {
+    if (configObj.choices) option.choices(configObj.choices)
+    if (configObj.conflicts) option.conflicts(configObj.conflicts)
+    if (configObj.default !== undefined) option.default(configObj.default)
+    if (configObj.hidden) option.hideHelp()
+    if (configObj.implies) option.implies(configObj.implies)
+  } else if (defaultValue !== undefined) {
+    option.default(defaultValue)
+  }
+
+  return option
+}

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

@@ -0,0 +1,86 @@
+import test from 'ava'
+import { Argument, Option } from 'commander'
+import { arrayToArgument, arrayToOption } from './index.js'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// arrayToArgument tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('arrayToArgument creates Argument from basic array', (t) => {
+  const arg = arrayToArgument(['<version>', 'the version to use'])
+
+  t.true(arg instanceof Argument)
+  t.is(arg.name(), 'version')
+  t.is(arg.description, 'the version to use')
+  t.true(arg.required)
+})
+
+test('arrayToArgument creates optional Argument', (t) => {
+  const arg = arrayToArgument(['[starter]', 'starter template'])
+
+  t.true(arg instanceof Argument)
+  t.is(arg.name(), 'starter')
+  t.false(arg.required)
+})
+
+test('arrayToArgument applies choices from config', (t) => {
+  const arg = arrayToArgument(['<format>', 'output format', { choices: ['pdf', 'epub'] }])
+
+  t.true(arg instanceof Argument)
+  t.deepEqual(arg.argChoices, ['pdf', 'epub'])
+})
+
+test('arrayToArgument applies default from config', (t) => {
+  const arg = arrayToArgument(['[starter]', 'starter template', { default: 'default' }])
+
+  t.true(arg instanceof Argument)
+  t.is(arg.defaultValue, 'default')
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// arrayToOption tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('arrayToOption creates Option from combined flags', (t) => {
+  const opt = arrayToOption(['--debug', 'enable debug output'])
+
+  t.true(opt instanceof Option)
+  t.is(opt.long, '--debug')
+  t.is(opt.description, 'enable debug output')
+})
+
+test('arrayToOption creates Option from separate short/long flags', (t) => {
+  const opt = arrayToOption(['-v', '--verbose', 'enable verbose output'])
+
+  t.true(opt instanceof Option)
+  t.is(opt.short, '-v')
+  t.is(opt.long, '--verbose')
+  t.is(opt.description, 'enable verbose output')
+})
+
+test('arrayToOption applies choices from config object', (t) => {
+  const opt = arrayToOption([
+    '--lib <module>',
+    'library to use',
+    { choices: ['pagedjs', 'prince'], default: 'pagedjs' }
+  ])
+
+  t.true(opt instanceof Option)
+  t.deepEqual(opt.argChoices, ['pagedjs', 'prince'])
+  t.is(opt.defaultValue, 'pagedjs')
+})
+
+test('arrayToOption applies default from positional argument', (t) => {
+  const opt = arrayToOption(['--port <number>', 'port to use', 8080])
+
+  t.true(opt instanceof Option)
+  t.is(opt.defaultValue, 8080)
+})
+
+test('arrayToOption handles option with value placeholder', (t) => {
+  const opt = arrayToOption(['--output <path>', 'output directory'])
+
+  t.true(opt instanceof Option)
+  t.is(opt.long, '--output')
+  t.true(opt.required) // option requires a value
+})

package/src/lib/commander/options.js

@@ -0,0 +1,195 @@
+/**
+ * Shared option definitions for CLI commands
+ *
+ * Provides consistent option definitions that can be imported by commands.
+ * This ensures uniform help text, flags, and behavior across the CLI.
+ *
+ * ## Recommended Usage
+ *
+ * Use `withOutputModes()` to wrap your command definition:
+ *
+ * ```javascript
+ * import { withOutputModes } from '#lib/commander/index.js'
+ *
+ * export default class MyCommand extends Command {
+ *   static definition = withOutputModes({
+ *     name: 'my-command',
+ *     description: 'Do something useful',
+ *     helpText: `
+ * Examples:
+ *   quire my-command --verbose
+ * `,
+ *     options: [
+ *       ['--custom', 'my custom option'],
+ *     ],
+ *   })
+ * }
+ * ```
+ *
+ * This automatically adds --quiet, --verbose, --debug options and prepends
+ * the standard output mode help text.
+ *
+ * ## Selective Options
+ *
+ * For commands that need only specific output options:
+ *
+ * ```javascript
+ * import { quietOption, verboseOption } from '#lib/commander/index.js'
+ *
+ * options: [
+ *   quietOption,
+ *   verboseOption,
+ *   // No --debug for this command
+ * ]
+ * ```
+ *
+ * ## Commander.js Boolean Negation
+ *
+ * Boolean options automatically support negation via Commander.js.
+ * For example, `--verbose` automatically supports `--no-verbose`.
+ *
+ * This enables the config fallback pattern:
+ * - `--verbose` → options.verbose = true
+ * - `--no-verbose` → options.verbose = false
+ * - (no flag) → options.verbose = undefined (falls back to config)
+ *
+ * @see https://github.com/tj/commander.js#other-option-types-negatable-boolean-and-booleanvalue
+ * @module lib/commander/options
+ */
+
+/**
+ * Quiet mode option - suppress progress output
+ *
+ * Use for CI/CD pipelines and automated scripts where spinner
+ * output would clutter logs. Exit codes still indicate success/failure.
+ *
+ * Conflicts with --verbose and --debug since quiet mode suppresses
+ * the output those modes would show.
+ *
+ * @type {Array}
+ */
+export const quietOption = [
+  '-q, --quiet', 'suppress progress output',
+  { conflicts: ['verbose', 'debug'] }
+]
+
+/**
+ * Verbose mode option - show detailed progress
+ *
+ * Shows additional information like file paths, timing data,
+ * and step-by-step progress. Useful when users want more
+ * visibility into what the CLI is doing.
+ *
+ * Respects config default: `quire settings set verbose true`
+ * Conflicts with --quiet since quiet mode suppresses output.
+ *
+ * @type {Array}
+ */
+export const verboseOption = [
+  '-v, --verbose', 'show detailed progress output',
+  { conflicts: ['quiet'] }
+]
+
+/**
+ * Progress option - hidden alias for --verbose
+ *
+ * Provides a familiar `--progress` flag as an alternative to `--verbose`.
+ * Many users expect `--progress` to show detailed output during long-running
+ * operations like builds and file deletions.
+ *
+ * Hidden from help output since --verbose is the canonical flag.
+ * Uses `implies` to set verbose=true when --progress is used.
+ *
+ * @type {Array}
+ */
+const progressOption = [
+  '--progress', 'show detailed progress (alias for --verbose)',
+  { hidden: true, implies: { verbose: true } }
+]
+
+/**
+ * Debug mode option - enable debug output
+ *
+ * Enables the DEBUG=quire:* namespace for internal logging.
+ * Outputs technical debugging information intended for developers
+ * and maintainers troubleshooting issues.
+ *
+ * Respects config default: `quire settings set debug true`
+ * Conflicts with --quiet since quiet mode suppresses output.
+ *
+ * @type {Array}
+ */
+export const debugOption = [
+  '--debug', 'enable debug output for troubleshooting',
+  { conflicts: ['quiet'] }
+]
+
+/**
+ * Standard output mode options (quiet, verbose, debug, progress)
+ *
+ * Most commands should include all three options for consistent UX.
+ * Spread this array into your command's options:
+ *
+ * ```javascript
+ * options: [
+ *   ...outputModeOptions,
+ *   ['--my-option', 'custom option'],
+ * ]
+ * ```
+ *
+ * @type {string[][]}
+ */
+export const outputModeOptions = [
+  quietOption,
+  verboseOption,
+  progressOption,
+  debugOption,
+]
+
+/**
+ * Standard help text for output modes
+ *
+ * @type {string}
+ */
+export const outputModeHelpText = `Output Modes:
+  -q, --quiet      Suppress progress output (for CI/scripts)
+  -v, --verbose    Show detailed progress (paths, timing)
+  --progress       Alias for --verbose
+  --debug          Enable debug output for troubleshooting`
+
+/**
+ * Add output mode options to a command definition
+ *
+ * Injects --quiet, --verbose, --debug options and prepends the
+ * standard output mode help text to the command's helpText.
+ *
+ * @param {Object} definition - Command definition object
+ * @param {string} [definition.helpText] - Existing help text (output modes prepended)
+ * @param {Array} [definition.options] - Existing options (output modes appended)
+ * @returns {Object} Modified definition with output mode options
+ *
+ * @example
+ * static definition = withOutputModes({
+ *   name: 'build',
+ *   description: 'Generate publication outputs',
+ *   helpText: `
+ * Examples:
+ *   quire build --verbose
+ * `,
+ *   options: [
+ *     ['--custom', 'my option'],
+ *   ],
+ * })
+ */
+export function withOutputModes(definition) {
+  return {
+    ...definition,
+    helpText: definition.helpText
+      ? `\n${outputModeHelpText}\n${definition.helpText}`
+      : `\n${outputModeHelpText}`,
+    options: [
+      ...(definition.options || []),
+      ...outputModeOptions,
+    ],
+  }
+}