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

package/src/commands/validate.test.js

@@ -232,3 +232,147 @@ test('validate command should pass debug option through', async (t) => {
   t.true(mockYamlValidation.called, 'validation should run')
   // Debug output should be logged (verified through console.debug stub)
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSON output tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.serial('validate --json should output valid JSON when all files pass', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+  const consoleLogStub = sandbox.stub(console, 'log')
+
+  const mockYamlValidation = sandbox.stub()
+  const mockTestcwd = sandbox.stub()
+
+  const ValidateCommand = await esmock('./validate.js', {
+    '../validators/validate-yaml.js': {
+      default: mockYamlValidation
+    },
+    '#lib/project/index.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new ValidateCommand()
+  command.name = sandbox.stub().returns('validate')
+
+  command.action({ json: true }, command)
+
+  // Should output via console.log, not logger.info
+  t.true(consoleLogStub.calledOnce, 'console.log should be called once')
+  t.false(mockLogger.info.called, 'logger.info should not be called in JSON mode')
+
+  const output = JSON.parse(consoleLogStub.firstCall.args[0])
+
+  // Verify JSON structure
+  t.truthy(output.summary, 'JSON should have summary section')
+  t.truthy(output.files, 'JSON should have files section')
+  t.is(output.summary.files, 2, 'should report 2 YAML files')
+  t.is(output.summary.passed, 2, 'both files should pass')
+  t.is(output.summary.failed, 0, 'no files should fail')
+
+  // Verify each file result
+  t.true(output.files.every((f) => f.status === 'passed'), 'all files should have passed status')
+})
+
+test.serial('validate --json should output valid JSON with errors and throw', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+  const consoleLogStub = sandbox.stub(console, 'log')
+
+  const validationError = new Error('Invalid YAML')
+  validationError.reason = 'Invalid YAML: missing required field'
+  const mockYamlValidation = sandbox.stub().throws(validationError)
+  const mockTestcwd = sandbox.stub()
+
+  const ValidateCommand = await esmock('./validate.js', {
+    '../validators/validate-yaml.js': {
+      default: mockYamlValidation
+    },
+    '#lib/project/index.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new ValidateCommand()
+  command.name = sandbox.stub().returns('validate')
+  command.logger = mockLogger
+
+  // Should still throw ValidationError for exit code
+  const error = t.throws(() => command.action({ json: true }, command), { instanceOf: ValidationError })
+  t.is(error.code, 'VALIDATION_FAILED')
+
+  // Should output JSON before throwing
+  t.true(consoleLogStub.calledOnce, 'console.log should be called once')
+
+  const output = JSON.parse(consoleLogStub.firstCall.args[0])
+
+  t.is(output.summary.files, 2)
+  t.is(output.summary.failed, 2, 'both files should fail')
+  t.is(output.summary.passed, 0)
+
+  // Verify error details in file results
+  t.true(output.files.every((f) => f.status === 'failed'), 'all files should have failed status')
+  t.true(output.files.every((f) => f.error), 'all failed files should have error details')
+
+  // logger.error should NOT be called in JSON mode
+  t.false(mockLogger.error.called, 'logger.error should not be called in JSON mode')
+})
+
+test.serial('validate --json should output mixed results', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+  const consoleLogStub = sandbox.stub(console, 'log')
+
+  // First file passes, second file fails
+  const validationError = new Error('Invalid YAML')
+  validationError.reason = 'duplicated mapping key at line 5'
+  const mockYamlValidation = sandbox.stub()
+  mockYamlValidation.onFirstCall().returns(undefined)
+  mockYamlValidation.onSecondCall().throws(validationError)
+  const mockTestcwd = sandbox.stub()
+
+  const ValidateCommand = await esmock('./validate.js', {
+    '../validators/validate-yaml.js': {
+      default: mockYamlValidation
+    },
+    '#lib/project/index.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new ValidateCommand()
+  command.name = sandbox.stub().returns('validate')
+  command.logger = mockLogger
+
+  // Should throw because there are errors
+  t.throws(() => command.action({ json: true }, command), { instanceOf: ValidationError })
+
+  const output = JSON.parse(consoleLogStub.firstCall.args[0])
+
+  t.is(output.summary.files, 2)
+  t.is(output.summary.passed, 1)
+  t.is(output.summary.failed, 1)
+  t.is(output.files[0].status, 'passed')
+  t.is(output.files[1].status, 'failed')
+  t.is(output.files[1].error, 'duplicated mapping key at line 5')
+})

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/README.md

@@ -5,28 +5,28 @@ This directory contains domain-specific modules that encapsulate the core functi
 ## Architecture Overview
 
 ```
-                            Commands Layer
-                ┌─────────────────────────────────────────┐
-                │  build  preview  new  pdf  epub  info   │
-                └──────────────────┬──────────────────────┘
-                                   │
-                ┌──────────────────┴──────────────────────┐
-                │              lib/ modules               │
-                └─────────────────────────────────────────┘
-
-     ┌─────────────────────────────────────────────────────────────────┐
-     │                        Domain Modules                           │
-     │  ┌────────────┐  ┌──────────┐  ┌────────────┐  ┌─────────────┐  │
-     │  │ project/   │  │  11ty/   │  │   pdf/     │  │   epub/     │  │
-     │  │            │  │          │  │            │  │             │  │
-     │  │ - paths    │  │ - api    │  │ - pagedjs  │  │ - epubjs    │  │
-     │  │ - config   │  │ - cli    │  │ - prince   │  │ - pandoc    │  │
-     │  │ - detect   │  │          │  │            │  │             │  │
-     │  │ - version  │  │          │  │            │  │             │  │
-     │  └────┬───────┘  └────┬─────┘  └────┬───────┘  └──────┬──────┘  │
-     └───────┼───────────────┼─────────────┼─────────────────┼─────────┘
-             │               │             │                 │
-             │      ┌────────┴─────────────┴─────────────────┘
+                                    Commands Layer
+                    ┌───────────────────────────────────────────────────┐
+                    │  build  preview  new  pdf  epub  info  doctor    │
+                    └────────────────────────┬──────────────────────────┘
+                                             │
+                    ┌────────────────────────┴──────────────────────────┐
+                    │                   lib/ modules                    │
+                    └───────────────────────────────────────────────────┘
+
+     ┌─────────────────────────────────────────────────────────────────────────┐
+     │                           Domain Modules                                │
+     │  ┌────────────┐  ┌──────────┐  ┌────────────┐  ┌──────────┐  ┌────────┐  │
+     │  │ project/   │  │  11ty/   │  │   pdf/     │  │  epub/   │  │doctor/ │  │
+     │  │            │  │          │  │            │  │          │  │        │  │
+     │  │ - paths    │  │ - api    │  │ - pagedjs  │  │ - epubjs │  │-checks │  │
+     │  │ - config   │  │ - cli    │  │ - prince   │  │ - pandoc │  │-format │  │
+     │  │ - detect   │  │          │  │            │  │          │  │        │  │
+     │  │ - version  │  │          │  │            │  │          │  │        │  │
+     │  └────┬───────┘  └────┬─────┘  └────┬───────┘  └────┬─────┘  └───┬────┘  │
+     └───────┼───────────────┼─────────────┼───────────────┼─────────────┼──────┘
+             │               │             │               │             │
+             │      ┌────────┴─────────────┴───────────────┴─────────────┘
              │      │
      ┌───────┴──────┴──────────────────────────────────────────────────┐
      │                     Installation Module                         │
@@ -65,6 +65,10 @@ These modules encapsulate specific business domains of Quire.
 |--------|-------------|
 | `paths` (default) | Singleton for path resolution |
 | `Paths` | Class for custom path instances |
+| `DATA_DIR` | Path to data files directory (`content/_data`) |
+| `PROJECT_MARKERS` | Files that identify a Quire project |
+| `REQUIRED_DATA_FILES` | Required data files (`publication.yaml`) |
+| `SOURCE_DIRECTORIES` | Directories monitored for changes |
 | `detect(dirpath)` | Check if directory is a Quire project |
 | `loadProjectConfig(projectRoot?)` | Load and validate project config |
 | `getVersion(projectPath?)` | Read `quire-11ty` version from project |
@@ -107,6 +111,57 @@ These modules encapsulate specific business domains of Quire.
 
 **Dependencies:** `project/`
 
+#### `doctor/`
+**Purpose:** Diagnostic checks for Quire environment and project health.
+
+| Export | Description |
+|--------|-------------|
+| `default` | Object with all check functions and arrays |
+| `checks` | Flat array of all diagnostic checks |
+| `checkSections` | Checks organized by section (Environment, Project) |
+| `runAllChecks()` | Run all checks, return flat results array |
+| `runAllChecksWithSections()` | Run all checks, return results by section |
+| `checkNodeVersion()` | Verify Node.js >= 22 |
+| `checkNpmAvailable()` | Verify npm in PATH |
+| `checkGitAvailable()` | Verify git in PATH |
+| `checkQuireProject()` | Detect project marker files |
+| `checkDependencies()` | Verify node_modules exists |
+| `checkDataFiles()` | Validate YAML files in content/_data/ |
+| `checkStaleBuild()` | Compare source vs build timestamps |
+
+**Sub-modules:**
+
+| File | Description |
+|------|-------------|
+| `formatDuration.js` | Human-readable time duration formatting |
+
+**Duration Formatting:**
+
+The `formatDuration` function converts milliseconds to the most appropriate time unit:
+
+| Duration       | Example Output  |
+|----------------|-----------------|
+| < 1 minute     | "45 seconds"    |
+| < 1 hour       | "30 minutes"    |
+| < 1 day        | "5 hours"       |
+| < 1 week       | "3 days"        |
+| < 1 month      | "2 weeks"       |
+| < 1 year       | "3 months"      |
+| >= 1 year      | "2 years"       |
+
+**Data Files Validation:**
+
+The `checkDataFiles` function validates YAML files in `content/_data/`:
+
+| Validation | Description |
+|------------|-------------|
+| Required files | Checks `publication.yaml` exists |
+| YAML syntax | Parses each file and reports syntax errors |
+| Schema validation | Validates against JSON schemas in `schemas/` |
+| Duplicate IDs | Detects duplicate `id` values in arrays |
+
+**Dependencies:** `project/`, `npm/`, `git/`, `validators/validate-data-files`
+
 #### `installer/`
 **Purpose:** Installation of `@thegetty/quire-11ty` into Quire projects.
 

package/src/lib/conf/README.md

@@ -93,6 +93,12 @@ quire settings get <key> --json    # Output single value as JSON
 quire settings --json --debug      # Include __internal__ keys in JSON output
 ```
 
+`staleThreshold` How stale an output must be before `quire doctor` warns; default `'HOURLY'`. Options: `'ZERO'` (0 min), `'SHORT'` (5 min), `'HOURLY'` (60 min), `'DAILY'` (12 hours), `'NEVER'` (disabled).
+
+```sh
+❯ quire config set staleThreshold DAILY
+```
+
 The `--json` flag outputs raw JSON to stdout (bypassing the logger), suitable for piping to `jq` or other tools. `__internal__` keys are excluded from JSON output unless `--debug` is also passed, consistent with the plain-text display.
 
 | Key | Type | Default | Description |

package/src/lib/conf/build-status.js

@@ -0,0 +1,103 @@
+/**
+ * Per-project build status persistence
+ *
+ * Records command outcomes (ok/failed) for build, pdf, and epub commands
+ * so that `quire doctor` can distinguish "never ran" from "ran and failed"
+ * when no output files exist on disk.
+ *
+ * Status is stored in the global CLI config under the `projects` key,
+ * keyed by a SHA-256 hash of the project's absolute path to avoid
+ * dot-notation traversal issues.
+ *
+ * @module lib/conf/build-status
+ */
+import { createHash } from 'node:crypto'
+import config from '#lib/conf/config.js'
+import createDebug from '#debug'
+
+const debug = createDebug('lib:conf:build-status')
+
+/**
+ * Commands whose status is tracked
+ * @type {readonly string[]}
+ */
+export const TRACKED_COMMANDS = Object.freeze(['build', 'pdf', 'epub'])
+
+/**
+ * Derive a fixed-length, dot-safe config key from a project path
+ *
+ * @param {string} projectPath - Absolute path to the project directory
+ * @returns {string} First 12 hex characters of the SHA-256 hash
+ */
+export function projectKey(projectPath) {
+  return createHash('sha256').update(projectPath).digest('hex').slice(0, 12)
+}
+
+/**
+ * Record the outcome of a command for a project
+ *
+ * @param {string} projectPath - Absolute path to the project directory
+ * @param {string} command - Command name ('build', 'pdf', or 'epub')
+ * @param {'ok'|'failed'} status - Outcome of the command
+ */
+export function recordStatus(projectPath, command, status) {
+  if (!TRACKED_COMMANDS.includes(command)) {
+    debug('ignoring untracked command: %s', command)
+    return
+  }
+
+  const key = projectKey(projectPath)
+  const projects = config.get('projects') || {}
+
+  const entry = projects[key] || { projectPath }
+  entry.projectPath = projectPath
+  entry.buildStatus = {
+    ...entry.buildStatus,
+    [command]: {
+      status,
+      timestamp: Date.now(),
+    },
+  }
+  projects[key] = entry
+
+  config.set('projects', projects)
+  debug('recorded %s=%s for %s (key=%s)', command, status, projectPath, key)
+}
+
+/**
+ * Retrieve the stored status for a command in a project
+ *
+ * @param {string} projectPath - Absolute path to the project directory
+ * @param {string} command - Command name ('build', 'pdf', or 'epub')
+ * @returns {{ status: 'ok'|'failed', timestamp: number } | undefined}
+ */
+export function getStatus(projectPath, command) {
+  const key = projectKey(projectPath)
+  const projects = config.get('projects') || {}
+  const entry = projects[key]
+
+  if (!entry || !entry.buildStatus) {
+    debug('no status entry for key=%s', key)
+    return undefined
+  }
+
+  return entry.buildStatus[command]
+}
+
+/**
+ * Clear all stored status for a project
+ *
+ * @param {string} projectPath - Absolute path to the project directory
+ */
+export function clearStatus(projectPath) {
+  const key = projectKey(projectPath)
+  const projects = config.get('projects') || {}
+  const entry = projects[key]
+
+  if (entry && entry.buildStatus) {
+    delete entry.buildStatus
+    projects[key] = entry
+    config.set('projects', projects)
+    debug('cleared build status for %s (key=%s)', projectPath, key)
+  }
+}