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

package/src/lib/help/index.js

@@ -0,0 +1,135 @@
+/**
+ * Help topics module
+ *
+ * Provides loading and rendering of help topics from markdown files.
+ * Topics are stored in the topics/ directory as markdown files with
+ * YAML frontmatter for metadata.
+ *
+ * @module lib/help
+ */
+import fs from 'fs-extra'
+import { marked } from 'marked'
+import { markedTerminal } from 'marked-terminal'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { HelpTopicNotFoundError } from '#src/errors/index.js'
+import { extractFrontmatter, stripFrontmatter } from './frontmatter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// Nota bene: env var override for development/testing only, not user-configurable
+const TOPICS_DIR =
+  process.env.QUIRE_HELP_TOPICS_DIR || path.join(__dirname, 'topics');
+
+/**
+ * Topic metadata extracted from markdown frontmatter
+ * @typedef {Object} TopicMeta
+ * @property {string} name - Topic identifier (filename without .md)
+ * @property {string} title - Display title
+ * @property {string} description - Brief description for listing
+ */
+
+/**
+ * List all available help topics
+ * @returns {Promise<TopicMeta[]>} Array of topic metadata sorted by name
+ */
+async function listTopics() {
+  if (!await fs.pathExists(TOPICS_DIR)) {
+    return []
+  }
+
+  const files = await fs.readdir(TOPICS_DIR)
+  const topics = []
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue
+
+    const name = path.basename(file, '.md')
+    const content = await fs.readFile(path.join(TOPICS_DIR, file), 'utf-8')
+    const meta = extractFrontmatter(content)
+
+    topics.push({
+      name,
+      title: meta.title || name,
+      description: meta.description || ''
+    })
+  }
+
+  return topics.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Load a help topic by name
+ * @param {string} name - Topic name (without .md extension)
+ * @returns {Promise<string>} Topic content
+ * @throws {HelpTopicNotFoundError} If topic does not exist
+ */
+async function loadTopic(name) {
+  const filePath = path.join(TOPICS_DIR, `${name}.md`)
+
+  if (!await fs.pathExists(filePath)) {
+    throw new HelpTopicNotFoundError(name)
+  }
+
+  const content = await fs.readFile(filePath, 'utf-8')
+  return stripFrontmatter(content)
+}
+
+/**
+ * Render markdown content for terminal display
+ * @param {string} content - Markdown content
+ * @returns {string} Rendered content for terminal
+ */
+function renderTopic(content) {
+  marked.use(markedTerminal())
+  return marked.parse(content).trimEnd()
+}
+
+/**
+ * Format topic list for display
+ * @param {TopicMeta[]} topics - Array of topic metadata
+ * @returns {string} Formatted topic list
+ */
+function formatTopicList(topics) {
+  if (topics.length === 0) {
+    return 'No help topics available.'
+  }
+
+  const lines = ['Available help topics:\n']
+  topics.forEach(({ name, description }) => {
+    lines.push(`  ${name.padEnd(16)} ${description}`)
+  })
+  lines.push('\nRun "quire help <topic>" for detailed information.')
+  lines.push('Run "quire <command> --help" for command-specific options.')
+
+  return lines.join('\n')
+}
+
+/**
+ * Get formatted list of available help topics
+ * @returns {Promise<string>} Formatted topic list for display
+ */
+export async function getTopicList() {
+  const topics = await listTopics()
+  return formatTopicList(topics)
+}
+
+/**
+ * Get formatted help content for a topic
+ * @param {string} name - Topic name
+ * @returns {Promise<string>} Rendered topic content
+ * @throws {HelpTopicNotFoundError} If topic does not exist
+ */
+export async function getTopicContent(name) {
+  const content = await loadTopic(name)
+  return renderTopic(content)
+}
+
+/**
+ * Get the topics directory path (for testing)
+ * @returns {string} Path to topics directory
+ */
+export function getTopicsDir() {
+  return TOPICS_DIR
+}

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

@@ -0,0 +1,160 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Help Topics Library Tests
+ *
+ * Tests the help topics public API.
+ */
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('getTopicList() returns formatted list of topics', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(true),
+    readdir: sandbox.stub().resolves(['workflows.md', 'debugging.md']),
+    readFile: sandbox.stub()
+  }
+
+  mockFs.readFile.withArgs(sinon.match(/workflows\.md/), 'utf-8').resolves(`---
+title: Common Workflows
+description: Step-by-step guides
+---
+# Workflows`)
+
+  mockFs.readFile.withArgs(sinon.match(/debugging\.md/), 'utf-8').resolves(`---
+title: Debugging
+description: Troubleshooting help
+---
+# Debugging`)
+
+  const { getTopicList } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const output = await getTopicList()
+
+  t.true(output.includes('Available help topics:'))
+  t.true(output.includes('debugging'))
+  t.true(output.includes('Troubleshooting help'))
+  t.true(output.includes('workflows'))
+  t.true(output.includes('Step-by-step guides'))
+  t.true(output.includes('Run "quire help <topic>"'))
+})
+
+test('getTopicList() returns message when no topics available', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(false)
+  }
+
+  const { getTopicList } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const output = await getTopicList()
+
+  t.is(output, 'No help topics available.')
+})
+
+test('getTopicList() returns message when topics directory is empty', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(true),
+    readdir: sandbox.stub().resolves([])
+  }
+
+  const { getTopicList } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const output = await getTopicList()
+
+  t.is(output, 'No help topics available.')
+})
+
+test('getTopicContent() loads and renders topic', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(true),
+    readFile: sandbox.stub().resolves('# Test\n\nContent here.')
+  }
+
+  const { getTopicContent } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const content = await getTopicContent('test')
+
+  t.is(typeof content, 'string')
+  t.true(content.includes('Test'))
+  t.true(content.includes('Content here'))
+})
+
+test('getTopicContent() strips frontmatter from content', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(true),
+    readFile: sandbox.stub().resolves(`---
+title: Test Topic
+description: A test
+---
+# Test Topic
+
+This is the content.`)
+  }
+
+  const { getTopicContent } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const content = await getTopicContent('test')
+
+  t.true(content.includes('Test Topic'))
+  t.true(content.includes('This is the content'))
+  t.false(content.includes('---'))
+  t.false(content.includes('title:'))
+})
+
+test('getTopicContent() throws HelpTopicNotFoundError for missing topic', async (t) => {
+  const { sandbox } = t.context
+
+  const mockFs = {
+    pathExists: sandbox.stub().resolves(false)
+  }
+
+  const { getTopicContent } = await esmock('./index.js', {
+    'fs-extra': mockFs
+  })
+
+  const error = await t.throwsAsync(
+    () => getTopicContent('nonexistent'),
+    { name: 'HelpTopicNotFoundError' }
+  )
+
+  t.is(error.code, 'HELP_TOPIC_NOT_FOUND')
+  t.is(error.topic, 'nonexistent')
+})
+
+test('getTopicsDir() returns the topics directory path', async (t) => {
+  const { getTopicsDir } = await import('./index.js')
+
+  const dir = getTopicsDir()
+
+  t.true(dir.endsWith('topics'))
+  t.true(dir.includes(`lib${path.sep}help`))
+})

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

@@ -0,0 +1,77 @@
+---
+title: Configuration
+description: Project and CLI configuration options
+---
+
+# Configuration
+
+## Project Configuration
+
+The `content/_data/publication.yaml` file contains publication settings:
+
+```yaml
+title: My Publication
+subtitle: A Quire Book
+contributor:
+  - type: primary
+    first_name: Jane
+    last_name: Doe
+
+url: https://my-publication.example.com
+```
+
+## Common Settings
+
+### Publication Metadata
+
+```yaml
+title: Publication Title
+subtitle: Optional Subtitle
+reading_line: Additional context
+pub_date: 2024-01-15
+```
+
+### Output Configuration
+
+```yaml
+pdf:
+  output: _site/downloads/publication.pdf
+
+epub:
+  output: _site/downloads/publication.epub
+```
+
+### Build Options
+
+```yaml
+debug: false
+verbose: false
+```
+
+## CLI Configuration
+
+The CLI stores user preferences separately from project settings.
+
+### View Configuration
+
+```bash
+quire config                 # Show all settings
+quire config path            # Show config file location
+```
+
+### Configuration File Location
+
+- **macOS:** `~/Library/Preferences/quire-cli-nodejs/config.json`
+- **Linux:** `~/.config/quire-cli-nodejs/config.json`
+- **Windows:** `%APPDATA%\quire-cli-nodejs\config.json`
+
+## Environment Variables
+
+Override settings via environment variables:
+
+```bash
+DEBUG=quire:* quire build            # Enable debug output
+QUIRE_LOG_LEVEL=debug quire preview  # Set log level
+```
+
+See full documentation: https://quire.getty.edu/docs-v1/configuration/

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

@@ -0,0 +1,69 @@
+---
+title: Debugging
+description: Troubleshooting common issues
+---
+
+# Debugging Quire Projects
+
+## Debug Output
+
+Enable debug output to see detailed information:
+
+```bash
+quire build --debug          # Enable debug mode
+DEBUG=quire:* quire build    # Enable all debug namespaces
+DEBUG=quire:lib:pdf quire pdf  # Debug PDF module only
+```
+
+## Common Issues
+
+### Build Fails with YAML Errors
+
+Run validation to identify syntax issues:
+
+```bash
+quire validate
+```
+
+Common YAML problems:
+- Missing colons after keys
+- Incorrect indentation (use spaces, not tabs)
+- Unquoted special characters
+- Missing closing quotes
+
+### PDF Generation Fails
+
+1. Check that build output exists: `quire build`
+2. Run with debug: `quire pdf --debug`
+3. Verify the PDF engine is installed
+
+### EPUB Generation Fails
+
+1. Ensure the build is complete: `quire build`
+2. Check for missing images or broken links
+3. Run with debug: `quire epub --debug`
+
+### Preview Not Updating
+
+Try a clean build:
+
+```bash
+quire clean && quire preview
+```
+
+### "Not in a Quire project" Error
+
+Make sure you're in a directory containing:
+- `content/` directory
+- An Eleventy configuration file (`.eleventy.js` or `eleventy.config.js`)
+
+```bash
+cd your-project-name
+quire preview
+```
+
+## Getting Help
+
+- Documentation: https://quire.getty.edu/docs-v1/
+- Community Forum: https://github.com/thegetty/quire/discussions
+- Issue Tracker: https://github.com/thegetty/quire/issues

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/