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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.36",
+  "version": "1.0.0-rc.38",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -78,7 +78,8 @@
     "read-package-up": "^11.0.0",
     "semver": "^7.3.8",
     "update-notifier": "^7.3.1",
-    "which": "^2.0.2"
+    "which": "^2.0.2",
+    "wrap-ansi": "^8.1.0"
   },
   "devDependencies": {
     "ava": "^6.2.0",

package/src/commands/build.js

@@ -4,6 +4,7 @@ import { withOutputModes } from '#lib/commander/index.js'
 import { api, cli } from '#lib/11ty/index.js'
 import paths from '#lib/project/index.js'
 import { clean } from '#helpers/clean.js'
+import { recordStatus } from '#lib/conf/build-status.js'
 import reporter from '#lib/reporter/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
@@ -49,8 +50,6 @@ Note: Run before "quire pdf" or "quire epub" commands.
     // Configure reporter for this command
     reporter.configure({ quiet: options.quiet, verbose: options.verbose })
 
-    reporter.start('Building site...', { showElapsed: true })
-
     try {
       if (options['11ty'] === 'api') {
         this.debug('running eleventy using lib/11ty api')
@@ -59,9 +58,9 @@ Note: Run before "quire pdf" or "quire epub" commands.
         this.debug('running eleventy using lib/11ty cli')
         await cli.build(options)
       }
-      reporter.succeed('Build complete')
+      recordStatus(paths.getProjectRoot(), 'build', 'ok')
     } catch (error) {
-      reporter.fail('Build failed')
+      recordStatus(paths.getProjectRoot(), 'build', 'failed')
       throw error
     }
   }

package/src/commands/build.test.js

@@ -108,8 +108,6 @@ test('build command should call eleventy CLI with default options', async (t) =>
   t.true(mockClean.called, 'clean should be called in preAction')
   t.false(mockEleventyApi.build.called, 'eleventy API build should not be called')
   t.true(mockEleventyCli.build.called, 'eleventy CLI build should be called')
-  t.true(mockReporter.start.called, 'reporter.start should be called')
-  t.true(mockReporter.succeed.called, 'reporter.succeed should be called')
 })
 
 test('build command should call eleventy API when 11ty option is "api"', async (t) => {
@@ -282,7 +280,7 @@ test('build command should pass options to eleventy build', async (t) => {
   t.true(mockEleventyCli.build.calledWith(options), 'eleventy CLI build should be called with options')
 })
 
-test('build command should call reporter.fail when build fails', async (t) => {
+test('build command should propagate errors from eleventy build', async (t) => {
   const { sandbox, fs, mockLogger, mockReporter } = t.context
 
   const buildError = new Error('Build failed')
@@ -334,11 +332,8 @@ test('build command should call reporter.fail when build fails', async (t) => {
   command.name = sandbox.stub().returns('build')
 
   // Run action and expect it to throw
+  // Nota bene: reporter.start/succeed/fail are called by the lib layer, not the command
   await t.throwsAsync(() => command.action({ '11ty': 'api' }, command), { message: 'Build failed' })
-
-  t.true(mockReporter.start.called, 'reporter.start should be called')
-  t.true(mockReporter.fail.called, 'reporter.fail should be called on error')
-  t.false(mockReporter.succeed.called, 'reporter.succeed should not be called on error')
 })
 
 test('build command should configure reporter with quiet option', async (t) => {

package/src/commands/clean.js

@@ -1,6 +1,7 @@
 import Command from '#src/Command.js'
 import { withOutputModes } from '#lib/commander/index.js'
 import { clean } from '#helpers/clean.js'
+import { clearStatus } from '#lib/conf/build-status.js'
 import paths from '#lib/project/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
@@ -31,6 +32,7 @@ Examples:
     options: [
       [ '-d, --dry-run', 'show paths to be cleaned without deleting files' ],
       [ '--dryrun', 'alias for --dry-run', { hidden: true, implies: { dryRun: true } } ],
+      [ '--status', 'also clear stored build status for this project' ],
     ],
   })
 
@@ -41,10 +43,16 @@ Examples:
   async action(options, command) {
     this.debug('called with options %O', options)
 
-    const deletedPaths = await clean(paths.getProjectRoot(), paths.toObject(), options)
+    const projectRoot = paths.getProjectRoot()
+    const deletedPaths = await clean(projectRoot, paths.toObject(), options)
+
+    if (options.status && !options.dryRun) {
+      clearStatus(projectRoot)
+      this.logger.info('Cleared build status for this project')
+    }
 
     if (!deletedPaths || !deletedPaths.length) {
-      this.logger.info('No files to delete')
+      if (!options.status) this.logger.info('No files to delete')
       return
     }
 

package/src/commands/clean.spec.js

@@ -42,6 +42,7 @@ test('registered command has correct options', (t) => {
   // Get all options
   const dryRunOption = command.options.find((opt) => opt.long === '--dry-run')
   const dryrunAlias = command.options.find((opt) => opt.long === '--dryrun')
+  const statusOption = command.options.find((opt) => opt.long === '--status')
   const progressOption = command.options.find((opt) => opt.long === '--progress')
   const quietOption = command.options.find((opt) => opt.long === '--quiet')
   const verboseOption = command.options.find((opt) => opt.long === '--verbose')
@@ -50,6 +51,7 @@ test('registered command has correct options', (t) => {
   // Verify all options exist
   t.truthy(dryRunOption, '--dry-run option should exist')
   t.truthy(dryrunAlias, '--dryrun alias should exist')
+  t.truthy(statusOption, '--status option should exist')
   t.truthy(progressOption, '--progress option should exist')
   t.truthy(quietOption, '--quiet option should exist')
   t.truthy(verboseOption, '--verbose option should exist')
@@ -58,6 +60,7 @@ test('registered command has correct options', (t) => {
   // Verify they are Option instances
   t.true(dryRunOption instanceof Option, '--dry-run should be Option instance')
   t.true(dryrunAlias instanceof Option, '--dryrun should be Option instance')
+  t.true(statusOption instanceof Option, '--status should be Option instance')
   t.true(progressOption instanceof Option, '--progress should be Option instance')
   t.true(quietOption instanceof Option, '--quiet should be Option instance')
   t.true(verboseOption instanceof Option, '--verbose should be Option instance')
@@ -73,6 +76,12 @@ test('registered command has correct options', (t) => {
   t.is(dryrunAlias.long, '--dryrun')
   t.true(dryrunAlias.hidden, '--dryrun should be hidden from help')
 
+  // --status clears stored build status
+  t.is(statusOption.long, '--status')
+  t.falsy(statusOption.short, '--status should not have a short flag')
+  t.truthy(statusOption.description)
+  t.false(statusOption.required, '--status should not require a value')
+
   // --progress is a hidden alias for --verbose
   t.is(progressOption.long, '--progress')
   t.truthy(progressOption.description)
@@ -101,6 +110,7 @@ test('command options are accessible via public API', (t) => {
 
   t.true(optionNames.includes('--dry-run'))
   t.true(optionNames.includes('--dryrun'))
+  t.true(optionNames.includes('--status'))
   t.true(optionNames.includes('--progress'))
   t.true(optionNames.includes('--quiet'))
   t.true(optionNames.includes('--verbose'))

package/src/commands/clean.test.js

@@ -258,3 +258,125 @@ test('clean command should pass all options to clean helper', async (t) => {
 
   t.true(mockClean.calledWith('/project', { output: '_site' }, options), 'clean should receive all options')
 })
+
+test('clean --status calls clearStatus for the project', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  const mockClean = sandbox.stub().resolves(['/project/_site'])
+  const mockTestcwd = sandbox.stub()
+  const mockClearStatus = sandbox.stub()
+
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#lib/conf/build-status.js': {
+      clearStatus: mockClearStatus
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new CleanCommand()
+  command.name = sandbox.stub().returns('clean')
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  await command.action({ status: true }, command)
+
+  t.true(mockClearStatus.calledOnce, 'clearStatus should be called once')
+  t.true(mockClearStatus.calledWith('/project'), 'clearStatus should be called with project root')
+
+  const calls = mockLogger.info.args.map((a) => a[0])
+  t.true(calls.some((c) => c.includes('Cleared build status')), 'should log status cleared message')
+})
+
+test('clean --status does not call clearStatus during dry-run', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  const mockClean = sandbox.stub().resolves(['/project/_site'])
+  const mockTestcwd = sandbox.stub()
+  const mockClearStatus = sandbox.stub()
+
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#lib/conf/build-status.js': {
+      clearStatus: mockClearStatus
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new CleanCommand()
+  command.name = sandbox.stub().returns('clean')
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  await command.action({ status: true, dryRun: true }, command)
+
+  t.false(mockClearStatus.called, 'clearStatus should not be called during dry-run')
+})
+
+test('clean --status with no files still clears status', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  const mockClean = sandbox.stub().resolves([])
+  const mockTestcwd = sandbox.stub()
+  const mockClearStatus = sandbox.stub()
+
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#lib/conf/build-status.js': {
+      clearStatus: mockClearStatus
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    'fs-extra': fs
+  })
+
+  const command = new CleanCommand()
+  command.name = sandbox.stub().returns('clean')
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  await command.action({ status: true }, command)
+
+  t.true(mockClearStatus.calledOnce, 'clearStatus should be called even when no files deleted')
+  t.true(mockClearStatus.calledWith('/project'), 'clearStatus should be called with project root')
+})

package/src/commands/config.js

@@ -194,7 +194,9 @@ Examples:
       const store = options.debug
         ? this.config.store
         : Object.fromEntries(
-          Object.entries(this.config.store).filter(([k]) => !k.startsWith('__internal__'))
+          Object.entries(this.config.store).filter(([k]) =>
+            !k.startsWith('__internal__') && k !== 'projects'
+          )
         )
       console.log(JSON.stringify(store, null, 2))
       return

package/src/commands/config.test.js

@@ -28,7 +28,8 @@ test.beforeEach((t) => {
       logShowLevel: false,
       projectTemplate: 'https://github.com/thegetty/quire-starter-default',
       quireVersion: '1.0.0',
-      __internal__secretKey: 'hidden-value'
+      __internal__secretKey: 'hidden-value',
+      projects: { abc123: { projectPath: '/test', buildStatus: { build: { status: 'ok', timestamp: 1000 } } } }
     },
     get: (key) => t.context.mockConfig.store[key],
     set: t.context.sandbox.stub(),
@@ -115,6 +116,46 @@ test('conf command should show internal config values with debug flag', async (t
   t.true(output.includes('__internal__secretKey: "hidden-value"'))
 })
 
+test('conf command should hide projects by default', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  await command.action(undefined, undefined, undefined, {})
+
+  const output = mockLogger.info.firstCall.args[0]
+  t.false(output.includes('projects'))
+})
+
+test('conf command should show projects with debug flag', async (t) => {
+  const { sandbox, mockLogger, mockConfig } = t.context
+
+  const { default: ConfCommand } = await esmock('./config.js', {}, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new ConfCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  await command.action(undefined, undefined, undefined, { debug: true })
+
+  const output = mockLogger.info.firstCall.args[0]
+  t.true(output.includes('projects'))
+})
+
 // =============================================================================
 // Get operation
 // =============================================================================

package/src/commands/doctor.js

@@ -0,0 +1,251 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import Command from '#src/Command.js'
+import { withOutputModes } from '#lib/commander/index.js'
+import { clearStatus } from '#lib/conf/build-status.js'
+import { runAllChecksWithSections, checkSections, SECTION_NAMES, CHECK_IDS } from '#lib/doctor/index.js'
+import { formatHuman } from '#lib/doctor/formatters/human.js'
+import { formatJson } from '#lib/doctor/formatters/json.js'
+
+/**
+ * Map section name to its check IDs
+ */
+const SECTION_CHECK_MAP = Object.fromEntries(
+  checkSections.map((s) => [s.name.toLowerCase(), s.checks.map((c) => c.id)])
+)
+
+/**
+ * Quire CLI `doctor` Command
+ *
+ * Diagnose common issues with the Quire environment and project setup.
+ *
+ * @class      DoctorCommand
+ * @extends    {Command}
+ */
+export default class DoctorCommand extends Command {
+  static definition = withOutputModes({
+    name: 'doctor',
+    aliases: ['checkup', 'check', 'diagnostic', 'health'],
+    description: 'Diagnose common issues with your Quire setup',
+    summary: 'check environment and project health',
+    docsLink: 'quire-commands/#troubleshooting',
+    helpText: `
+Runs diagnostic checks organized into four sections:
+  • Environment: os, cli, node, runtime, npm, git
+  • Tools: prince, pandoc
+  • Project: project, deps, 11ty, data
+  • Outputs: build, pdf, epub
+
+Examples:
+  quire doctor                          Run all diagnostic checks
+  quire doctor all                      Run all checks (same as no argument)
+  quire doctor environment              Check environment section only
+  quire doctor node                     Check Node.js version only
+  quire doctor node git                 Check multiple items
+  quire doctor --errors                 Show only failed checks
+  quire doctor --warnings               Show only warnings
+  quire doctor --verbose                Show additional details (paths, versions)
+  quire doctor --json                   Output results as JSON (to stdout)
+  quire doctor --json report.json       Save JSON results to file
+  quire doctor --reset                  Clear stored build status
+  quire checkup                         Alias for doctor command
+
+CI/Scripting:
+  quire doctor --quiet                  Exit code only (0=success, 1=failure)
+  quire doctor --quiet --json out.json  Save JSON report silently
+`,
+    version: '1.0.0',
+    args: [
+      [
+        '[checks...]',
+        `run specific check(s): all, ${SECTION_NAMES.join(', ')}, or ${CHECK_IDS.join(', ')}`,
+      ],
+    ],
+    options: [
+      ['-e, --errors', 'show only failed checks'],
+      ['-w, --warnings', 'show only warnings'],
+      ['--json [file]', 'output results as JSON (to standard out or a file)'],
+      ['--reset', 'clear stored build status for the current project'],
+    ],
+  })
+
+  constructor() {
+    super(DoctorCommand.definition)
+  }
+
+  async action(checks, options, command) {
+    this.debug('called with checks=%O options=%O', checks, options)
+
+    // --reset: clear stored build status and exit without running checks
+    if (options.reset) {
+      clearStatus(process.cwd())
+      if (!options.quiet) {
+        this.logger.info('Build status cleared for this project')
+      }
+      return
+    }
+
+    // Parse variadic checks argument into sections and individual checks
+    const filterOptions = { sections: null, checks: null }
+    let label = 'diagnostic checks'
+
+    if (checks.length > 0) {
+      const values = checks.map((v) => v.toLowerCase())
+
+      // "all" means no filtering
+      if (!values.includes('all')) {
+        // Separate section names from individual check IDs
+        const sectionValues = values.filter((v) => SECTION_NAMES.includes(v))
+        const checkValues = values.filter((v) => CHECK_IDS.includes(v))
+
+        // If we have section names, use them as section filter
+        if (sectionValues.length > 0 && checkValues.length === 0) {
+          filterOptions.sections = sectionValues
+          label = sectionValues.length === 1
+            ? `${sectionValues[0]} checks`
+            : `${sectionValues.join(', ')} checks`
+        } else if (checkValues.length > 0) {
+          // If we have individual checks (with or without sections),
+          // expand sections to their check IDs and combine
+          const expandedChecks = new Set(checkValues)
+          for (const section of sectionValues) {
+            const sectionCheckIds = SECTION_CHECK_MAP[section] || []
+            sectionCheckIds.forEach((id) => expandedChecks.add(id))
+          }
+          filterOptions.checks = [...expandedChecks]
+          label = filterOptions.checks.length === 1
+            ? `${filterOptions.checks[0]} check`
+            : `${filterOptions.checks.join(', ')} checks`
+        }
+      }
+    }
+
+    const sections = await runAllChecksWithSections(filterOptions)
+
+    // JSON output mode (options.json is true for flag-only, or string for file path)
+    if (options.json) {
+      this.outputJson(sections, options)
+      return
+    }
+
+    // Quiet mode without JSON: just exit with appropriate code
+    if (options.quiet) {
+      this.outputQuiet(sections)
+      return
+    }
+
+    // Human-readable output
+    this.outputHuman(sections, options, label)
+  }
+
+  /**
+   * Quiet mode: no output, just exit code
+   * @param {Array} sections - Check results organized by section
+   */
+  outputQuiet(sections) {
+    const { exitCode } = formatJson(sections, {})
+    if (exitCode !== 0) {
+      process.exitCode = exitCode
+    }
+  }
+
+  /**
+   * Output results as JSON for programmatic consumption
+   * @param {Array} sections - Check results organized by section
+   * @param {Object} options - Command options (options.json is true or filename string)
+   */
+  outputJson(sections, options) {
+    const { json, exitCode } = formatJson(sections, {
+      errors: options.errors,
+      warnings: options.warnings,
+      verbose: options.verbose,
+    })
+
+    // Write to file (if string path provided) or stdout (if just --json flag)
+    if (typeof options.json === 'string') {
+      const outputPath = path.resolve(options.json)
+      fs.writeFileSync(outputPath, json + '\n')
+      if (!options.quiet) {
+        this.logger.info(`Results written to ${outputPath}`)
+      }
+    } else if (!options.quiet) {
+      // Write to stdout (bypassing logger formatting) unless quiet mode
+      console.log(json)
+    }
+
+    // Set exit code if any checks failed
+    if (exitCode !== 0) {
+      process.exitCode = exitCode
+    }
+  }
+
+  /**
+   * Map log level to console method for direct output
+   *
+   * Nota bene: doctor output bypasses the logger to avoid the `[quire]`
+   * prefix on every line. The formatter already handles its own formatting
+   * (icons, indentation, section headers). Using console methods directly
+   * routes output to the correct output stream (stdout for info, stderr for
+   * warn/error) without logger prefix and level labels.
+   */
+  static #consoleMethods = {
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+  }
+
+  /**
+   * Output results in human-readable format
+   * @param {Array} sections - Check results organized by section
+   * @param {Object} options - Command options
+   * @param {string} label - Description of checks being run
+   */
+  outputHuman(sections, options, label) {
+    const { lines, summary, key, exitCode, isEmpty } = formatHuman(sections, {
+      errors: options.errors,
+      warnings: options.warnings,
+      verbose: options.verbose,
+      label,
+    })
+
+    // Handle case where filters excluded all results
+    if (isEmpty) {
+      for (const { text, level } of lines) {
+        this.#log(level, text)
+      }
+      return
+    }
+
+    // Output all formatted lines routed by log level
+    for (const { text, level } of lines) {
+      this.#log(level, text)
+    }
+
+    // Output summary
+    if (summary) {
+      this.#log(summary.level, summary.text)
+    }
+
+    // Output symbol key
+    if (key) {
+      this.#log('info', '')
+      this.#log(key.level, key.text)
+    }
+
+    // Set exit code if any checks failed
+    if (exitCode !== 0) {
+      process.exitCode = exitCode
+    }
+  }
+
+  /**
+   * Write a line to the console, routed by log level
+   *
+   * @param {string} level - Log level (info, warn, error)
+   * @param {string} text - Text to output
+   */
+  #log(level, text) {
+    const method = DoctorCommand.#consoleMethods[level] || console.log
+    method(text)
+  }
+}