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

package/src/lib/help/frontmatter.js

@@ -0,0 +1,77 @@
+/**
+ * YAML frontmatter parsing utilities
+ *
+ * Extracts and strips YAML frontmatter from markdown content.
+ * Frontmatter is delimited by `---` on its own line.
+ *
+ * @module lib/help/frontmatter
+ */
+import yaml from 'js-yaml'
+
+/** Regex to match YAML frontmatter block */
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---/
+
+/**
+ * Extract YAML frontmatter from markdown content
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {Object} Parsed frontmatter data or empty object if none/invalid
+ *
+ * @example
+ * const meta = extractFrontmatter(`---
+ * title: My Topic
+ * description: A description
+ * ---
+ * # Content`)
+ * // => { title: 'My Topic', description: 'A description' }
+ */
+export function extractFrontmatter(content) {
+  const match = content.match(FRONTMATTER_REGEX)
+  if (!match) return {}
+
+  try {
+    return yaml.load(match[1]) || {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Strip YAML frontmatter from markdown content
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {string} Content without frontmatter block
+ *
+ * @example
+ * const body = stripFrontmatter(`---
+ * title: My Topic
+ * ---
+ * # Content`)
+ * // => '# Content'
+ */
+export function stripFrontmatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, '')
+}
+
+/**
+ * Parse markdown content with frontmatter
+ *
+ * Convenience function that returns both metadata and content body.
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {{ data: Object, content: string }} Parsed frontmatter and body
+ *
+ * @example
+ * const { data, content } = parseFrontmatter(`---
+ * title: My Topic
+ * ---
+ * # Content`)
+ * // data => { title: 'My Topic' }
+ * // content => '# Content'
+ */
+export function parseFrontmatter(content) {
+  return {
+    data: extractFrontmatter(content),
+    content: stripFrontmatter(content)
+  }
+}

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

@@ -0,0 +1,139 @@
+import test from 'ava'
+
+import {
+  extractFrontmatter,
+  stripFrontmatter,
+  parseFrontmatter
+} from './frontmatter.js'
+
+/**
+ * Frontmatter Parsing Tests
+ */
+
+// extractFrontmatter tests
+
+test('extractFrontmatter() returns parsed YAML data', (t) => {
+  const content = `---
+title: Test Topic
+description: A test description
+---
+# Content`
+
+  const result = extractFrontmatter(content)
+
+  t.deepEqual(result, {
+    title: 'Test Topic',
+    description: 'A test description'
+  })
+})
+
+test('extractFrontmatter() returns empty object when no frontmatter', (t) => {
+  const content = '# Just Content\n\nNo frontmatter here.'
+
+  const result = extractFrontmatter(content)
+
+  t.deepEqual(result, {})
+})
+
+test('extractFrontmatter() returns empty object for invalid YAML', (t) => {
+  const content = `---
+title: [invalid yaml
+---
+# Content`
+
+  const result = extractFrontmatter(content)
+
+  t.deepEqual(result, {})
+})
+
+test('extractFrontmatter() handles values containing colons', (t) => {
+  const content = `---
+url: https://example.com/path
+title: "Part 1: Introduction"
+---
+# Content`
+
+  const result = extractFrontmatter(content)
+
+  t.is(result.url, 'https://example.com/path')
+  t.is(result.title, 'Part 1: Introduction')
+})
+
+test('extractFrontmatter() handles arrays and nested objects', (t) => {
+  const content = `---
+tags:
+  - one
+  - two
+author:
+  name: Test
+  email: test@example.com
+---
+# Content`
+
+  const result = extractFrontmatter(content)
+
+  t.deepEqual(result.tags, ['one', 'two'])
+  t.deepEqual(result.author, { name: 'Test', email: 'test@example.com' })
+})
+
+// stripFrontmatter tests
+
+test('stripFrontmatter() removes frontmatter block', (t) => {
+  const content = `---
+title: Test
+---
+# Content
+
+Body text.`
+
+  const result = stripFrontmatter(content)
+
+  t.is(result, '# Content\n\nBody text.')
+})
+
+test('stripFrontmatter() returns content unchanged when no frontmatter', (t) => {
+  const content = '# Just Content\n\nNo frontmatter.'
+
+  const result = stripFrontmatter(content)
+
+  t.is(result, content)
+})
+
+test('stripFrontmatter() handles frontmatter without trailing newline', (t) => {
+  const content = `---
+title: Test
+---# Content`
+
+  const result = stripFrontmatter(content)
+
+  t.is(result, '# Content')
+})
+
+// parseFrontmatter tests
+
+test('parseFrontmatter() returns both data and content', (t) => {
+  const content = `---
+title: Test Topic
+description: A description
+---
+# Heading
+
+Body content.`
+
+  const result = parseFrontmatter(content)
+
+  t.deepEqual(result.data, {
+    title: 'Test Topic',
+    description: 'A description'
+  })
+  t.is(result.content, '# Heading\n\nBody content.')
+})
+
+test('parseFrontmatter() returns empty data when no frontmatter', (t) => {
+  const content = '# Just Content'
+
+  const result = parseFrontmatter(content)
+
+  t.deepEqual(result.data, {})
+  t.is(result.content, '# Just Content')
+})

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