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

package/src/lib/epub/schema.js

@@ -0,0 +1,21 @@
+/**
+ * EPUB engine schema definition
+ *
+ * This module has NO imports to avoid circular dependencies.
+ * It serves as the single source of truth for EPUB engine options.
+ */
+
+/**
+ * Supported EPUB engines
+ * @type {string[]}
+ */
+export const ENGINES = ['epubjs', 'pandoc']
+
+/**
+ * Schema definition for epubEngine config property
+ */
+export const schema = {
+  type: 'string',
+  enum: ENGINES,
+  description: 'Default EPUB engine to use (epubjs, pandoc)'
+}

package/src/lib/error/README.md

@@ -0,0 +1,170 @@
+# Error Handler
+
+Centralized error handling for the Quire CLI. All command errors flow through this handler for consistent formatting and exit code management.
+
+## Usage
+
+```javascript
+import { handleError, handleErrors, formatError } from '#lib/error/handler.js'
+
+try {
+  await someOperation()
+} catch (error) {
+  handleError(error, { debug: options.debug })
+}
+```
+
+## API
+
+### `formatError(error, options)`
+
+Formats a QuireError for user display.
+
+**Parameters:**
+- `error` - The error to format (QuireError or Error)
+- `options.debug` - Include error code in output (default: `false`)
+
+**Returns:** Formatted string with error message and metadata.
+
+**Output format:**
+```
+[ERROR_CODE] Message                    # Code shown only in debug mode
+  File: /path/to/file                   # If error.filePath is set
+  Suggestion: Actionable fix            # If error.suggestion is set
+  Learn more: https://docs.url          # If error.docsUrl is set
+  Tip: Run with --debug for more details  # If not in debug mode and showDebugHint !== false
+```
+
+### `handleError(error, options)`
+
+Handles a single error: formats it, logs it, and exits.
+
+**Parameters:**
+- `error` - The error to handle
+- `options.exit` - Whether to exit process (default: `true`)
+- `options.exitFn` - Exit function for testing (default: `process.exit`)
+- `options.debug` - Show stack traces (default: `false`)
+
+**Returns:** Exit code (number)
+
+**Behavior:**
+- QuireError: Uses structured properties (code, exitCode, suggestion, docsUrl)
+- Other errors: Shows as "Unexpected error" with issue report link
+
+### `handleErrors(errors, options)`
+
+Handles multiple errors (for batch validation scenarios).
+
+**Parameters:** Same as `handleError`, but takes array of errors.
+
+**Returns:** Highest exit code from all errors.
+
+## Debug Mode
+
+When `--debug` is enabled:
+- Error codes are shown in the header (e.g., `[TOOL_NOT_FOUND]`)
+- Stack traces are printed after the error message
+- The "Tip: Run with --debug" hint is suppressed
+
+## Debug Hint Control
+
+By default, errors display a tip suggesting the user run with `--debug` for more details. This can be disabled for errors where the fix is obvious and debug info wouldn't help.
+
+### Disabling the hint
+
+Set `showDebugHint: false` in the error options:
+
+```javascript
+class NotInProjectError extends QuireError {
+  constructor(commandName) {
+    super(`Must run inside a Quire project`, {
+      code: 'NOT_IN_PROJECT',
+      suggestion: "Navigate to your project folder with 'cd your-project-name'",
+      showDebugHint: false  // Fix is obvious, debug won't help
+    })
+  }
+}
+```
+
+### When to disable
+
+Disable the hint for "simple user errors" where:
+- The fix is immediately obvious from the message
+- Debug output wouldn't provide additional useful information
+- The user just needs to take a simple corrective action
+
+**Examples of errors with hint disabled:**
+- `NotInProjectError` - just cd to project folder
+- `DirectoryNotEmptyError` - choose empty directory
+- `InvalidPathError` - verify path exists
+- `MissingBuildOutputError` - run `quire build` first
+- `InvalidPdfLibraryError` - use valid library name
+- `InvalidEpubLibraryError` - use valid library name
+
+### When to keep the hint
+
+Keep the hint (default) for errors where:
+- The issue may be complex or environmental
+- Stack traces or debug logging would help diagnosis
+- The user may need to report a bug
+
+**Examples of errors with hint enabled (default):**
+- `BuildFailedError` - complex build issues
+- `PdfGenerationError` - tool/process issues
+- `EpubGenerationError` - tool/process issues
+- `ToolNotFoundError` - PATH/environment issues
+- `DependencyInstallError` - npm issues
+- Configuration and YAML validation errors
+
+## QuireError Properties
+
+The handler understands these QuireError properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message` | string | Main error message |
+| `code` | string | Error code (e.g., `'TOOL_NOT_FOUND'`) |
+| `exitCode` | number | Process exit code (default: 1) |
+| `suggestion` | string | Actionable fix for the user |
+| `docsUrl` | string | Link to relevant documentation |
+| `filePath` | string | Source file that caused the error |
+| `showDebugHint` | boolean | Whether to show --debug hint (default: true) |
+
+## Exit Codes
+
+| Code | Category | Examples |
+|------|----------|----------|
+| 1 | General error | Unexpected errors |
+| 2 | Project error | Not in project, directory not empty |
+| 3 | Build error | Config not found, build failed |
+| 4 | Validation error | YAML parse error, validation failed |
+| 5 | Output error | PDF/EPUB generation failed |
+| 6 | Install error | Invalid path, dependency install failed |
+
+## Testing
+
+Use the `exit` and `exitFn` options to prevent actual process exit:
+
+```javascript
+import { handleError } from '#lib/error/handler.js'
+
+const exitCode = handleError(error, {
+  exit: false,  // Don't call process.exit
+  debug: true
+})
+
+t.is(exitCode, 5)
+```
+
+Or provide a mock exit function:
+
+```javascript
+const mockExit = sinon.stub()
+
+handleError(error, {
+  exitFn: mockExit,
+  debug: false
+})
+
+t.true(mockExit.calledWith(5))
+```

package/src/lib/error/handler.js

@@ -0,0 +1,107 @@
+/**
+ * Centralized error handler for the Quire CLI
+ *
+ * Provides consistent error formatting and exit code management.
+ * All command errors should flow through this handler.
+ *
+ * @module lib/error/handler
+ */
+import { logger } from '#lib/logger/index.js'
+import QuireError from '#src/errors/quire-error.js'
+
+/**
+ * Format a QuireError for user display
+ *
+ * @param {QuireError} error - The error to format
+ * @param {Object} options - Formatting options
+ * @param {boolean} options.debug - Include error code in output (default: false)
+ * @returns {string} Formatted error message
+ */
+export function formatError(error, options = {}) {
+  const { debug = false } = options
+  // Only show error code (e.g., INVALID_PATH) in debug mode
+  const header = (debug && error.code) ? `${error.code} ${error.message}` : error.message
+  const lines = [header]
+  if (error.filePath) lines.push(`  File: ${error.filePath}`)
+  if (error.suggestion) lines.push(`  Suggestion: ${error.suggestion}`)
+  if (error.docsUrl) lines.push(`  Learn more: ${error.docsUrl}`)
+  // Show debug hint when not in debug mode and error opts in
+  if (!debug && error.showDebugHint !== false) {
+    lines.push('  Tip: Run with --debug for more details')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Handle a single error
+ *
+ * @param {Error} error - The error to handle
+ * @param {Object} options
+ * @param {boolean} options.exit - Whether to exit process (default: true)
+ * @param {Function} options.exitFn - Exit function for testing (default: process.exit)
+ * @param {boolean} options.debug - Show stack traces (default: false)
+ * @returns {number} Exit code
+ */
+export function handleError(error, options = {}) {
+  const { exit = true, exitFn = process.exit, debug = false } = options
+
+  if (error instanceof QuireError) {
+    logger.error(formatError(error, { debug }))
+
+    if (debug && error.stack) {
+      logger.debug('Stack trace:')
+      logger.debug(error.stack)
+    }
+
+    if (exit) exitFn(error.exitCode)
+    return error.exitCode
+  }
+
+  // Non-Quire errors (unexpected)
+  logger.error(`Unexpected error: ${error.message}`)
+  logger.info('Please report this issue: https://github.com/thegetty/quire/issues')
+
+  if (debug && error.stack) {
+    logger.debug('Stack trace:')
+    logger.debug(error.stack)
+  }
+
+  if (exit) exitFn(1)
+  return 1
+}
+
+/**
+ * Handle multiple errors (for batch validation)
+ *
+ * @param {Error[]} errors - Array of errors
+ * @param {Object} options - Same as handleError
+ * @returns {number} Highest exit code
+ */
+export function handleErrors(errors, options = {}) {
+  if (!errors.length) return 0
+
+  const { exit = true, exitFn = process.exit, debug = false } = options
+
+  logger.error(`${errors.length} error(s) occurred:\n`)
+
+  let maxExitCode = 1
+  errors.forEach((error, i) => {
+    const formatted = error instanceof QuireError ? formatError(error, { debug }) : error.message
+    logger.error(`${i + 1}. ${formatted}`)
+    if (error instanceof QuireError && error.exitCode > maxExitCode) {
+      maxExitCode = error.exitCode
+    }
+  })
+
+  if (debug) {
+    errors.forEach((error) => {
+      if (error.stack) {
+        logger.debug(`Stack trace for ${error.message}:`)
+        logger.debug(error.stack)
+      }
+    })
+  }
+
+  if (exit) exitFn(maxExitCode)
+  return maxExitCode
+}

package/src/lib/git/README.md

@@ -1,3 +1,152 @@
-## CLI Git Module
+# Git Façade
 
-This `quire-cli/lib/git` module is a façade for interacting with `git` when creating new Quire projects and contributing to the `quire` code base, including the `quire-cli`.
+A façade module that abstracts git command-line operations for the Quire CLI.
+
+## Purpose
+
+This module provides a unified interface for git operations with:
+
+- Encapsulation of git implementation details
+- Consistent logging prefixed with `[CLI:lib/git]`
+- Unified error handling
+- Easy mockability for testing
+
+## Usage
+
+### Singleton (for global operations)
+
+```javascript
+import git from '#lib/git/index.js'
+
+// Check git availability
+if (!git.isAvailable()) {
+  console.error('git is not installed')
+}
+
+// Get git version
+// @see https://git-scm.com/docs/git-version
+const version = await git.version()
+```
+
+### Git Class (for repository-scoped operations)
+
+```javascript
+import { Git } from '#lib/git/index.js'
+
+// Create instance with working directory
+const repo = new Git('/path/to/project')
+
+// Clone a repository
+// @see https://git-scm.com/docs/git-clone
+await repo.clone('https://github.com/user/repo', '.')
+
+// Initialize a repository
+// @see https://git-scm.com/docs/git-init
+await repo.init()
+
+// Stage files
+// @see https://git-scm.com/docs/git-add
+await repo.add('.')
+await repo.add(['file1.js', 'file2.js'])
+
+// Create a commit
+// @see https://git-scm.com/docs/git-commit
+await repo.commit('Initial commit')
+
+// Remove files from tracking
+// @see https://git-scm.com/docs/git-rm
+await repo.rm('package.json')
+await repo.rm(['file1.js', 'file2.js'])
+```
+
+## API
+
+### Constructor
+
+#### `new Git(cwd)`
+
+Create a Git façade instance scoped to a working directory.
+
+**Parameters:**
+- `cwd` (string, optional) - Working directory for all operations
+
+### Methods
+
+#### `isAvailable()`
+
+Check if git is available in PATH.
+
+#### `version()`
+
+Get the installed git version.
+
+#### `add(files)`
+
+Stage files for commit.
+
+**Parameters:**
+- `files` (string|string[]) - Files to stage (use `'.'` for all)
+
+#### `clone(url, destination)`
+
+Clone a repository.
+
+**Parameters:**
+- `url` (string) - Repository URL
+- `destination` (string, default: `'.'`) - Destination directory
+
+#### `commit(message)`
+
+Create a commit with staged changes.
+
+**Parameters:**
+- `message` (string) - Commit message
+
+#### `init()`
+
+Initialize a new git repository.
+
+#### `rm(files)`
+
+Remove files from the working tree and index.
+
+**Parameters:**
+- `files` (string|string[]) - Files to remove
+
+## Testing
+
+### Mocking the singleton
+
+```javascript
+import esmock from 'esmock'
+
+const mockGit = {
+  isAvailable: sandbox.stub().returns(true),
+  version: sandbox.stub().resolves('2.39.0'),
+}
+
+const MyCommand = await esmock('./mycommand.js', {
+  '#lib/git/index.js': { default: mockGit }
+})
+```
+
+### Mocking the Git class
+
+```javascript
+import esmock from 'esmock'
+
+const MockGit = class {
+  constructor(cwd) {
+    this.cwd = cwd
+    this.add = sandbox.stub().resolves()
+    this.clone = sandbox.stub().resolves()
+    this.commit = sandbox.stub().resolves()
+    this.init = sandbox.stub().resolves()
+    this.rm = sandbox.stub().resolves()
+  }
+}
+
+const MyCommand = await esmock('./mycommand.js', {
+  '#lib/git/index.js': { Git: MockGit }
+})
+```

package/src/lib/git/index.js

@@ -1,22 +1,226 @@
-import { simpleGit } from 'simple-git'
+/**
+ * Git façade providing abstracted git operations
+ *
+ * Provides a consistent interface for git commands with unified
+ * logging, error handling, and testability.
+ *
+ * @example using default singleton for global operations
+ * import git from '#lib/git/index.js'
+ * const version = await git.version()
+ * if (!git.isAvailable()) { ... }
+ *
+ * @example using Git class for repository-scoped operations
+ * import { Git } from '#lib/git/index.js'
+ * const repo = new Git('/path/to/project')
+ * await repo.init()
+ * await repo.add('.')
+ * await repo.commit('Initial commit')
+ *
+ * @example mocking in tests
+ * const mockGit = {
+ *   clone: sandbox.stub().resolves(),
+ *   commit: sandbox.stub().resolves(),
+ * }
+ * const MyCommand = await esmock('./mycommand.js', {
+ *   '#lib/git/index.js': { default: mockGit }
+ * })
+ *
+ * @see https://git-scm.com/docs - git documentation
+ * @module git
+ */
+import { execa } from 'execa'
+import fs from 'node:fs'
+import path from 'node:path'
+import which from '#helpers/which.js'
+import createDebug from '#debug'
+
+const debug = createDebug('lib:git')
+
+/**
+ * Check if a source string is a remote URL (vs local path)
+ *
+ * Git supports various remote URL formats:
+ * - https://github.com/user/repo.git
+ * - git@github.com:user/repo.git
+ * - ssh://git@github.com/user/repo.git
+ * - http://github.com/user/repo.git
+ * - git://github.com/user/repo.git
+ *
+ * @param {string} source - Source string to check
+ * @returns {boolean} True if source appears to be a remote URL
+ */
+export function isRemoteUrl(source) {
+  return source.startsWith('https://') ||
+         source.startsWith('git@') ||
+         source.startsWith('ssh://') ||
+         source.startsWith('http://') ||
+         source.startsWith('git://')
+}
 
 /**
- * SimpleGit configuration
- * @see https://github.com/steveukx/git-js#configuration
+ * Check if a path is a git repository
+ *
+ * A directory is considered a git repository if it contains a .git directory.
+ *
+ * @param {string} dirPath - Path to check
+ * @returns {boolean} True if the path is a git repository
  */
-const options = {
-  baseDir: process.cwd(),
-  binary: 'git',
-  maxConcurrentProcesses: 6,
-  trimmed: false,
+export function isGitRepository(dirPath) {
+  const gitDir = path.join(dirPath, '.git')
+  return fs.existsSync(gitDir)
 }
 
 /**
- * Configured SimpleGit instance
- * @see https://github.com/steveukx/git-js#api
+ * Validate a clone source before attempting to clone
  *
- * @type  {SimpleGit}
+ * For remote URLs, validation is skipped (let git clone handle network errors).
+ * For local paths, validates the path exists and is a git repository.
+ *
+ * @param {string} source - Clone source (URL or local path)
+ * @returns {{ valid: boolean, reason?: string }} Validation result
  */
-const git = simpleGit(options)
+export function validateCloneSource(source) {
+  // Remote URLs are assumed valid - let git clone handle errors
+  if (isRemoteUrl(source)) {
+    return { valid: true }
+  }
+
+  // Local path validation
+  if (!fs.existsSync(source)) {
+    return { valid: false, reason: 'path does not exist' }
+  }
+
+  if (!isGitRepository(source)) {
+    return { valid: false, reason: 'not a git repository' }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Git façade class
+ */
+class Git {
+  /**
+   * Create a Git façade instance
+   * @param {string} [cwd] - Working directory for all operations
+   */
+  constructor(cwd) {
+    this.cwd = cwd
+  }
+
+  /**
+   * Get execa options with working directory
+   * @private
+   * @returns {Object} Options object for execa
+   */
+  #getOptions() {
+    return this.cwd ? { cwd: this.cwd } : {}
+  }
+
+  /**
+   * Get resolved working directory for logging
+   * @private
+   * @returns {string} Resolved absolute path
+   */
+  #resolvedCwd() {
+    return path.resolve(this.cwd || process.cwd())
+  }
+
+  /**
+   * Stage files for commit
+   * @see https://git-scm.com/docs/git-add
+   * @param {string|string[]} files - Files to stage (use '.' for all)
+   * @returns {Promise<void>}
+   */
+  async add(files) {
+    const fileList = Array.isArray(files) ? files : [files]
+    debug('staging files in %s: %s', this.#resolvedCwd(), fileList.join(', '))
+    const { stderr } = await execa('git', ['add', ...fileList], this.#getOptions())
+    if (stderr) {
+      debug('git add stderr: %s', stderr)
+    }
+  }
+
+  /**
+   * Clone a repository
+   * @see https://git-scm.com/docs/git-clone
+   * @param {string} url - Repository URL
+   * @param {string} [destination='.'] - Destination directory
+   * @returns {Promise<void>}
+   */
+  async clone(url, destination = '.') {
+    const resolvedDest = path.resolve(this.#resolvedCwd(), destination)
+    debug('cloning %s to %s', url, resolvedDest)
+    const { stderr } = await execa('git', ['clone', url, destination], this.#getOptions())
+    if (stderr) {
+      debug('git clone stderr: %s', stderr)
+    }
+  }
+
+  /**
+   * Create a commit
+   * @see https://git-scm.com/docs/git-commit
+   * @param {string} message - Commit message
+   * @returns {Promise<void>}
+   */
+  async commit(message) {
+    debug('committing in %s: %s...', this.#resolvedCwd(), message.substring(0, 50))
+    const { stderr } = await execa('git', ['commit', '-m', message], this.#getOptions())
+    if (stderr) {
+      debug('git commit stderr: %s', stderr)
+    }
+  }
+
+  /**
+   * Initialize a new repository
+   * @see https://git-scm.com/docs/git-init
+   * @returns {Promise<void>}
+   */
+  async init() {
+    debug('initializing repository in %s', this.#resolvedCwd())
+    const { stderr } = await execa('git', ['init'], this.#getOptions())
+    if (stderr) {
+      debug('git init stderr: %s', stderr)
+    }
+  }
+
+  /**
+   * Check if git is available in PATH
+   * @returns {boolean} True if git is available
+   */
+  isAvailable() {
+    return !!which('git')
+  }
+
+  /**
+   * Remove files from the working tree and index
+   * @see https://git-scm.com/docs/git-rm
+   * @param {string|string[]} files - Files to remove
+   * @returns {Promise<void>}
+   */
+  async rm(files) {
+    const fileList = Array.isArray(files) ? files : [files]
+    debug('removing files in %s: %s', this.#resolvedCwd(), fileList.join(', '))
+    const { stderr } = await execa('git', ['rm', ...fileList], this.#getOptions())
+    if (stderr) {
+      debug('git rm stderr: %s', stderr)
+    }
+  }
+
+  /**
+   * Get git version
+   * @see https://git-scm.com/docs/git-version
+   * @returns {Promise<string>} git version string
+   */
+  async version() {
+    const { stdout } = await execa('git', ['--version'])
+    return stdout.replace('git version ', '')
+  }
+}
+
+// Export class for repository-scoped operations
+export { Git }
 
-export default git
+// Export singleton instance for global operations
+export default new Git()