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

package/src/commands/validate.js

@@ -25,11 +25,14 @@ export default class ValidateCommand extends Command {
 Examples:
   quire validate               Check YAML syntax in content/_data/
   quire validate --verbose     Validate with detailed file listing
+  quire validate --json        Output validation results as JSON
 
 Validates YAML files in content/_data/ directory.
 `,
     version: '1.0.0',
-    options: [],
+    options: [
+      ['--json', 'output validation results as JSON'],
+    ],
   })
 
   constructor() {
@@ -45,21 +48,50 @@ Validates YAML files in content/_data/ directory.
       .map(file => path.join(dataPath, file)
       )
 
-    let errorList = []
-    this.logger.info('Validating YAML files..')
+    const results = []
+    if (!options.json) {
+      this.logger.info('Validating YAML files..')
+    }
 
     for (const file of files) {
       try {
         yamlValidation(file)
+        results.push({ file, status: 'passed' })
       } catch (error){
-        errorList.push(error)
+        results.push({ file, status: 'failed', error: error.reason })
+      }
+    }
+
+    const errors = results.filter((r) => r.status === 'failed')
+
+    if (options.json) {
+      const output = {
+        summary: {
+          files: results.length,
+          passed: results.length - errors.length,
+          failed: errors.length,
+        },
+        files: results,
+      }
+      console.log(JSON.stringify(output, null, 2))
+
+      // Still throw so exit code reflects failure
+      if (errors.length > 0) {
+        throw new ValidationError(
+          `Validation failed with ${errors.length} error(s)`,
+          {
+            code: 'VALIDATION_FAILED',
+            suggestion: 'Fix the errors listed above and run validation again'
+          }
+        )
       }
+      return
     }
 
-    if(errorList.length > 0) {
-      errorList.forEach(err => { this.logger.error(`${err.reason}`) })
+    if (errors.length > 0) {
+      errors.forEach((r) => { this.logger.error(`${r.error}`) })
       throw new ValidationError(
-        `Validation failed with ${errorList.length} error(s)`,
+        `Validation failed with ${errors.length} error(s)`,
         {
           code: 'VALIDATION_FAILED',
           suggestion: 'Fix the errors listed above and run validation again'

package/src/commands/validate.spec.js

@@ -40,21 +40,28 @@ test('registered command has correct options', (t) => {
   const { command } = t.context
 
   // Get all options
+  const jsonOption = command.options.find((opt) => opt.long === '--json')
   const quietOption = command.options.find((opt) => opt.long === '--quiet')
   const verboseOption = command.options.find((opt) => opt.long === '--verbose')
   const debugOption = command.options.find((opt) => opt.long === '--debug')
 
   // Verify all options exist
+  t.truthy(jsonOption, '--json option should exist')
   t.truthy(quietOption, '--quiet option should exist')
   t.truthy(verboseOption, '--verbose option should exist')
   t.truthy(debugOption, '--debug option should exist')
 
   // Verify they are Option instances
+  t.true(jsonOption instanceof Option, '--json should be Option instance')
   t.true(quietOption instanceof Option, '--quiet should be Option instance')
   t.true(verboseOption instanceof Option, '--verbose should be Option instance')
   t.true(debugOption instanceof Option, '--debug should be Option instance')
 
   // Verify option properties
+  t.is(jsonOption.long, '--json')
+  t.truthy(jsonOption.description)
+  t.false(jsonOption.required, '--json should not require a value')
+
   t.is(quietOption.long, '--quiet')
   t.is(quietOption.short, '-q')
   t.truthy(quietOption.description)
@@ -76,6 +83,7 @@ test('command options are accessible via public API', (t) => {
   // Test that options can be accessed the way Commander.js does
   const optionNames = command.options.map((opt) => opt.long)
 
+  t.true(optionNames.includes('--json'))
   t.true(optionNames.includes('--quiet'))
   t.true(optionNames.includes('--verbose'))
   t.true(optionNames.includes('--debug'))

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