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

package/bin/cli.js

@@ -20,7 +20,20 @@ process.removeAllListeners('warning')
 process.env.QUIRE_LOG_LEVEL = config.get('logLevel') || 'info'
 
 /**
- * Dynamic import ensures env var is set before logger modules are loaded
+ * Set NO_COLOR env var from config before importing CLI modules
+ *
+ * Chalk 5.x and ora read NO_COLOR at module load time.
+ * Setting it here ensures color is disabled before any styled imports.
+ * If NO_COLOR is already set in the shell environment, we do not override it.
+ *
+ * @see https://no-color.org/
+ */
+if (process.env.NO_COLOR === undefined && config.get('logUseColor') === false) {
+  process.env.NO_COLOR = '1'
+}
+
+/**
+ * Dynamic import ensures env vars are set before logger modules are loaded
  */
 const { default: cli } = await import('#src/main.js')
 

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.40",
   "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/config.js

@@ -205,7 +205,7 @@ Examples:
     const output = formatSettings(this.config.store, {
       showInternal: options.debug,
       configPath: this.config.path,
-      useColor: this.config.get('logUseColor'),
+      useColor: this.config.get('logUseColor') && !process.env.NO_COLOR,
     })
     this.logger.info(output)
   }

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/commander/index.js

@@ -10,6 +10,8 @@ import { Argument, Option } from 'commander'
 
 // Re-export shared option definitions
 export {
+  colorOption,
+  noColorOption,
   quietOption,
   verboseOption,
   debugOption,

package/src/lib/commander/options.js

@@ -124,6 +124,30 @@ export const debugOption = [
   { conflicts: ['quiet'] }
 ]
 
+/**
+ * Color options - enable/disable colored output
+ *
+ * Commander.js requires separate option definitions for --color and --no-color
+ * to support both the positive and negative forms. When --color has no default,
+ * the three-state semantics are:
+ *
+ * - `--color` → options.color = true (force color on)
+ * - `--no-color` → options.color = false (force color off)
+ * - (no flag) → options.color = undefined (falls back to env/config)
+ *
+ * Respects the NO_COLOR environment variable (https://no-color.org/).
+ * Respects config default: `quire settings set logUseColor false`
+ *
+ * @type {Array[]}
+ */
+export const colorOption = [
+  '--color', 'force colored output (overrides NO_COLOR env var)',
+]
+
+export const noColorOption = [
+  '--no-color', 'disable colored output',
+]
+
 /**
  * Standard output mode options (quiet, verbose, debug, progress)
  *

package/src/lib/commander/options.test.js

@@ -1,7 +1,7 @@
 import test from 'ava'
 import { Command } from 'commander'
 import { arrayToOption } from './index.js'
-import { quietOption, verboseOption, debugOption } from './options.js'
+import { colorOption, noColorOption, quietOption, verboseOption, debugOption } from './options.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Integration tests for option conflicts
@@ -16,6 +16,8 @@ import { quietOption, verboseOption, debugOption } from './options.js'
 function createTestProgram() {
   const program = new Command()
   program
+    .addOption(arrayToOption(colorOption))
+    .addOption(arrayToOption(noColorOption))
     .addOption(arrayToOption(quietOption))
     .addOption(arrayToOption(verboseOption))
     .addOption(arrayToOption(debugOption))
@@ -107,3 +109,46 @@ test('options order does not affect conflict detection', (t) => {
   t.throws(() => program1.parse(['node', 'test', '--quiet', '--verbose']))
   t.throws(() => program2.parse(['node', 'test', '--verbose', '--quiet']))
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Color option tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('--no-color sets color to false', (t) => {
+  const program = createTestProgram()
+  program.parse(['node', 'test', '--no-color'])
+  t.is(program.opts().color, false)
+})
+
+test('--color sets color to true', (t) => {
+  const program = createTestProgram()
+  program.parse(['node', 'test', '--color'])
+  t.is(program.opts().color, true)
+})
+
+test('no color flag leaves color undefined', (t) => {
+  const program = createTestProgram()
+  program.parse(['node', 'test'])
+  t.is(program.opts().color, undefined)
+})
+
+test('--no-color can be combined with --verbose', (t) => {
+  const program = createTestProgram()
+  t.notThrows(() => {
+    program.parse(['node', 'test', '--no-color', '--verbose'])
+  })
+})
+
+test('--no-color can be combined with --quiet', (t) => {
+  const program = createTestProgram()
+  t.notThrows(() => {
+    program.parse(['node', 'test', '--no-color', '--quiet'])
+  })
+})
+
+test('--no-color can be combined with --debug', (t) => {
+  const program = createTestProgram()
+  t.notThrows(() => {
+    program.parse(['node', 'test', '--no-color', '--debug'])
+  })
+})

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