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

package/src/errors/index.js

@@ -1,58 +0,0 @@
-/**
- * Centralized error exports for Quire CLI
- *
- * All custom error classes are exported from here for easy imports.
- *
- * @example
- * import { NotInProjectError, BuildFailedError } from '#src/errors/index.js'
- *
- * @module errors
- */
-
-// Base error class
-export { default as QuireError } from './quire-error.js'
-
-// Project errors (exit code: 2)
-export {
-  NotInProjectError,
-  ProjectCreateError
-} from './project/index.js'
-
-// Build errors (exit code: 3)
-export {
-  BuildFailedError,
-  ConfigFieldMissingError,
-  ConfigFileNotFoundError
-} from './build/index.js'
-
-// Output errors (exit code: 5)
-export {
-  EpubGenerationError,
-  InvalidEpubLibraryError,
-  InvalidPdfLibraryError,
-  MissingBuildOutputError,
-  PdfGenerationError,
-  ToolNotFoundError
-} from './output/index.js'
-
-// Install errors (exit code: 6)
-export {
-  DependencyInstallError,
-  DirectoryNotEmptyError,
-  InvalidPathError,
-  InvalidStarterError,
-  VersionNotFoundError
-} from './install/index.js'
-
-// Validation errors (exit code: 4)
-export {
-  ValidationError,
-  UnknownConfigKeyError,
-  UnknownConfigOperationError
-} from './validation/index.js'
-
-// Input errors (exit code: 2)
-export { InvalidInputError } from './input/index.js'
-
-// Help errors (exit code: 2)
-export { HelpTopicNotFoundError } from './help/index.js'

package/src/errors/input/index.js

@@ -1,8 +0,0 @@
-/**
- * Input errors (exit code: 2)
- *
- * Errors related to invalid user input (arguments, options, values).
- *
- * @module errors/input
- */
-export { default as InvalidInputError } from './invalid-input-error.js'

package/src/errors/input/invalid-input-error.js

@@ -1,21 +0,0 @@
-import QuireError from '../quire-error.js'
-
-/**
- * Error thrown when user input is invalid
- *
- * Generic error for invalid arguments, options, or other user-provided values.
- * Can be extended for specific input validation scenarios.
- */
-export default class InvalidInputError extends QuireError {
-  constructor(message, options = {}) {
-    super(message, {
-      code: options.code || 'INVALID_INPUT',
-      exitCode: options.exitCode ?? 2,
-      suggestion: options.suggestion,
-      docsUrl: options.docsUrl,
-      ...options
-    })
-    this.inputValue = options.inputValue
-    this.inputName = options.inputName
-  }
-}

package/src/errors/install/dependency-install-error.js

@@ -1,19 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when dependency installation fails
- */
-export default class DependencyInstallError extends QuireError {
-  constructor(details) {
-    super(
-      `Failed to install dependencies: ${details}`,
-      {
-        code: 'DEPENDENCY_INSTALL_FAILED',
-        exitCode: 6,
-        suggestion: "Try running 'npm install' manually to see detailed errors",
-        docsUrl: docsUrl('troubleshooting')
-      }
-    )
-  }
-}

package/src/errors/install/directory-not-empty-error.js

@@ -1,25 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when attempting to create a project in a non-empty directory
- *
- * This error indicates the target directory contains existing files,
- * which could be user content that should not be overwritten or deleted.
- */
-export default class DirectoryNotEmptyError extends QuireError {
-  constructor(path) {
-    const location = path === '.' ? 'the current directory' : path
-    super(
-      `Cannot create project in a non-empty directory: ${location}`,
-      {
-        code: 'DIRECTORY_NOT_EMPTY',
-        exitCode: 2,
-        filePath: path,
-        suggestion: 'Choose an empty directory or create a new one',
-        docsUrl: docsUrl('install-uninstall'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/install/index.js

@@ -1,12 +0,0 @@
-/**
- * Installation errors (exit code: 6)
- *
- * Errors related to dependency installation and version management.
- *
- * @module errors/install
- */
-export { default as DependencyInstallError } from './dependency-install-error.js'
-export { default as DirectoryNotEmptyError } from './directory-not-empty-error.js'
-export { default as InvalidPathError } from './invalid-path-error.js'
-export { default as InvalidStarterError } from './invalid-starter-error.js'
-export { default as VersionNotFoundError } from './version-not-found-error.js'

package/src/errors/install/invalid-path-error.js

@@ -1,31 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when a specified path does not exist
- *
- * Used when --quire-path option points to a non-existent directory.
- */
-export default class InvalidPathError extends QuireError {
-  /**
-   * @param {string} originalPath - The path as provided by the user
-   * @param {string} resolvedPath - The fully resolved absolute path
-   */
-  constructor(originalPath, resolvedPath) {
-    const pathDisplay = originalPath === resolvedPath
-      ? originalPath
-      : `${originalPath} (resolved to: ${resolvedPath})`
-
-    super(
-      `--quire-path does not exist: ${pathDisplay}`,
-      {
-        code: 'INVALID_PATH',
-        exitCode: 6,
-        filePath: resolvedPath,
-        suggestion: 'Verify the path exists and is accessible',
-        docsUrl: docsUrl('install-uninstall'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/install/invalid-starter-error.js

@@ -1,27 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when a starter template is invalid
- *
- * Used when the starter argument points to a non-existent path
- * or a path that is not a valid git repository.
- */
-export default class InvalidStarterError extends QuireError {
-  /**
-   * @param {string} starterPath - The starter path that is invalid
-   * @param {string} reason - Why the starter is invalid
-   */
-  constructor(starterPath, reason) {
-    super(
-      `Invalid starter template '${starterPath}': ${reason}`,
-      {
-        code: 'INVALID_STARTER',
-        exitCode: 6,
-        filePath: starterPath,
-        suggestion: 'Verify the path exists and is a git repository, or use a repository URL',
-        docsUrl: docsUrl('install-uninstall')
-      }
-    )
-  }
-}

package/src/errors/install/version-not-found-error.js

@@ -1,35 +0,0 @@
-import path from 'node:path'
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when a package version cannot be determined
- *
- * Handles both npm registry lookups and local package paths.
- */
-export default class VersionNotFoundError extends QuireError {
-  /**
-   * @param {string} packageName - Package name or path description
-   * @param {string} reason - Version string for npm, or reason for local path
-   * @param {Object} [options] - Override default suggestion
-   * @param {string} [options.suggestion] - Custom suggestion text
-   */
-  constructor(packageName, reason, options = {}) {
-    const isLocalPath = packageName.includes(path.sep)
-    const defaultSuggestion = isLocalPath
-      ? 'Ensure the local package has a valid package.json with a version field'
-      : `Run 'npm view ${packageName} versions' to see available versions`
-
-    super(
-      isLocalPath
-        ? `Cannot determine version from ${packageName}: ${reason}`
-        : `Version '${reason}' of ${packageName} not found`,
-      {
-        code: 'VERSION_NOT_FOUND',
-        exitCode: 6,
-        suggestion: options.suggestion || defaultSuggestion,
-        docsUrl: docsUrl('install-uninstall')
-      }
-    )
-  }
-}

package/src/errors/output/epub-generation-error.js

@@ -1,19 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when EPUB generation fails
- */
-export default class EpubGenerationError extends QuireError {
-  constructor(details) {
-    super(
-      `EPUB generation failed: ${details}`,
-      {
-        code: 'EPUB_FAILED',
-        exitCode: 5,
-        suggestion: 'Check that your publication built successfully first',
-        docsUrl: docsUrl('epub-output')
-      }
-    )
-  }
-}

package/src/errors/output/index.js

@@ -1,14 +0,0 @@
-/**
- * Output generation errors (exit code: 5)
- *
- * Errors related to PDF and EPUB generation including
- * missing build output and external tool issues.
- *
- * @module errors/output
- */
-export { default as EpubGenerationError } from './epub-generation-error.js'
-export { default as InvalidEpubLibraryError } from './invalid-epub-library-error.js'
-export { default as InvalidPdfLibraryError } from './invalid-pdf-library-error.js'
-export { default as MissingBuildOutputError } from './missing-build-output-error.js'
-export { default as PdfGenerationError } from './pdf-generation-error.js'
-export { default as ToolNotFoundError } from './tool-not-found-error.js'

package/src/errors/output/invalid-epub-library-error.js

@@ -1,20 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when an unrecognized EPUB library is specified
- */
-export default class InvalidEpubLibraryError extends QuireError {
-  constructor(libName, validLibraries = ['epubjs', 'pandoc']) {
-    super(
-      `Unrecognized EPUB library '${libName}'`,
-      {
-        code: 'INVALID_EPUB_LIBRARY',
-        exitCode: 5,
-        suggestion: `Use one of: ${validLibraries.join(', ')}`,
-        docsUrl: docsUrl('epub-output'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/output/invalid-pdf-library-error.js

@@ -1,20 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when an unrecognized PDF library is specified
- */
-export default class InvalidPdfLibraryError extends QuireError {
-  constructor(libName, validLibraries = ['prince', 'pagedjs']) {
-    super(
-      `Unrecognized PDF library '${libName}'`,
-      {
-        code: 'INVALID_PDF_LIBRARY',
-        exitCode: 5,
-        suggestion: `Use one of: ${validLibraries.join(', ')}`,
-        docsUrl: docsUrl('pdf-output'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/output/missing-build-output-error.js

@@ -1,21 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when required build output is missing
- */
-export default class MissingBuildOutputError extends QuireError {
-  constructor(outputType, expectedPath) {
-    super(
-      `Cannot generate ${outputType}: build output not found`,
-      {
-        code: 'BUILD_OUTPUT_MISSING',
-        exitCode: 5,
-        filePath: expectedPath,
-        suggestion: "Run 'quire build' first, then try again",
-        docsUrl: docsUrl('quire-commands'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/output/pdf-generation-error.js

@@ -1,24 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when PDF generation fails
- *
- * @param {string} tool - The PDF tool that failed (e.g., 'Paged.js', 'Prince')
- * @param {string} operation - The operation that failed (e.g., 'PDF rendering', 'page map extraction')
- * @param {string} [details] - Additional error details from the underlying error
- */
-export default class PdfGenerationError extends QuireError {
-  constructor(tool, operation, details) {
-    const message = details
-      ? `${tool} ${operation} failed: ${details}`
-      : `${tool} ${operation} failed`
-
-    super(message, {
-      code: 'PDF_FAILED',
-      exitCode: 5,
-      suggestion: `Check that ${tool} is properly configured and the input files are valid`,
-      docsUrl: docsUrl('pdf-output')
-    })
-  }
-}

package/src/errors/output/tool-not-found-error.js

@@ -1,37 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when a required external tool is not found
- *
- * @param {string} toolName - The name of the tool (e.g., 'prince', 'pandoc')
- * @param {Object} [toolInfo] - Tool metadata provided by the calling façade
- * @param {string} [toolInfo.displayName] - Human-readable tool name
- * @param {string} [toolInfo.installUrl] - URL where tool can be downloaded
- * @param {string} [toolInfo.docsUrl] - Quire docs URL for this tool's usage
- * @param {string} [toolInfo.fallback] - Alternative suggestion (e.g., use default engine)
- */
-export default class ToolNotFoundError extends QuireError {
-  constructor(toolName, toolInfo = {}) {
-    const displayName = toolInfo.displayName || toolName
-    const installUrl = toolInfo.installUrl || 'the tool documentation'
-    const toolDocsUrl = toolInfo.docsUrl || docsUrl('troubleshooting')
-
-    let suggestion = `Install ${displayName} from ${installUrl}`
-    if (toolInfo.fallback) {
-      suggestion += `\n${toolInfo.fallback}`
-    }
-
-    super(
-      `${displayName} is not installed or not in PATH`,
-      {
-        code: 'TOOL_NOT_FOUND',
-        exitCode: 5,
-        suggestion,
-        docsUrl: toolDocsUrl,
-      }
-    )
-
-    this.toolName = toolName
-  }
-}

package/src/errors/project/index.js

@@ -1,10 +0,0 @@
-/**
- * Project-related errors (exit code: 2)
- *
- * Errors related to project setup and detection.
- * Used when commands are run outside a Quire project or project creation fails.
- *
- * @module errors/project
- */
-export { default as NotInProjectError } from './not-in-project-error.js'
-export { default as ProjectCreateError } from './project-create-error.js'

package/src/errors/project/not-in-project-error.js

@@ -1,20 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when a command is run outside a Quire project directory
- */
-export default class NotInProjectError extends QuireError {
-  constructor(commandName) {
-    super(
-      `The '${commandName}' command must be run inside a Quire project`,
-      {
-        code: 'NOT_IN_PROJECT',
-        exitCode: 2,
-        suggestion: "Navigate to your project folder with 'cd your-project-name'",
-        docsUrl: docsUrl('quire-commands'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/project/project-create-error.js

@@ -1,21 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Error thrown when project creation fails
- */
-export default class ProjectCreateError extends QuireError {
-  constructor(projectPath, cause) {
-    super(
-      `Failed to create project at '${projectPath}'`,
-      {
-        code: 'PROJECT_CREATE_FAILED',
-        exitCode: 2,
-        filePath: projectPath,
-        suggestion: 'Check that the directory is empty and you have write permissions',
-        docsUrl: docsUrl('getting-started')
-      }
-    )
-    this.cause = cause
-  }
-}

package/src/errors/quire-error.js

@@ -1,27 +0,0 @@
-/**
- * Base error class for all Quire CLI errors
- *
- * Provides structured error data for the error handler to format.
- *
- * @property {string} code - Error code (e.g., 'CONFIG_FILE_NOT_FOUND')
- * @property {number} exitCode - Process exit code (default: 1)
- * @property {string} suggestion - Actionable fix for the user
- * @property {string} docsUrl - Link to relevant documentation
- * @property {string} filePath - Source file that caused the error (optional)
- * @property {boolean} showDebugHint - Whether to show --debug hint (default: true)
- */
-export default class QuireError extends Error {
-  constructor(message, options = {}) {
-    super(message)
-    this.name = this.constructor.name
-    this.code = options.code
-    this.exitCode = options.exitCode ?? 1
-    this.suggestion = options.suggestion
-    this.docsUrl = options.docsUrl
-    this.filePath = options.filePath
-    this.showDebugHint = options.showDebugHint ?? true
-    if ('captureStackTrace' in Error) {
-      Error.captureStackTrace(this, this.constructor)
-    }
-  }
-}

package/src/errors/validation/index.js

@@ -1,3 +0,0 @@
-export { default as ValidationError } from './validation-error.js'
-export { default as UnknownConfigKeyError } from './unknown-config-key-error.js'
-export { default as UnknownConfigOperationError } from './unknown-config-operation-error.js'

package/src/errors/validation/unknown-config-key-error.js

@@ -1,27 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-import { suggestSimilar, formatSuggestion } from '#helpers/suggest-similar.js'
-
-/**
- * Error thrown when an unrecognized configuration key is used
- *
- * @param {string} key - The unrecognized key
- * @param {string[]} validKeys - Array of valid configuration keys
- */
-export default class UnknownConfigKeyError extends QuireError {
-  constructor(key, validKeys) {
-    const suggestion = formatSuggestion(suggestSimilar(key, validKeys))
-      || `Valid keys: ${validKeys.join(', ')}`
-
-    super(
-      `Unknown configuration key: ${key}`,
-      {
-        code: 'UNKNOWN_CONFIG_KEY',
-        exitCode: 4,
-        suggestion,
-        docsUrl: docsUrl('quire-commands/'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/errors/validation/unknown-config-operation-error.js

@@ -1,24 +0,0 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-import { suggestSimilar, formatSuggestion } from '#helpers/suggest-similar.js'
-
-/**
- * Error thrown when an unrecognized settings operation is used
- */
-export default class UnknownConfigOperationError extends QuireError {
-  constructor(operation, validOperations) {
-    const suggestion = formatSuggestion(suggestSimilar(operation, validOperations))
-      || `Valid operations: ${validOperations.join(', ')}`
-
-    super(
-      `Unknown operation: ${operation}`,
-      {
-        code: 'UNKNOWN_CONFIG_OPERATION',
-        exitCode: 4,
-        suggestion,
-        docsUrl: docsUrl('quire-commands/'),
-        showDebugHint: false
-      }
-    )
-  }
-}

package/src/helpers/docs-url.js

@@ -1,32 +0,0 @@
-/**
- * Helper module for constructing documentation URLs
- * @module helpers/docs-url
- */
-
-/**
- * Base URL for Quire documentation
- */
-const DOCS_BASE = 'https://quire.getty.edu/docs-v1/'
-
-/**
- * Export the base URL for cases where direct access is needed
- */
-export { DOCS_BASE }
-
-/**
- * Construct a full documentation URL from a path segment
- *
- * Uses the URL constructor for automatic path normalization.
- *
- * @param {string} path - Documentation path segment (e.g., 'install-uninstall')
- * @returns {string} Full documentation URL
- *
- * @example
- * docsUrl('install-uninstall')
- * // => 'https://quire.getty.edu/docs-v1/install-uninstall'
- *
- * @example
- * docsUrl('quire-commands')
- * // => 'https://quire.getty.edu/docs-v1/quire-commands'
- */
-export const docsUrl = (path) => new URL(path, DOCS_BASE).href

package/src/helpers/pager.js

@@ -1,59 +0,0 @@
-/**
- * Terminal pager utility
- *
- * Provides paged output for long content in interactive terminals.
- * Paging can be disabled with:
- * - `--no-pager` CLI flag (sets NO_PAGER env var)
- * - `NO_PAGER=1` environment variable
- * - `PAGER=cat` traditional Unix convention (content passes through without paging)
- *
- * @module helpers/pager
- */
-import { spawn } from 'node:child_process'
-
-/**
- * Output content with optional paging for long content
- *
- * Uses system pager (less/more) when:
- * - Output is to an interactive terminal (TTY)
- * - Content exceeds terminal height
- * - Paging is not disabled via NO_PAGER env var
- *
- * The PAGER env var selects the pager program (default: less on Unix, more on
- * Windows). Setting PAGER=cat effectively disables paging as a traditional
- * Unix convention.
- *
- * @param {string} content - Content to output
- * @returns {Promise<void>}
- */
-export async function outputWithPaging(content) {
-  const noPager = process.env.NO_PAGER
-  const lines = content.split('\n').length
-  const isTTY = process.stdout.isTTY
-  const terminalRows = process.stdout.rows || 24
-
-  // Use pager if content exceeds terminal height and we're in a TTY
-  if (!noPager && isTTY && lines > terminalRows) {
-    const pager = process.env.PAGER || (process.platform === 'win32' ? 'more' : 'less')
-    const pagerArgs = pager === 'less' ? ['-R'] : [] // -R preserves ANSI colors
-
-    return new Promise((resolve) => {
-      const child = spawn(pager, pagerArgs, {
-        stdio: ['pipe', 'inherit', 'inherit']
-      })
-
-      child.stdin.write(content + '\n')
-      child.stdin.end()
-
-      child.on('close', resolve)
-      child.on('error', () => {
-        // Fallback to direct output if pager fails
-        process.stdout.write(content + '\n')
-        resolve()
-      })
-    })
-  }
-
-  // Direct output for non-TTY or short content
-  process.stdout.write(content + '\n')
-}