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

package/src/commands/workflows.js

@@ -0,0 +1,70 @@
+import Command from '#src/Command.js'
+import { DOCS_BASE } from '#helpers/docs-url.js'
+
+/**
+ * Quire CLI `workflows` Command
+ *
+ * Displays common workflow documentation.
+ * Hidden from main help but accessible via `quire help workflows` or `quire workflows`.
+ *
+ * TODO: Refactor to an extensible `quire help <topic>` system that can load
+ * help topics from a topics/ directory or markdown files. This would support:
+ * - quire help workflows
+ * - quire help debugging
+ * - quire help publishing
+ * - quire help configuration
+ *
+ * @class      WorkflowsCommand
+ * @extends    {Command}
+ */
+export default class WorkflowsCommand extends Command {
+  static definition = {
+    name: 'workflows',
+    description: 'Display common workflow documentation',
+    summary: 'show common workflows',
+    hidden: true,
+    docsLink: 'quire-commands/',
+    helpText: `
+Common Workflows:
+
+  Starting a New Project:
+    quire new my-book && cd my-book && quire preview
+
+  Building for Web:
+    quire build                  Generate HTML site files
+    quire clean && quire build   Clean build (recommended for production)
+
+  Generating PDF:
+    quire pdf --build            Build first, then generate PDF
+    quire pdf --build --open     Generate and open PDF
+    quire pdf --engine prince    Use PrinceXML instead of Paged.js
+
+  Generating EPUB:
+    quire epub --build           Build first, then generate EPUB
+    quire epub --build --open    Generate and open EPUB
+
+  Full Publication Build:
+    quire clean && quire build && quire pdf && quire epub
+
+  Troubleshooting:
+    quire validate               Check YAML files for errors
+    quire info                   Show version information
+    quire build --verbose        Build with debug output
+
+See full documentation: ${DOCS_BASE}
+`,
+    version: '1.0.0',
+    options: [],
+  }
+
+  constructor() {
+    super(WorkflowsCommand.definition)
+  }
+
+  async action(options, command) {
+    this.debug('called with options %O', options)
+    // The help text is automatically displayed via Commander's help system
+    // If called directly (quire workflows), display help
+    command.help()
+  }
+}

package/src/errors/build/build-failed-error.js

@@ -0,0 +1,19 @@
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+
+/**
+ * Error thrown when the publication build fails
+ */
+export default class BuildFailedError extends QuireError {
+  constructor(details) {
+    super(
+      `Publication build failed${details ? `: ${details}` : ''}`,
+      {
+        code: 'BUILD_FAILED',
+        exitCode: 3,
+        suggestion: "Run 'quire build --debug' for detailed error information",
+        docsUrl: docsUrl('troubleshooting')
+      }
+    )
+  }
+}

package/src/errors/build/config-field-missing-error.js

@@ -0,0 +1,20 @@
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+
+/**
+ * Error thrown when a required field is missing from a configuration file
+ */
+export default class ConfigFieldMissingError extends QuireError {
+  constructor(fieldName, configFile) {
+    super(
+      `Missing required field '${fieldName}' in ${configFile}`,
+      {
+        code: 'CONFIG_FIELD_MISSING',
+        exitCode: 3,
+        filePath: `content/_data/${configFile}`,
+        suggestion: `Add '${fieldName}' to your ${configFile}`,
+        docsUrl: docsUrl('publication-configuration')
+      }
+    )
+  }
+}

package/src/errors/build/config-file-not-found-error.js

@@ -0,0 +1,20 @@
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
+
+/**
+ * Error thrown when a required configuration file is not found
+ */
+export default class ConfigFileNotFoundError extends QuireError {
+  constructor(configFile) {
+    super(
+      `Required configuration file '${configFile}' not found`,
+      {
+        code: 'CONFIG_FILE_NOT_FOUND',
+        exitCode: 3,
+        filePath: `content/_data/${configFile}`,
+        suggestion: `Create ${configFile} in your content/_data/ folder`,
+        docsUrl: docsUrl('publication-configuration')
+      }
+    )
+  }
+}

package/src/errors/build/index.js

@@ -0,0 +1,11 @@
+/**
+ * Build-related errors (exit code: 3)
+ *
+ * Errors related to publication build process including
+ * Eleventy build failures and configuration issues.
+ *
+ * @module errors/build
+ */
+export { default as BuildFailedError } from './build-failed-error.js'
+export { default as ConfigFieldMissingError } from './config-field-missing-error.js'
+export { default as ConfigFileNotFoundError } from './config-file-not-found-error.js'

package/src/errors/index.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { default as ValidationError } from './validation/validation-error.js'

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * 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

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

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * 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

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

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

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * 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

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

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

@@ -0,0 +1,27 @@
+/**
+ * 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/validation-error.js

@@ -1,13 +1,22 @@
-export default class ValidationError extends Error {
-  constructor(message, {filePath, reason, code} = {}) {
-    super(message)
-    this.name = this.constructor.name
-    this.filePath = filePath
-    this.reason = reason
-    this.code = code
+import QuireError from '../quire-error.js'
+import { docsUrl } from '#helpers/docs-url.js'
 
-    if ('captureStackTrace' in Error) {
-      Error.captureStackTrace(this, this.constructor)
-    }
+/**
+ * Base validation error class (exit code: 4)
+ *
+ * Used for YAML validation, schema violations, and configuration errors.
+ * Maintains backward compatibility with existing properties (filePath, reason, code).
+ */
+export default class ValidationError extends QuireError {
+  constructor(message, { filePath, reason, code, suggestion, docsUrl: docsUrlOverride } = {}) {
+    super(message, {
+      code,
+      exitCode: 4,
+      filePath,
+      suggestion: suggestion || (reason ? `Fix: ${reason}` : undefined),
+      docsUrl: docsUrlOverride || docsUrl('troubleshooting')
+    })
+    // Maintain backward compatibility
+    this.reason = reason
   }
-}
+}

package/src/helpers/clean.js

@@ -36,7 +36,7 @@ export async function clean (projectRoot, paths, options = {}) {
   const deletedPaths = await deleteAsync(pathsToClean, {
     dryRun: options.dryRun,
     force: true,
-    onProgress: (options.progress || options.verbose) && progressLogger,
+    onProgress: options.verbose && progressLogger,
   })
 
   return deletedPaths