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

package/src/lib/doctor/checks/project/quire-11ty.test.js

@@ -0,0 +1,170 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkOutdatedQuire11ty returns N/A when package.json does not exist', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(false),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.true(result.ok)
+  t.is(result.level, 'na')
+  t.regex(result.message, /not installed/)
+})
+
+test('checkOutdatedQuire11ty returns N/A when package.json is not a quire-11ty project', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns(JSON.stringify({
+          name: 'some-other-package',
+          version: '1.0.0',
+        })),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.true(result.ok)
+  t.is(result.level, 'na')
+  t.regex(result.message, /not installed/)
+})
+
+test('checkOutdatedQuire11ty returns ok when version is up to date', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns(JSON.stringify({
+          name: '@thegetty/quire-11ty',
+          version: '1.0.0-rc.33',
+        })),
+      },
+    },
+    '#lib/npm/index.js': {
+      default: {
+        view: sandbox.stub().resolves('1.0.0-rc.33'),
+      },
+    },
+    '#lib/conf/config.js': {
+      default: {
+        get: sandbox.stub().returns('rc'),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.true(result.ok)
+  t.regex(result.message, /1\.0\.0-rc\.33/)
+  t.regex(result.message, /up to date/)
+})
+
+test('checkOutdatedQuire11ty returns warning when version is outdated', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns(JSON.stringify({
+          name: '@thegetty/quire-11ty',
+          version: '1.0.0-rc.30',
+        })),
+      },
+    },
+    '#lib/npm/index.js': {
+      default: {
+        view: sandbox.stub().resolves('1.0.0-rc.33'),
+      },
+    },
+    '#lib/conf/config.js': {
+      default: {
+        get: sandbox.stub().returns('rc'),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn')
+  t.regex(result.message, /1\.0\.0-rc\.30 installed/)
+  t.regex(result.message, /1\.0\.0-rc\.33 available/)
+  t.truthy(result.remediation)
+  t.truthy(result.docsUrl)
+})
+
+test('checkOutdatedQuire11ty returns warning when cannot read installed version', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().throws(new Error('ENOENT')),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn')
+  t.regex(result.message, /Could not read/)
+  t.truthy(result.remediation)
+})
+
+test('checkOutdatedQuire11ty returns ok with message when network check fails', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkOutdatedQuire11ty } = await esmock('./quire-11ty.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(true),
+        readFileSync: sandbox.stub().returns(JSON.stringify({
+          name: '@thegetty/quire-11ty',
+          version: '1.0.0-rc.30',
+        })),
+      },
+    },
+    '#lib/npm/index.js': {
+      default: {
+        view: sandbox.stub().rejects(new Error('Network error')),
+      },
+    },
+    '#lib/conf/config.js': {
+      default: {
+        get: sandbox.stub().returns('rc'),
+      },
+    },
+  })
+
+  const result = await checkOutdatedQuire11ty()
+
+  t.true(result.ok)
+  t.regex(result.message, /1\.0\.0-rc\.30/)
+  t.regex(result.message, /could not check/)
+})

package/src/lib/doctor/checks/project/quire-project.js

@@ -0,0 +1,38 @@
+/**
+ * Quire project detection check
+ *
+ * @module lib/doctor/checks/project/quire-project
+ */
+import fs from 'node:fs'
+import { PROJECT_MARKERS } from '#lib/project/index.js'
+import createDebug from '#debug'
+import { DOCS_BASE_URL } from '#lib/doctor/constants.js'
+
+const debug = createDebug('lib:doctor:quire-project')
+
+/**
+ * Check if current directory is a Quire project
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkQuireProject() {
+  const found = PROJECT_MARKERS.find((marker) => fs.existsSync(marker))
+  debug('Quire project marker: %s', found || 'none')
+
+  if (found) {
+    return {
+      ok: true,
+      message: `Detected via ${found}`,
+    }
+  }
+
+  return {
+    ok: false,
+    message: 'No Quire project marker found',
+    remediation: `This command should be run from within a Quire project directory.
+    • Navigate to your project: cd your-project-name
+    • Or create a new project: quire new my-project`,
+    docsUrl: `${DOCS_BASE_URL}/quire-commands/#start-a-new-project`,
+  }
+}
+
+export default checkQuireProject

package/src/lib/doctor/checks/project/quire-project.test.js

@@ -0,0 +1,47 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkQuireProject returns ok when marker file exists', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkQuireProject } = await esmock('./quire-project.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().callsFake((path) => path === '.quire'),
+      },
+    },
+  })
+
+  const result = checkQuireProject()
+
+  t.true(result.ok)
+  t.regex(result.message, /Detected via \.quire/)
+})
+
+test('checkQuireProject returns not ok when no marker file exists', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkQuireProject } = await esmock('./quire-project.js', {
+    'node:fs': {
+      default: {
+        existsSync: sandbox.stub().returns(false),
+      },
+    },
+  })
+
+  const result = checkQuireProject()
+
+  t.false(result.ok)
+  t.regex(result.message, /No Quire project marker/)
+  t.truthy(result.remediation, 'should include remediation guidance')
+  t.truthy(result.docsUrl, 'should include documentation link')
+})

package/src/lib/doctor/checks/tools/index.js

@@ -0,0 +1,10 @@
+/**
+ * Tool checks
+ *
+ * Optional external tools that enhance Quire output capabilities.
+ * These are not required for core Quire functionality.
+ *
+ * @module lib/doctor/checks/tools
+ */
+export { checkPrinceAvailable } from './prince-available.js'
+export { checkPandocAvailable } from './pandoc-available.js'

package/src/lib/doctor/checks/tools/pandoc-available.js

@@ -0,0 +1,82 @@
+/**
+ * Pandoc availability check
+ *
+ * Checks if Pandoc is installed and available in PATH.
+ * Pandoc is an optional EPUB engine - only required when using --engine pandoc.
+ *
+ * @module lib/doctor/checks/tools/pandoc-available
+ */
+import which from 'which'
+import createDebug from '#debug'
+import { getPlatform, Platform } from '#lib/platform.js'
+import { DOCS_BASE_URL } from '#lib/doctor/constants.js'
+
+const debug = createDebug('lib:doctor:pandoc-available')
+
+/**
+ * Get pandoc binary path if available
+ * @returns {string|null} Path to pandoc binary or null if not found
+ */
+function getPandocPath() {
+  return which.sync('pandoc', { nothrow: true })
+}
+
+/**
+ * Get OS-specific Pandoc installation instructions
+ * @returns {string}
+ */
+function getRemediation() {
+  const platform = getPlatform()
+
+  switch (platform) {
+    case Platform.MACOS:
+      return `Pandoc is optional (only needed for --engine pandoc).
+    • Install via Homebrew: brew install pandoc
+    • Or download from: https://pandoc.org/installing.html`
+    case Platform.WINDOWS:
+      return `Pandoc is optional (only needed for --engine pandoc).
+    • Install via winget: winget install --source winget --exact --id JohnMacFarlane.Pandoc
+    • Or download from: https://pandoc.org/installing.html
+    • Restart your terminal after installation`
+    case Platform.LINUX:
+      return `Pandoc is optional (only needed for --engine pandoc).
+    • Install via package manager: apt install pandoc / dnf install pandoc
+    • Or download from: https://pandoc.org/installing.html`
+    default:
+      return `Pandoc is optional (only needed for --engine pandoc).
+    • Download from: https://pandoc.org/installing.html`
+  }
+}
+
+/**
+ * Check Pandoc is available in PATH
+ *
+ * This is an optional check - Pandoc is only required when using
+ * the --engine pandoc option for EPUB generation. The default engine
+ * (epubjs) does not require Pandoc.
+ *
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkPandocAvailable() {
+  const pandocPath = getPandocPath()
+  const ok = !!pandocPath
+  debug('pandoc available: %s', ok)
+
+  if (ok) {
+    return {
+      ok: true,
+      message: 'installed',
+      details: pandocPath,
+    }
+  }
+
+  return {
+    ok: false,
+    level: 'warn',
+    message: 'not found (optional)',
+    remediation: getRemediation(),
+    docsUrl: `${DOCS_BASE_URL}/quire-commands/#epub`,
+  }
+}
+
+export default checkPandocAvailable

package/src/lib/doctor/checks/tools/pandoc-available.test.js

@@ -0,0 +1,73 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkPandocAvailable returns ok when pandoc is available', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPandocAvailable } = await esmock('./pandoc-available.js', {
+    which: {
+      sync: sandbox.stub().returns('/usr/local/bin/pandoc'),
+    },
+  })
+
+  const result = checkPandocAvailable()
+
+  t.true(result.ok)
+  t.regex(result.message, /installed/)
+  t.is(result.details, '/usr/local/bin/pandoc')
+})
+
+test('checkPandocAvailable returns warning when pandoc is missing', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPandocAvailable } = await esmock('./pandoc-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPandocAvailable()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn', 'should be a warning, not an error')
+  t.is(result.message, 'not found (optional)')
+  t.truthy(result.remediation, 'should include remediation guidance')
+  t.truthy(result.docsUrl, 'should include documentation link')
+})
+
+test('checkPandocAvailable remediation includes download link', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPandocAvailable } = await esmock('./pandoc-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPandocAvailable()
+
+  t.regex(result.remediation, /pandoc\.org/, 'should include Pandoc download URL')
+})
+
+test('checkPandocAvailable remediation mentions --engine pandoc', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPandocAvailable } = await esmock('./pandoc-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPandocAvailable()
+
+  t.regex(result.remediation, /--engine pandoc/, 'should mention --engine pandoc flag')
+})

package/src/lib/doctor/checks/tools/prince-available.js

@@ -0,0 +1,81 @@
+/**
+ * PrinceXML availability check
+ *
+ * Checks if PrinceXML is installed and available in PATH.
+ * PrinceXML is an optional PDF engine - only required when using --engine prince.
+ *
+ * @module lib/doctor/checks/tools/prince-available
+ */
+import which from 'which'
+import createDebug from '#debug'
+import { getPlatform, Platform } from '#lib/platform.js'
+import { DOCS_BASE_URL } from '#lib/doctor/constants.js'
+
+const debug = createDebug('lib:doctor:prince-available')
+
+/**
+ * Get prince binary path if available
+ * @returns {string|null} Path to prince binary or null if not found
+ */
+function getPrincePath() {
+  return which.sync('prince', { nothrow: true })
+}
+
+/**
+ * Get OS-specific PrinceXML installation instructions
+ * @returns {string}
+ */
+function getRemediation() {
+  const platform = getPlatform()
+
+  switch (platform) {
+    case Platform.MACOS:
+      return `PrinceXML is optional (only needed for --engine prince).
+    • Download from: https://www.princexml.com/download/
+    • Or install via Homebrew: brew install --cask prince`
+    case Platform.WINDOWS:
+      return `PrinceXML is optional (only needed for --engine prince).
+    • Download from: https://www.princexml.com/download/
+    • Restart your terminal after installation`
+    case Platform.LINUX:
+      return `PrinceXML is optional (only needed for --engine prince).
+    • Download from: https://www.princexml.com/download/
+    • Follow platform-specific installation instructions`
+    default:
+      return `PrinceXML is optional (only needed for --engine prince).
+    • Download from: https://www.princexml.com/download/`
+  }
+}
+
+/**
+ * Check PrinceXML is available in PATH
+ *
+ * This is an optional check - PrinceXML is only required when using
+ * the --engine prince option for PDF generation. The default engine
+ * (Paged.js) does not require PrinceXML.
+ *
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkPrinceAvailable() {
+  const princePath = getPrincePath()
+  const ok = !!princePath
+  debug('prince available: %s', ok)
+
+  if (ok) {
+    return {
+      ok: true,
+      message: 'installed',
+      details: princePath,
+    }
+  }
+
+  return {
+    ok: false,
+    level: 'warn',
+    message: 'not found (optional)',
+    remediation: getRemediation(),
+    docsUrl: `${DOCS_BASE_URL}/quire-commands/#pdf`,
+  }
+}
+
+export default checkPrinceAvailable

package/src/lib/doctor/checks/tools/prince-available.test.js

@@ -0,0 +1,73 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkPrinceAvailable returns ok when prince is available', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPrinceAvailable } = await esmock('./prince-available.js', {
+    which: {
+      sync: sandbox.stub().returns('/usr/local/bin/prince'),
+    },
+  })
+
+  const result = checkPrinceAvailable()
+
+  t.true(result.ok)
+  t.regex(result.message, /installed/)
+  t.is(result.details, '/usr/local/bin/prince')
+})
+
+test('checkPrinceAvailable returns warning when prince is missing', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPrinceAvailable } = await esmock('./prince-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPrinceAvailable()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn', 'should be a warning, not an error')
+  t.is(result.message, 'not found (optional)')
+  t.truthy(result.remediation, 'should include remediation guidance')
+  t.truthy(result.docsUrl, 'should include documentation link')
+})
+
+test('checkPrinceAvailable remediation includes download link', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPrinceAvailable } = await esmock('./prince-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPrinceAvailable()
+
+  t.regex(result.remediation, /princexml\.com/, 'should include PrinceXML download URL')
+})
+
+test('checkPrinceAvailable remediation mentions --engine prince', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPrinceAvailable } = await esmock('./prince-available.js', {
+    which: {
+      sync: sandbox.stub().returns(null),
+    },
+  })
+
+  const result = checkPrinceAvailable()
+
+  t.regex(result.remediation, /--engine prince/, 'should mention --engine prince flag')
+})

package/src/lib/doctor/constants.js

@@ -0,0 +1,39 @@
+/**
+ * Re-export shared constants for doctor checks
+ *
+ * This module re-exports constants from the shared lib/constants.js
+ * to maintain backwards compatibility with existing doctor check imports.
+ *
+ * @module lib/doctor/constants
+ */
+export {
+  DOCS_BASE_URL,
+  QUIRE_11TY_PACKAGE,
+  REQUIRED_NODE_VERSION,
+} from '#lib/constants.js'
+
+/**
+ * Stale threshold intervals in milliseconds, keyed by setting name.
+ *
+ * Used by output checks (stale-build, pdf-output, epub-output) to determine
+ * how much time must elapse before an output is flagged as stale.
+ *
+ * @constant {Object<string, number>}
+ */
+export const STALE_THRESHOLDS = Object.freeze({
+  ZERO: 0,
+  SHORT: 5 * 60 * 1000,
+  HOURLY: 60 * 60 * 1000,
+  DAILY: 12 * 60 * 60 * 1000,
+  NEVER: Infinity,
+})
+
+/**
+ * Resolve the staleThreshold config value to milliseconds.
+ *
+ * @param {string} value - One of the STALE_THRESHOLDS keys
+ * @returns {number} Threshold in milliseconds
+ */
+export function resolveStaleThreshold(value) {
+  return STALE_THRESHOLDS[value] ?? STALE_THRESHOLDS.HOURLY
+}