@thegetty/quire-cli 1.0.0-rc.38 → 1.0.0-rc.40

package/src/lib/help/topics/pdf.md

@@ -0,0 +1,74 @@
+---
+title: PDF Generation
+description: Creating print-ready PDF publications
+---
+
+# PDF Generation
+
+## Quick Start
+
+```bash
+quire pdf --build            # Build and generate PDF
+quire pdf --build --open     # Build, generate, and open PDF
+```
+
+## PDF Engines
+
+Quire supports two PDF engines:
+
+### Paged.js (Default)
+
+Open-source, browser-based PDF generation. No additional installation required.
+
+```bash
+quire pdf                    # Uses Paged.js by default
+quire pdf --lib pagedjs      # Explicit Paged.js
+```
+
+### PrinceXML
+
+Commercial PDF engine with advanced typography features. Requires separate installation.
+
+```bash
+quire pdf --lib prince       # Use PrinceXML
+```
+
+**When to use PrinceXML:**
+- Complex typography requirements
+- Specific print production needs
+- Advanced CSS paged media features
+
+## Configuration
+
+PDF settings in `content/_data/config.yaml`:
+
+```yaml
+pdf:
+  output: _site/downloads/my-publication.pdf
+  # Additional PDF-specific settings
+```
+
+## Troubleshooting
+
+### PDF is blank or missing content
+
+1. Ensure build completed successfully: `quire build`
+2. Check that `_site/pdf.html` exists
+3. Run with debug: `quire pdf --debug`
+
+### Fonts not rendering correctly
+
+- Ensure fonts are properly installed or embedded
+- Check font paths in your CSS
+
+### Page breaks in wrong places
+
+Use CSS page break properties:
+
+```css
+.chapter {
+  page-break-before: always;
+}
+```
+
+See full documentation: https://quire.getty.edu/docs-v1/pdf-output/

package/src/lib/help/topics/publishing.md

@@ -0,0 +1,80 @@
+---
+title: Publishing
+description: Deploying your Quire publication
+---
+
+# Publishing Your Publication
+
+## Build for Production
+
+Always use a clean build for production:
+
+```bash
+quire clean && quire build
+```
+
+This ensures all files are freshly generated without stale artifacts.
+
+## Output Formats
+
+### Web (HTML)
+
+The default `quire build` generates a static HTML site in `_site/`:
+
+```bash
+quire build
+# Output: _site/
+```
+
+Deploy the `_site/` directory to any static hosting service.
+
+### PDF
+
+```bash
+quire pdf --build
+# Output: _site/downloads/*.pdf
+```
+
+### EPUB
+
+```bash
+quire epub --build
+# Output: _site/downloads/*.epub
+```
+
+## Complete Publication Workflow
+
+Generate all formats in one sequence:
+
+```bash
+quire clean && quire build && quire pdf && quire epub
+```
+
+## Deployment Options
+
+### GitHub Pages
+
+1. Push `_site/` to a `gh-pages` branch
+2. Configure GitHub Pages in repository settings
+3. Access at `https://username.github.io/repo-name/`
+
+### Netlify / Vercel
+
+1. Connect your repository
+2. Set build command: `quire build`
+3. Set publish directory: `_site`
+
+### Traditional Hosting
+
+Upload the contents of `_site/` to your web server via FTP/SFTP.
+
+## Pre-Publication Checklist
+
+- [ ] Run `quire validate` to check for errors
+- [ ] Review all content for accuracy
+- [ ] Test links and navigation
+- [ ] Verify images display correctly
+- [ ] Check PDF and EPUB in multiple readers
+- [ ] Test on different devices and browsers
+
+See full documentation: https://quire.getty.edu/docs-v1/site-deploy/

package/src/lib/help/topics/workflows.md

@@ -0,0 +1,50 @@
+---
+title: Common Workflows
+description: Step-by-step guides for common Quire tasks
+---
+
+# Common Workflows
+
+## Starting a New Project
+
+```bash
+quire new my-book && cd my-book && quire preview
+```
+
+## Building for Web
+
+```bash
+quire build                  # Generate HTML site files
+quire clean && quire build   # Clean build (recommended for production)
+```
+
+## Generating PDF
+
+```bash
+quire pdf --build            # Build first, then generate PDF
+quire pdf --build --open     # Generate and open PDF
+quire pdf --lib prince       # Use PrinceXML instead of Paged.js
+```
+
+## Generating EPUB
+
+```bash
+quire epub --build           # Build first, then generate EPUB
+quire epub --build --open    # Generate and open EPUB
+```
+
+## Full Publication Build
+
+```bash
+quire clean && quire build && quire pdf && quire epub
+```
+
+## Troubleshooting
+
+```bash
+quire validate               # Check YAML files for errors
+quire info                   # Show version information
+quire build --verbose        # Build with detailed output
+```
+
+See full documentation: https://quire.getty.edu/docs-v1/

package/src/lib/logger/index.js

@@ -162,7 +162,7 @@ export default function createLogger(name = 'quire', level) {
       const prefix = config.get('logPrefix')
       const prefixStyle = config.get('logPrefixStyle')
       const showLevel = config.get('logShowLevel')
-      const useColor = config.get('logUseColor')
+      const useColor = config.get('logUseColor') && !process.env.NO_COLOR
       const colorMessages = config.get('logColorMessages')
 
       const parts = []

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

@@ -475,3 +475,104 @@ test.serial('invalid env var value falls back to info', async (t) => {
     }
   }
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NO_COLOR environment variable tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.serial('logger disables color when NO_COLOR env var is set', async (t) => {
+  const { sandbox } = t.context
+  const consoleErrorStub = sandbox.stub(console, 'error')
+  const originalNoColor = process.env.NO_COLOR
+
+  try {
+    process.env.NO_COLOR = '1'
+
+    const mockConfig = {
+      get: sandbox.stub().callsFake((key) => ({
+        logPrefix: 'quire',
+        logPrefixStyle: 'bracket',
+        logShowLevel: true,
+        logUseColor: true, // Config says use color, but NO_COLOR overrides
+        logColorMessages: true,
+      })[key])
+    }
+
+    const { default: createLoggerMocked } = await esmock('./index.js', {
+      '#lib/conf/config.js': { default: mockConfig }
+    })
+
+    const log = createLoggerMocked('test:nocolor', 'error')
+    log.error('Error message')
+
+    t.true(consoleErrorStub.calledOnce)
+    const output = consoleErrorStub.firstCall.args.join(' ')
+    // Should not contain ANSI escape sequences when NO_COLOR is set
+    t.false(/\u001b\[/.test(output), 'output should not contain ANSI escape codes')
+    // Should still contain the actual text
+    t.true(output.includes('[quire]'))
+    t.true(output.includes('ERROR'))
+    t.true(output.includes('Error message'))
+  } finally {
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR
+    } else {
+      process.env.NO_COLOR = originalNoColor
+    }
+  }
+})
+
+test.serial('logger uses color when NO_COLOR env var is not set and config enables color', async (t) => {
+  const { sandbox } = t.context
+  const consoleErrorStub = sandbox.stub(console, 'error')
+  const originalNoColor = process.env.NO_COLOR
+
+  try {
+    delete process.env.NO_COLOR
+
+    const mockConfig = {
+      get: sandbox.stub().callsFake((key) => ({
+        logPrefix: 'quire',
+        logPrefixStyle: 'bracket',
+        logShowLevel: true,
+        logUseColor: true,
+        logColorMessages: true,
+      })[key])
+    }
+
+    // Create a mock chalk that always applies ANSI styling regardless of TTY/env
+    const ansiRed = (s) => `\u001b[91m${s}\u001b[39m`
+    const ansiRedInverse = (s) => `\u001b[91m\u001b[7m${s}\u001b[27m\u001b[39m`
+    const ansiBold = (s) => `\u001b[1m${s}\u001b[22m`
+    const mockChalk = {
+      bold: ansiBold,
+      gray: (s) => s,
+      yellow: (s) => s,
+      magenta: (s) => s,
+      red: ansiRed,
+      redBright: { inverse: ansiRedInverse },
+      'yellow.inverse': (s) => s,
+    }
+    // Support chained properties
+    mockChalk.yellow.inverse = (s) => s
+
+    const { default: createLoggerMocked } = await esmock('./index.js', {
+      '#lib/conf/config.js': { default: mockConfig },
+      'chalk': { default: mockChalk }
+    })
+
+    const log = createLoggerMocked('test:withcolor', 'error')
+    log.error('Error message')
+
+    t.true(consoleErrorStub.calledOnce)
+    const output = consoleErrorStub.firstCall.args.join(' ')
+    // Should contain ANSI escape sequences when color is enabled and NO_COLOR not set
+    t.true(/\u001b\[/.test(output), 'output should contain ANSI escape codes')
+  } finally {
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR
+    } else {
+      process.env.NO_COLOR = originalNoColor
+    }
+  }
+})

package/src/main.js

@@ -2,6 +2,8 @@ import { Command, Argument, Option } from 'commander'
 import {
   arrayToArgument,
   arrayToOption,
+  colorOption,
+  noColorOption,
   quietOption,
   verboseOption,
   debugOption
@@ -34,7 +36,22 @@ Output Modes:
 
   Set defaults: quire settings set verbose true
 
+Color Output:
+  --no-color       Disable colored output
+  --color          Force colored output (overrides NO_COLOR env var)
+
+  Respects NO_COLOR environment variable (https://no-color.org/)
+  Set default: quire settings set logUseColor false
+
+Paging:
+  --no-pager             Disable paging for long output
+  NO_PAGER=1             Disable paging via environment variable
+  PAGER=cat              Traditional Unix alternative (passes output through)
+
 Environment Variables:
+  NO_COLOR               Disable colored output (https://no-color.org/)
+  NO_PAGER=1             Disable paging for long output
+  PAGER=<program>        Set pager program (default: less). Use PAGER=cat to disable
   DEBUG=quire:*          Enable debug output for all modules
   DEBUG=quire:lib:pdf    Enable debug output for PDF module only
   DEBUG=quire:lib:*      Enable debug output for all lib modules
@@ -43,13 +60,15 @@ Examples:
   $ quire build                  Build the publication
   $ quire build --verbose        Build with detailed progress
   $ quire build --debug          Build with debug output
+  $ quire build --no-color       Build without colored output
+  $ NO_COLOR=1 quire build       Build without colored output
   $ DEBUG=quire:* quire pdf      Generate PDF with debug output
 `
 
 /**
  * Quire CLI implements the command pattern.
  *
- * The `main` module acts as the _receiver_, parsing input from the client,
+ * The \`main\` module acts as the _receiver_, parsing input from the client,
  * calling the appropriate command module(s), managing messages between modules,
  * and sending formatted messages to the client for display.
  */
@@ -59,9 +78,12 @@ program
   .name('quire')
   .description('Quire command-line interface')
   .version(version, '-V, --version', 'output quire version number')
+  .addOption(arrayToOption(colorOption))
+  .addOption(arrayToOption(noColorOption))
   .addOption(arrayToOption(quietOption))
   .addOption(arrayToOption(verboseOption))
   .addOption(arrayToOption(debugOption))
+  .option('--no-pager', 'disable paging for long output')
   .addHelpText('after', mainHelpText)
   .configureHelp({
     helpWidth: 80,
@@ -80,6 +102,8 @@ program
  * - --quiet: Suppress progress spinners (for CI/scripts)
  * - --verbose: Show detailed progress (paths, timing, steps)
  * - --debug: Enable DEBUG namespace + tool debug modes (for developers)
+ * - --no-color: Disable colored output (sets NO_COLOR env var)
+ * - --color: Force colored output (overrides NO_COLOR env var)
  *
  * These global options are passed through to commands via opts()
  * and should be merged with command-level options.
@@ -87,11 +111,26 @@ program
 program.hook('preAction', (thisCommand) => {
   const opts = thisCommand.opts()
 
+  // Handle --no-color / --color flag
+  // Sets NO_COLOR env var for chalk, ora, and logger to read
+  if (opts.color === false) {
+    process.env.NO_COLOR = '1'
+    delete process.env.FORCE_COLOR
+  } else if (opts.color === true) {
+    delete process.env.NO_COLOR
+    process.env.FORCE_COLOR = '1'
+  }
+
   // --debug or config.debug enables the quire:* DEBUG namespace for internal logging
   // CLI flag takes precedence, then config setting
   if (opts.debug ?? config.get('debug')) {
     enableDebug('quire:*')
   }
+
+  // --no-pager sets pager to false; propagate via env var for pager utility
+  if (opts.pager === false) {
+    process.env.NO_PAGER = '1'
+  }
 })
 
 /**