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

package/src/lib/help/index.js

@@ -1,146 +0,0 @@
-/**
- * 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))
-}
-
-/**
- * Get available topic names from the topics directory
- * @returns {Promise<string[]>} Topic names (filenames without .md)
- */
-async function getTopicNames() {
-  if (!await fs.pathExists(TOPICS_DIR)) return []
-  const files = await fs.readdir(TOPICS_DIR)
-  return files.filter((f) => f.endsWith('.md')).map((f) => path.basename(f, '.md'))
-}
-
-/**
- * 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)) {
-    const validTopics = await getTopicNames()
-    throw new HelpTopicNotFoundError(name, validTopics)
-  }
-
-  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

@@ -1,188 +0,0 @@
-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()
-      .onFirstCall().resolves(false)   // topic file does not exist
-      .onSecondCall().resolves(true),  // topics directory exists
-    readdir: sandbox.stub().resolves(['epub.md', 'pdf.md', 'debugging.md'])
-  }
-
-  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('getTopicContent() suggests similar topic for typo', async (t) => {
-  const { sandbox } = t.context
-
-  const mockFs = {
-    pathExists: sandbox.stub()
-      .onFirstCall().resolves(false)
-      .onSecondCall().resolves(true),
-    readdir: sandbox.stub().resolves([
-      'configuration.md', 'debugging.md', 'epub.md',
-      'pdf.md', 'publishing.md', 'workflows.md'
-    ])
-  }
-
-  const { getTopicContent } = await esmock('./index.js', {
-    'fs-extra': mockFs
-  })
-
-  const error = await t.throwsAsync(
-    () => getTopicContent('edub'),
-    { name: 'HelpTopicNotFoundError' }
-  )
-
-  t.is(error.suggestion, 'Did you mean: epub?')
-})
-
-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

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

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

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

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

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