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

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

@@ -0,0 +1,74 @@
+---
+title: EPUB Generation
+description: Creating e-book publications
+---
+
+# EPUB Generation
+
+## Quick Start
+
+```bash
+quire epub --build           # Build and generate EPUB
+quire epub --build --open    # Build, generate, and open EPUB
+```
+
+## EPUB Engines
+
+Quire supports two EPUB engines:
+
+### epubjs (Default)
+
+JavaScript-based EPUB generation.
+
+```bash
+quire epub                   # Uses epubjs by default
+quire epub --lib epubjs      # Explicit epubjs
+```
+
+### Pandoc
+
+Universal document converter with EPUB support. Requires separate installation.
+
+```bash
+quire epub --lib pandoc      # Use Pandoc
+```
+
+## Configuration
+
+EPUB settings in `content/_data/config.yaml`:
+
+```yaml
+epub:
+  output: _site/downloads/my-publication.epub
+  # Additional EPUB-specific settings
+```
+
+## Troubleshooting
+
+### EPUB fails validation
+
+Common issues:
+- Missing required metadata in `content/_data/publication.yaml`
+- Invalid image formats (use JPEG or PNG)
+- Broken internal links
+
+### Images not appearing
+
+1. Check image paths are relative
+2. Ensure images are in supported formats
+3. Verify images exist in the build output
+
+### EPUB not opening in reader
+
+1. Validate the EPUB file structure
+2. Check for malformed HTML in content
+3. Ensure all required files are included
+
+## Testing Your EPUB
+
+Open in different readers to verify:
+- Apple Books (macOS/iOS)
+- Calibre (cross-platform)
+- Adobe Digital Editions
+
+See full documentation: https://quire.getty.edu/docs-v1/epub-output/

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/platform.js

@@ -0,0 +1,95 @@
+/**
+ * Platform detection utilities
+ *
+ * Provides OS detection and platform-specific helpers for the CLI.
+ *
+ * @module lib/platform
+ */
+import os from 'node:os'
+
+/**
+ * Platform identifiers
+ * @readonly
+ * @enum {string}
+ */
+export const Platform = {
+  MACOS: 'macos',
+  WINDOWS: 'windows',
+  LINUX: 'linux',
+  UNKNOWN: 'unknown',
+}
+
+/**
+ * Get the current platform identifier
+ * @returns {string} Platform identifier (macos, windows, linux, or unknown)
+ */
+export function getPlatform() {
+  switch (process.platform) {
+    case 'darwin':
+      return Platform.MACOS
+    case 'win32':
+      return Platform.WINDOWS
+    case 'linux':
+      return Platform.LINUX
+    default:
+      return Platform.UNKNOWN
+  }
+}
+
+/**
+ * Get a human-readable platform name
+ * @returns {string} Human-readable OS name (e.g., "macOS 14.0", "Windows 11", "Linux")
+ */
+export function getPlatformName() {
+  const platform = getPlatform()
+  const release = os.release()
+
+  switch (platform) {
+    case Platform.MACOS: {
+      // Darwin kernel version to macOS version mapping (approximate)
+      const majorVersion = parseInt(release.split('.')[0], 10)
+      // Darwin 23.x = macOS 14 (Sonoma), 22.x = macOS 13, etc.
+      const macOSVersion = majorVersion >= 20 ? majorVersion - 9 : majorVersion - 4
+      return `macOS ${macOSVersion >= 14 ? macOSVersion : release}`
+    }
+    case Platform.WINDOWS:
+      return `Windows (${release})`
+    case Platform.LINUX:
+      return `Linux (${release})`
+    default:
+      return `${process.platform} (${release})`
+  }
+}
+
+/**
+ * Check if running on macOS
+ * @returns {boolean}
+ */
+export function isMacOS() {
+  return process.platform === 'darwin'
+}
+
+/**
+ * Check if running on Windows
+ * @returns {boolean}
+ */
+export function isWindows() {
+  return process.platform === 'win32'
+}
+
+/**
+ * Check if running on Linux
+ * @returns {boolean}
+ */
+export function isLinux() {
+  return process.platform === 'linux'
+}
+
+export default {
+  Platform,
+  getPlatform,
+  getPlatformName,
+  isMacOS,
+  isWindows,
+  isLinux,
+}

package/src/lib/project/build.js

@@ -2,12 +2,15 @@
  * Build detection module
  *
  * Detects if build output exists and provides build status information.
+ * Uses shared output path resolution to ensure consistency with the
+ * doctor command and generation commands.
  *
  * @module lib/project/build
  */
 import fs from 'node:fs'
 import path from 'node:path'
 import paths from './paths.js'
+import { getPdfOutputPaths, getEpubOutputPaths, getEpubBuildDir } from './output-paths.js'
 
 /**
  * Get build output information
@@ -17,45 +20,60 @@ import paths from './paths.js'
  */
 export function getBuildInfo(projectRoot = paths.getProjectRoot()) {
   const sitePath = path.join(projectRoot, '_site')
-  const epubPath = path.join(projectRoot, '_epub')
-  const pdfFiles = ['pagedjs.pdf', 'prince.pdf']
+  const epubBuildPath = getEpubBuildDir({ projectRoot })
 
   const info = {
     site: {
       exists: fs.existsSync(sitePath),
       path: sitePath,
-      mtime: null,
+      lastModified: null,
     },
     epub: {
-      exists: fs.existsSync(epubPath),
-      path: epubPath,
-      mtime: null,
+      exists: false,
+      paths: [],
+      buildDir: epubBuildPath,
+      buildDirExists: fs.existsSync(epubBuildPath),
+      lastModified: null,
     },
     pdf: {
       exists: false,
       paths: [],
-      mtime: null,
+      lastModified: null,
     },
   }
 
-  // Get modification times if directories exist
+  // Get last modified times if directories exist
   if (info.site.exists) {
-    info.site.mtime = fs.statSync(sitePath).mtime
+    const { mtime: lastModified } = fs.statSync(sitePath)
+    info.site.lastModified = lastModified
   }
-  if (info.epub.exists) {
-    info.epub.mtime = fs.statSync(epubPath).mtime
+  if (info.epub.buildDirExists) {
+    const { mtime: lastModified } = fs.statSync(epubBuildPath)
+    info.epub.lastModified = lastModified
   }
 
-  // Check for PDF files
-  for (const file of pdfFiles) {
-    const pdfPath = path.join(projectRoot, file)
+  // Check for EPUB files using shared path resolution
+  const epubPaths = getEpubOutputPaths({ projectRoot })
+  for (const epubPath of epubPaths) {
+    if (fs.existsSync(epubPath)) {
+      info.epub.exists = true
+      info.epub.paths.push(epubPath)
+      const { mtime: lastModified } = fs.statSync(epubPath)
+      if (!info.epub.lastModified || lastModified > info.epub.lastModified) {
+        info.epub.lastModified = lastModified
+      }
+    }
+  }
+
+  // Check for PDF files using shared path resolution
+  const pdfPaths = getPdfOutputPaths({ projectRoot })
+  for (const pdfPath of pdfPaths) {
     if (fs.existsSync(pdfPath)) {
       info.pdf.exists = true
       info.pdf.paths.push(pdfPath)
-      // Use most recent mtime if multiple PDFs exist
-      const mtime = fs.statSync(pdfPath).mtime
-      if (!info.pdf.mtime || mtime > info.pdf.mtime) {
-        info.pdf.mtime = mtime
+      const { mtime: lastModified } = fs.statSync(pdfPath)
+      if (!info.pdf.lastModified || lastModified > info.pdf.lastModified) {
+        info.pdf.lastModified = lastModified
       }
     }
   }
@@ -77,20 +95,21 @@ export function hasSiteOutput(projectRoot = paths.getProjectRoot()) {
 /**
  * Check if epub build output exists
  *
+ * Checks for the intermediate _epub build directory.
+ *
  * @param {string} [projectRoot] - Project root directory (defaults to cwd)
  * @returns {boolean} True if _epub directory exists
  */
 export function hasEpubOutput(projectRoot = paths.getProjectRoot()) {
-  const epubPath = path.join(projectRoot, '_epub')
+  const epubPath = getEpubBuildDir({ projectRoot })
   return fs.existsSync(epubPath)
 }
 
 /**
  * Check if PDF output exists
  *
- * Checks for PDF output at common locations:
- * - Default library outputs: pagedjs.pdf, prince.pdf
- * - Specific library output when lib option provided
+ * Uses shared path resolution to check all possible PDF output locations,
+ * including config-aware custom paths and default engine-named paths.
  *
  * @param {Object} [options]
  * @param {string} [options.lib] - Specific library to check ('pagedjs' or 'prince')
@@ -105,9 +124,9 @@ export function hasPdfOutput(options = {}) {
     return fs.existsSync(pdfPath)
   }
 
-  // Check for any common PDF output
-  const pdfFiles = ['pagedjs.pdf', 'prince.pdf']
-  return pdfFiles.some((file) => fs.existsSync(path.join(projectRoot, file)))
+  // Check all possible PDF output locations
+  const pdfPaths = getPdfOutputPaths({ projectRoot })
+  return pdfPaths.some((pdfPath) => fs.existsSync(pdfPath))
 }
 
 /**

package/src/lib/project/build.test.js

@@ -84,6 +84,7 @@ test('getBuildInfo returns correct status for existing builds', async (t) => {
   vol.fromJSON({
     [memfsPath('_site', 'index.html')]: '<html></html>',
     [memfsPath('_epub', 'content.opf')]: '<package></package>',
+    [memfsPath('epubjs.epub')]: 'PK\x03\x04',
     [memfsPath('pagedjs.pdf')]: '%PDF-1.4',
   })
 
@@ -95,15 +96,17 @@ test('getBuildInfo returns correct status for existing builds', async (t) => {
 
   t.true(info.site.exists)
   t.is(info.site.path, nativePath('_site'))
-  t.truthy(info.site.mtime)
+  t.truthy(info.site.lastModified)
 
   t.true(info.epub.exists)
-  t.is(info.epub.path, nativePath('_epub'))
-  t.truthy(info.epub.mtime)
+  t.true(info.epub.buildDirExists)
+  t.is(info.epub.buildDir, nativePath('_epub'))
+  t.true(info.epub.paths.includes(nativePath('epubjs.epub')))
+  t.truthy(info.epub.lastModified)
 
   t.true(info.pdf.exists)
   t.deepEqual(info.pdf.paths, [nativePath('pagedjs.pdf')])
-  t.truthy(info.pdf.mtime)
+  t.truthy(info.pdf.lastModified)
 })
 
 test('getBuildInfo returns correct status for missing builds', async (t) => {
@@ -120,14 +123,15 @@ test('getBuildInfo returns correct status for missing builds', async (t) => {
   const info = getBuildInfo(testRoot)
 
   t.false(info.site.exists)
-  t.is(info.site.mtime, null)
+  t.is(info.site.lastModified, null)
 
   t.false(info.epub.exists)
-  t.is(info.epub.mtime, null)
+  t.false(info.epub.buildDirExists)
+  t.is(info.epub.lastModified, null)
 
   t.false(info.pdf.exists)
   t.deepEqual(info.pdf.paths, [])
-  t.is(info.pdf.mtime, null)
+  t.is(info.pdf.lastModified, null)
 })
 
 test('getBuildInfo returns multiple PDF paths when both exist', async (t) => {
@@ -148,7 +152,25 @@ test('getBuildInfo returns multiple PDF paths when both exist', async (t) => {
   t.is(info.pdf.paths.length, 2)
   t.true(info.pdf.paths.includes(nativePath('pagedjs.pdf')))
   t.true(info.pdf.paths.includes(nativePath('prince.pdf')))
-  t.truthy(info.pdf.mtime)
+  t.truthy(info.pdf.lastModified)
+})
+
+test('getBuildInfo detects epub build dir without .epub files', async (t) => {
+  const { vol } = t.context
+
+  vol.fromJSON({
+    [memfsPath('_epub', 'content.opf')]: '<package></package>',
+  })
+
+  const { getBuildInfo } = await esmock('./build.js', {
+    'node:fs': createFsFromVolume(vol),
+  })
+
+  const info = getBuildInfo(testRoot)
+
+  t.false(info.epub.exists, 'no .epub files should mean exists is false')
+  t.true(info.epub.buildDirExists, '_epub directory should be detected')
+  t.truthy(info.epub.lastModified, 'lastModified from _epub dir should be present')
 })
 
 test('requireBuildOutput throws when site output missing', async (t) => {

package/src/lib/project/detect.js

@@ -7,7 +7,21 @@
  */
 import fs from 'node:fs'
 
-const QUIRE_DOT_FILES = Object.freeze([
+/**
+ * Files that indicate a Quire project directory.
+ *
+ * These marker files are created by `quire new` or exist in Quire project templates.
+ * The presence of any one of these files indicates the directory is a Quire project root.
+ *
+ * @constant {ReadonlyArray<string>}
+ *
+ * @example
+ * // Check if a file is a project marker
+ * if (PROJECT_MARKERS.includes(filename)) {
+ *   console.log('This is a Quire project root')
+ * }
+ */
+export const PROJECT_MARKERS = Object.freeze([
   '.eleventy.js',
   '.quire',
   '.quire-11ty',
@@ -29,5 +43,5 @@ const QUIRE_DOT_FILES = Object.freeze([
  */
 export default function (dirpath) {
   return fs.readdirSync(dirpath)
-    .find((entry) => QUIRE_DOT_FILES.includes(entry))
+    .find((entry) => PROJECT_MARKERS.includes(entry))
 }

package/src/lib/project/index.js

@@ -4,8 +4,8 @@
  * Provides project-level concerns including paths, detection, configuration,
  * build status, and version management.
  */
-import paths, { Paths } from './paths.js'
-import detect from './detect.js'
+import paths, { DATA_DIR, Paths, REQUIRED_DATA_FILES, SOURCE_DIRECTORIES } from './paths.js'
+import detect, { PROJECT_MARKERS } from './detect.js'
 import { loadProjectConfig } from './config.js'
 import {
   getBuildInfo,
@@ -14,6 +14,13 @@ import {
   hasSiteOutput,
   requireBuildOutput,
 } from './build.js'
+import {
+  getPdfOutputPaths,
+  getEpubOutputPaths,
+  getEpubBuildDir,
+  PDF_ENGINES,
+  EPUB_ENGINES,
+} from './output-paths.js'
 import {
   getVersion,
   setVersion,
@@ -23,8 +30,17 @@ import {
 } from './version.js'
 
 export {
+  DATA_DIR,
+  EPUB_ENGINES,
+  PDF_ENGINES,
+  PROJECT_MARKERS,
+  REQUIRED_DATA_FILES,
+  SOURCE_DIRECTORIES,
   detect,
   getBuildInfo,
+  getEpubBuildDir,
+  getEpubOutputPaths,
+  getPdfOutputPaths,
   hasEpubOutput,
   hasPdfOutput,
   hasSiteOutput,