@thegetty/quire-cli 1.0.0-rc.44 → 1.0.0-rc.46

package/src/lib/error/README.md

@@ -1,170 +0,0 @@
-# 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

@@ -1,107 +0,0 @@
-/**
- * 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/index.spec.js

@@ -1,80 +0,0 @@
-import test from 'ava'
-import git, { Git } from './index.js'
-
-/**
- * Git Façade Unit Tests
- *
- * Tests the git façade module interface and API contract.
- * These tests verify the module exports and method signatures
- * without actually executing git commands.
- */
-
-// Default singleton export tests
-test('git façade exports a singleton object', (t) => {
-  t.truthy(git, 'git should be exported')
-  t.is(typeof git, 'object', 'git should be an object')
-})
-
-test('git façade singleton has no cwd by default', (t) => {
-  t.is(git.cwd, undefined, 'singleton cwd should be undefined')
-})
-
-test('git façade has add method', (t) => {
-  t.is(typeof git.add, 'function', 'add should be a function')
-})
-
-test('git façade has clone method', (t) => {
-  t.is(typeof git.clone, 'function', 'clone should be a function')
-})
-
-test('git façade has commit method', (t) => {
-  t.is(typeof git.commit, 'function', 'commit should be a function')
-})
-
-test('git façade has init method', (t) => {
-  t.is(typeof git.init, 'function', 'init should be a function')
-})
-
-test('git façade has isAvailable method', (t) => {
-  t.is(typeof git.isAvailable, 'function', 'isAvailable should be a function')
-})
-
-test('git façade has rm method', (t) => {
-  t.is(typeof git.rm, 'function', 'rm should be a function')
-})
-
-test('git façade has version method', (t) => {
-  t.is(typeof git.version, 'function', 'version should be a function')
-})
-
-test('isAvailable returns a boolean', (t) => {
-  const result = git.isAvailable()
-  t.is(typeof result, 'boolean', 'isAvailable should return a boolean')
-})
-
-// Git class export tests
-test('Git class is exported', (t) => {
-  t.truthy(Git, 'Git class should be exported')
-  t.is(typeof Git, 'function', 'Git should be a constructor')
-})
-
-test('Git class can be instantiated with cwd', (t) => {
-  const repo = new Git('/path/to/project')
-  t.is(repo.cwd, '/path/to/project', 'cwd should be set from constructor')
-})
-
-test('Git class can be instantiated without cwd', (t) => {
-  const repo = new Git()
-  t.is(repo.cwd, undefined, 'cwd should be undefined when not provided')
-})
-
-test('Git instance has all methods', (t) => {
-  const repo = new Git('/path/to/project')
-  t.is(typeof repo.add, 'function', 'add should be a function')
-  t.is(typeof repo.clone, 'function', 'clone should be a function')
-  t.is(typeof repo.commit, 'function', 'commit should be a function')
-  t.is(typeof repo.init, 'function', 'init should be a function')
-  t.is(typeof repo.isAvailable, 'function', 'isAvailable should be a function')
-  t.is(typeof repo.rm, 'function', 'rm should be a function')
-  t.is(typeof repo.version, 'function', 'version should be a function')
-})