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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.38",
+  "version": "1.0.0-rc.39",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -70,6 +70,8 @@
     "inquirer": "^9.1.4",
     "js-yaml": "^4.1.0",
     "loglevel": "^1.8.1",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
     "node-fetch": "^3.3.2",
     "open": "^8.4.0",
     "ora": "^6.1.2",

package/src/commands/help.js

@@ -0,0 +1,60 @@
+import Command from '#src/Command.js'
+import { outputWithPaging } from '#helpers/pager.js'
+import { getTopicContent, getTopicList } from '#lib/help/index.js'
+
+/**
+ * Quire CLI `help` Command
+ *
+ * Display help for a specific topic or list available topics.
+ * Complements Commander's built-in help with extended documentation.
+ *
+ * @example
+ * quire help                 # List available topics
+ * quire help workflows       # Show workflows topic
+ * quire help --list          # List available topics
+ *
+ * @class      HelpCommand
+ * @extends    {Command}
+ */
+export default class HelpCommand extends Command {
+  static definition = {
+    name: 'help',
+    aliases: ['h'],
+    description: 'Display help for a topic or list available topics',
+    summary: 'show help for a topic',
+    docsLink: 'quire-commands/',
+    helpText: `
+Examples:
+  quire help                 List available help topics
+  quire help workflows       Show common workflow examples
+  quire help pdf             Show PDF generation guide
+  quire help --list          List all available topics
+`,
+    version: '1.0.0',
+    args: [
+      ['[topic]', 'help topic to display']
+    ],
+    options: [
+      ['--list', 'list all available topics'],
+    ],
+  }
+
+  constructor() {
+    super(HelpCommand.definition)
+  }
+
+  async action(topic, options, command) {
+    this.debug('called with topic=%s options=%O', topic, options)
+
+    // List topics if no topic specified or --list flag
+    if (!topic || options.list) {
+      const list = await getTopicList()
+      process.stdout.write(list + '\n')
+      return
+    }
+
+    // Display requested topic with paging (throws HelpTopicNotFoundError if missing)
+    const content = await getTopicContent(topic)
+    await outputWithPaging(content)
+  }
+}

package/src/commands/help.test.js

@@ -0,0 +1,132 @@
+import esmock from 'esmock'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Help Command Integration Tests
+ *
+ * Tests the help command behavior with mocked dependencies.
+ */
+
+test.serial('help command outputs topic list when called without arguments', async (t) => {
+  const sandbox = sinon.createSandbox()
+  const stdoutWrite = sandbox.stub(process.stdout, 'write')
+
+  try {
+    const mockList = 'Available help topics:\n  debugging  Troubleshooting help'
+
+    const HelpCommand = await esmock('./help.js', {
+      '#lib/help/index.js': {
+        getTopicList: sandbox.stub().resolves(mockList),
+        getTopicContent: sandbox.stub()
+      },
+      '#helpers/pager.js': {
+        outputWithPaging: sandbox.stub()
+      }
+    })
+
+    const command = new HelpCommand.default()
+    await command.action(undefined, {}, {})
+
+    t.true(stdoutWrite.calledOnce)
+    t.true(stdoutWrite.calledWith(mockList + '\n'))
+  } finally {
+    sandbox.restore()
+  }
+})
+
+test.serial('help command outputs topic list when --list flag is provided', async (t) => {
+  const sandbox = sinon.createSandbox()
+  const stdoutWrite = sandbox.stub(process.stdout, 'write')
+
+  try {
+    const mockList = 'Available help topics:\n  pdf  PDF generation'
+
+    const HelpCommand = await esmock('./help.js', {
+      '#lib/help/index.js': {
+        getTopicList: sandbox.stub().resolves(mockList),
+        getTopicContent: sandbox.stub()
+      },
+      '#helpers/pager.js': {
+        outputWithPaging: sandbox.stub()
+      }
+    })
+
+    const command = new HelpCommand.default()
+    await command.action('ignored', { list: true }, {})
+
+    t.true(stdoutWrite.calledOnce)
+    t.true(stdoutWrite.calledWith(mockList + '\n'))
+  } finally {
+    sandbox.restore()
+  }
+})
+
+test('help command outputs topic content with paging when topic is specified', async (t) => {
+  const sandbox = sinon.createSandbox()
+
+  try {
+    const mockRendered = 'Rendered workflows content'
+    const mockOutputWithPaging = sandbox.stub().resolves()
+
+    const HelpCommand = await esmock('./help.js', {
+      '#lib/help/index.js': {
+        getTopicList: sandbox.stub(),
+        getTopicContent: sandbox.stub().resolves(mockRendered)
+      },
+      '#helpers/pager.js': {
+        outputWithPaging: mockOutputWithPaging
+      }
+    })
+
+    const command = new HelpCommand.default()
+    await command.action('workflows', {}, {})
+
+    t.true(mockOutputWithPaging.calledOnce)
+    t.true(mockOutputWithPaging.calledWith(mockRendered))
+  } finally {
+    sandbox.restore()
+  }
+})
+
+test('help command propagates HelpTopicNotFoundError from getTopicContent', async (t) => {
+  const sandbox = sinon.createSandbox()
+
+  try {
+    const { default: HelpTopicNotFoundError } = await import('#src/errors/help/help-topic-not-found-error.js')
+
+    const HelpCommand = await esmock('./help.js', {
+      '#lib/help/index.js': {
+        getTopicList: sandbox.stub(),
+        getTopicContent: sandbox.stub().rejects(new HelpTopicNotFoundError('nonexistent'))
+      },
+      '#helpers/pager.js': {
+        outputWithPaging: sandbox.stub()
+      }
+    })
+
+    const command = new HelpCommand.default()
+
+    const error = await t.throwsAsync(
+      () => command.action('nonexistent', {}, {}),
+      { name: 'HelpTopicNotFoundError' }
+    )
+
+    t.is(error.code, 'HELP_TOPIC_NOT_FOUND')
+    t.is(error.exitCode, 2)
+    t.is(error.topic, 'nonexistent')
+  } finally {
+    sandbox.restore()
+  }
+})
+
+test('help command has correct definition', async (t) => {
+  const HelpCommand = await import('./help.js')
+  const command = new HelpCommand.default()
+
+  t.is(command.name, 'help')
+  t.deepEqual(command.aliases, ['h'])
+  t.truthy(command.description)
+  t.truthy(command.args)
+  t.truthy(command.options)
+})

package/src/errors/help/help-topic-not-found-error.js

@@ -0,0 +1,22 @@
+import InvalidInputError from '../input/invalid-input-error.js'
+import QuireError from '../quire-error.js'
+
+/**
+ * Error thrown when a requested help topic does not exist
+ */
+export default class HelpTopicNotFoundError extends InvalidInputError {
+  constructor(topic) {
+    super(
+      `Unknown help topic: ${topic}`,
+      {
+        code: 'HELP_TOPIC_NOT_FOUND',
+        exitCode: 2,
+        inputValue: topic,
+        inputName: 'topic',
+        suggestion: 'Run "quire help --list" to see available topics',
+        docsUrl: `${QuireError.DOCS_BASE}/quire-commands/`
+      }
+    )
+    this.topic = topic
+  }
+}

package/src/errors/help/index.js

@@ -0,0 +1,8 @@
+/**
+ * Help errors (exit code: 2)
+ *
+ * Errors related to the help system and topic lookup.
+ *
+ * @module errors/help
+ */
+export { default as HelpTopicNotFoundError } from './help-topic-not-found-error.js'

package/src/errors/index.js

@@ -46,3 +46,9 @@ export {
 
 // Validation errors (exit code: 4)
 export { default as ValidationError } from './validation/validation-error.js'
+
+// Input errors (exit code: 2)
+export { InvalidInputError } from './input/index.js'
+
+// Help errors (exit code: 2)
+export { HelpTopicNotFoundError } from './help/index.js'

package/src/errors/input/index.js

@@ -0,0 +1,8 @@
+/**
+ * Input errors (exit code: 2)
+ *
+ * Errors related to invalid user input (arguments, options, values).
+ *
+ * @module errors/input
+ */
+export { default as InvalidInputError } from './invalid-input-error.js'

package/src/errors/input/invalid-input-error.js

@@ -0,0 +1,21 @@
+import QuireError from '../quire-error.js'
+
+/**
+ * Error thrown when user input is invalid
+ *
+ * Generic error for invalid arguments, options, or other user-provided values.
+ * Can be extended for specific input validation scenarios.
+ */
+export default class InvalidInputError extends QuireError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code || 'INVALID_INPUT',
+      exitCode: options.exitCode ?? 2,
+      suggestion: options.suggestion,
+      docsUrl: options.docsUrl,
+      ...options
+    })
+    this.inputValue = options.inputValue
+    this.inputName = options.inputName
+  }
+}

package/src/helpers/pager.js

@@ -0,0 +1,59 @@
+/**
+ * Terminal pager utility
+ *
+ * Provides paged output for long content in interactive terminals.
+ * Paging can be disabled with:
+ * - `--no-pager` CLI flag (sets NO_PAGER env var)
+ * - `NO_PAGER=1` environment variable
+ * - `PAGER=cat` traditional Unix convention (content passes through without paging)
+ *
+ * @module helpers/pager
+ */
+import { spawn } from 'node:child_process'
+
+/**
+ * Output content with optional paging for long content
+ *
+ * Uses system pager (less/more) when:
+ * - Output is to an interactive terminal (TTY)
+ * - Content exceeds terminal height
+ * - Paging is not disabled via NO_PAGER env var
+ *
+ * The PAGER env var selects the pager program (default: less on Unix, more on
+ * Windows). Setting PAGER=cat effectively disables paging as a traditional
+ * Unix convention.
+ *
+ * @param {string} content - Content to output
+ * @returns {Promise<void>}
+ */
+export async function outputWithPaging(content) {
+  const noPager = process.env.NO_PAGER
+  const lines = content.split('\n').length
+  const isTTY = process.stdout.isTTY
+  const terminalRows = process.stdout.rows || 24
+
+  // Use pager if content exceeds terminal height and we're in a TTY
+  if (!noPager && isTTY && lines > terminalRows) {
+    const pager = process.env.PAGER || (process.platform === 'win32' ? 'more' : 'less')
+    const pagerArgs = pager === 'less' ? ['-R'] : [] // -R preserves ANSI colors
+
+    return new Promise((resolve) => {
+      const child = spawn(pager, pagerArgs, {
+        stdio: ['pipe', 'inherit', 'inherit']
+      })
+
+      child.stdin.write(content + '\n')
+      child.stdin.end()
+
+      child.on('close', resolve)
+      child.on('error', () => {
+        // Fallback to direct output if pager fails
+        process.stdout.write(content + '\n')
+        resolve()
+      })
+    })
+  }
+
+  // Direct output for non-TTY or short content
+  process.stdout.write(content + '\n')
+}

package/src/helpers/pager.test.js

@@ -0,0 +1,85 @@
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Pager Helper Tests
+ */
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test.serial('outputWithPaging() writes directly when not a TTY', async (t) => {
+  const { sandbox } = t.context
+  const originalIsTTY = process.stdout.isTTY
+  const stdoutWrite = sandbox.stub(process.stdout, 'write')
+
+  try {
+    // Simulate non-TTY (piped output)
+    Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true })
+
+    const { outputWithPaging } = await import('./pager.js')
+    await outputWithPaging('Short content')
+
+    t.true(stdoutWrite.calledWith('Short content\n'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+  }
+})
+
+test.serial('outputWithPaging() writes directly when content is short', async (t) => {
+  const { sandbox } = t.context
+  const originalIsTTY = process.stdout.isTTY
+  const originalRows = process.stdout.rows
+  const stdoutWrite = sandbox.stub(process.stdout, 'write')
+
+  try {
+    // Simulate TTY with 24 rows
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    Object.defineProperty(process.stdout, 'rows', { value: 24, configurable: true })
+
+    const { outputWithPaging } = await import('./pager.js')
+    await outputWithPaging('Line 1\nLine 2\nLine 3')
+
+    t.true(stdoutWrite.calledWith('Line 1\nLine 2\nLine 3\n'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    Object.defineProperty(process.stdout, 'rows', { value: originalRows, configurable: true })
+  }
+})
+
+test.serial('outputWithPaging() writes directly when NO_PAGER is set', async (t) => {
+  const { sandbox } = t.context
+  const originalIsTTY = process.stdout.isTTY
+  const originalRows = process.stdout.rows
+  const originalNoPager = process.env.NO_PAGER
+  const stdoutWrite = sandbox.stub(process.stdout, 'write')
+
+  try {
+    // Simulate TTY with small terminal (would normally trigger pager)
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true })
+    Object.defineProperty(process.stdout, 'rows', { value: 5, configurable: true })
+    process.env.NO_PAGER = '1'
+
+    const { outputWithPaging } = await import('./pager.js')
+
+    // Content longer than terminal height
+    const longContent = Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`).join('\n')
+    await outputWithPaging(longContent)
+
+    // Should write directly despite long content, because pager is disabled
+    t.true(stdoutWrite.calledWith(longContent + '\n'))
+  } finally {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true })
+    Object.defineProperty(process.stdout, 'rows', { value: originalRows, configurable: true })
+    if (originalNoPager === undefined) {
+      delete process.env.NO_PAGER
+    } else {
+      process.env.NO_PAGER = originalNoPager
+    }
+  }
+})

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')
+})