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

package/src/commands/pdf.spec.js

@@ -0,0 +1,114 @@
+import { Command, Option } from 'commander'
+import program from '#src/main.js'
+import test from 'ava'
+
+/**
+ * Command Contract/Interface Tests
+ *
+ * Verifies the command's public API and Commander.js integration.
+ * @see docs/testing-commands.md
+ */
+
+test.before((t) => {
+  // Get the registered command (from program.commands) once and share across all tests
+  t.context.command = program.commands.find((cmd) => cmd.name() === 'pdf')
+})
+
+test('command is registered in CLI program', (t) => {
+  const { command } = t.context
+
+  t.truthy(command, 'command "pdf" should be registered in program')
+  t.true(command instanceof Command, 'registered command should be Commander.js Command instance')
+})
+
+test('registered command has correct metadata', (t) => {
+  const { command } = t.context
+
+  t.is(command.name(), 'pdf')
+  t.truthy(command.description())
+  t.is(typeof command._actionHandler, 'function', 'command should have action handler')
+})
+
+test('registered command has no arguments', (t) => {
+  const { command } = t.context
+  const registeredArguments = command.registeredArguments
+
+  t.is(registeredArguments.length, 0, 'pdf command should have no arguments')
+})
+
+test('registered command has correct options', (t) => {
+  const { command } = t.context
+
+  // Get all options
+  const engineOption = command.options.find((opt) => opt.long === '--engine')
+  const libOption = command.options.find((opt) => opt.long === '--lib')
+  const buildOption = command.options.find((opt) => opt.long === '--build')
+  const openOption = command.options.find((opt) => opt.long === '--open')
+  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(engineOption, '--engine option should exist')
+  t.truthy(libOption, '--lib option should exist (deprecated alias)')
+  t.truthy(buildOption, '--build option should exist')
+  t.truthy(openOption, '--open 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(engineOption instanceof Option, '--engine should be Option instance')
+  t.true(libOption instanceof Option, '--lib should be Option instance')
+  t.true(buildOption instanceof Option, '--build should be Option instance')
+  t.true(openOption instanceof Option, '--open 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 --engine option properties
+  t.is(engineOption.long, '--engine')
+  t.truthy(engineOption.description)
+  t.true(engineOption.required, '--engine should require a value')
+
+  // Verify --lib is hidden (deprecated alias)
+  t.is(libOption.long, '--lib')
+  t.true(libOption.hidden, '--lib should be hidden (deprecated)')
+
+  t.is(buildOption.long, '--build')
+  t.truthy(buildOption.description)
+  t.false(buildOption.required, '--build should not require a value')
+
+  t.is(openOption.long, '--open')
+  t.truthy(openOption.description)
+  t.false(openOption.required, '--open should not require a value')
+
+  t.is(quietOption.long, '--quiet')
+  t.is(quietOption.short, '-q', '--quiet should have -q short flag')
+  t.truthy(quietOption.description)
+  t.false(quietOption.required, '--quiet should not require a value')
+
+  t.is(verboseOption.long, '--verbose')
+  t.is(verboseOption.short, '-v', '--verbose should have -v short flag')
+  t.truthy(verboseOption.description)
+  t.false(verboseOption.required, '--verbose should not require a value')
+
+  t.is(debugOption.long, '--debug')
+  t.truthy(debugOption.description)
+  t.false(debugOption.required, '--debug should not require a value')
+})
+
+test('command options are accessible via public API', (t) => {
+  const { command } = t.context
+
+  // Test that options can be accessed the way Commander.js does
+  const optionNames = command.options.map((opt) => opt.long)
+
+  t.true(optionNames.includes('--engine'))
+  t.true(optionNames.includes('--lib'))  // deprecated alias still exists
+  t.true(optionNames.includes('--build'))
+  t.true(optionNames.includes('--open'))
+  t.true(optionNames.includes('--quiet'))
+  t.true(optionNames.includes('--verbose'))
+  t.true(optionNames.includes('--debug'))
+})

package/src/commands/pdf.test.js

@@ -0,0 +1,464 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+
+  // Create mock reporter
+  t.context.mockReporter = {
+    configure: t.context.sandbox.stub().returnsThis(),
+    start: t.context.sandbox.stub().returnsThis(),
+    update: t.context.sandbox.stub().returnsThis(),
+    succeed: t.context.sandbox.stub().returnsThis(),
+    fail: t.context.sandbox.stub().returnsThis(),
+    stop: t.context.sandbox.stub().returnsThis(),
+  }
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('pdf command should call generatePdf with pagedjs engine', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs' }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'pagedjs', 'should pass lib to generatePdf')
+  // Nota bene: reporter lifecycle (start/succeed/fail) is handled by the façade, not the command
+})
+
+test('pdf command should call generatePdf with prince engine', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'prince' }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'prince', 'should pass lib to generatePdf')
+})
+
+test('pdf command should open PDF when --open flag is provided', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const outputPath = '/project/_site/_pdf/test-book.pdf'
+  const mockGeneratePdf = sandbox.stub().resolves(outputPath)
+  const mockOpen = sandbox.stub()
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: mockOpen
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs', open: true }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.true(mockOpen.called, 'open should be called when --open flag is provided')
+  t.is(mockOpen.firstCall.args[0], outputPath, 'should open the generated PDF path')
+})
+
+test('pdf command should not open PDF when --open flag is not provided', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+  const mockOpen = sandbox.stub()
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: mockOpen
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs' }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.false(mockOpen.called, 'open should not be called without --open flag')
+})
+
+test('pdf command should pass debug option to generatePdf', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs', debug: true }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'pagedjs', 'should pass lib to generatePdf')
+  t.true(mockGeneratePdf.firstCall.args[0].debug, 'should pass debug option')
+})
+
+test('pdf command should propagate MissingBuildOutputError from façade', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  // Simulate the façade throwing MissingBuildOutputError when pdf.html is missing
+  const missingBuildError = new Error('Cannot generate pdf.html: build output not found')
+  missingBuildError.code = 'BUILD_OUTPUT_MISSING'
+  const mockGeneratePdf = sandbox.stub().rejects(missingBuildError)
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true // Command doesn't check this for validation anymore
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  const error = await t.throwsAsync(() => command.action({ engine: 'pagedjs' }, command))
+
+  t.is(error.code, 'BUILD_OUTPUT_MISSING', 'should propagate error code from façade')
+  t.true(mockGeneratePdf.called, 'generatePdf should be called (validation is in façade)')
+})
+
+test('pdf command should run build first when --build flag is set and output missing', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+  const mockBuild = sandbox.stub().resolves()
+  let buildCalled = false
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => {
+        // Return false first (before build), true after build
+        if (!buildCalled) return false
+        return true
+      }
+    },
+    '#lib/11ty/index.js': {
+      default: {
+        build: async (opts) => {
+          buildCalled = true
+          return mockBuild(opts)
+        }
+      }
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs', build: true }, command)
+
+  t.true(mockBuild.called, 'build should be called when --build flag is set')
+  t.true(mockGeneratePdf.called, 'generatePdf should be called after build')
+})
+
+test('pdf command should support deprecated --lib option', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  // Use deprecated --lib option (should still work)
+  await command.action({ lib: 'prince' }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called with deprecated --lib')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'prince', 'should pass lib to generatePdf from deprecated option')
+})
+
+test('pdf command should propagate errors from generatePdf', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const pdfError = new Error('PDF generation failed')
+  const mockGeneratePdf = sandbox.stub().rejects(pdfError)
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await t.throwsAsync(() => command.action({ engine: 'pagedjs' }, command), { message: 'PDF generation failed' })
+
+  // Note: reporter lifecycle (start/succeed/fail) is handled by the façade, not the command
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+})
+
+test('pdf command should configure reporter with quiet option', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs', quiet: true }, command)
+
+  t.true(
+    mockReporter.configure.calledWith(sinon.match({ quiet: true })),
+    'reporter.configure should be called with quiet option'
+  )
+})
+
+test('pdf command should pass output option to generatePdf', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const customOutput = '/custom/path/my-book.pdf'
+  const mockGeneratePdf = sandbox.stub().resolves(customOutput)
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+
+  await command.action({ engine: 'pagedjs', output: customOutput }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].output, customOutput, 'should pass output option to generatePdf')
+})
+
+test('pdf command should use pdfEngine from config when --engine not specified', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+  // Mock config to return 'prince' for pdfEngine
+  command.config = { get: (key) => key === 'pdfEngine' ? 'prince' : undefined }
+
+  // No --engine specified, should use config value
+  await command.action({}, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'prince', 'should use pdfEngine from config')
+})
+
+test('pdf command should use default engine when --engine not specified and config not set', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+  // Mock config to return undefined (no pdfEngine set)
+  command.config = { get: () => undefined }
+
+  // No --engine specified, no config, should use default 'pagedjs'
+  await command.action({}, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'pagedjs', 'should use default pagedjs when no config')
+})
+
+test('pdf command --engine flag should override config pdfEngine', async (t) => {
+  const { sandbox, mockReporter } = t.context
+
+  const mockGeneratePdf = sandbox.stub().resolves('/project/_site/_pdf/test-book.pdf')
+
+  const PDFCommand = await esmock('./pdf.js', {
+    '#lib/pdf/index.js': {
+      default: mockGeneratePdf
+    },
+    '#lib/project/index.js': {
+      hasSiteOutput: () => true
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    open: {
+      default: sandbox.stub()
+    }
+  })
+
+  const command = new PDFCommand()
+  command.name = sandbox.stub().returns('pdf')
+  // Mock config to return 'prince' for pdfEngine
+  command.config = { get: (key) => key === 'pdfEngine' ? 'prince' : undefined }
+
+  // --engine pagedjs should override config's 'prince'
+  await command.action({ engine: 'pagedjs' }, command)
+
+  t.true(mockGeneratePdf.called, 'generatePdf should be called')
+  t.is(mockGeneratePdf.firstCall.args[0].lib, 'pagedjs', 'CLI --engine should override config')
+})

package/src/commands/preview.js

@@ -1,5 +1,7 @@
 import Command from '#src/Command.js'
-import { api, cli, paths, projectRoot  } from '#lib/11ty/index.js'
+import { Option } from 'commander'
+import { withOutputModes } from '#lib/commander/index.js'
+import { api, cli } from '#lib/11ty/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -11,50 +13,43 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class PreviewCommand extends Command {
-  static definition = {
+  static definition = withOutputModes({
     name: 'preview',
     description: 'Run the development server and watch on file changes',
-    summary: 'run the development server',
-    version: '1.0.0',
-    args: [
-      // [
-      //   '[formats...]', 'output formats',
-      //   {
-      //     choices: ['pdf', 'epub'],
-      //   }
-      // ],
-    ],
+    summary: 'start local preview server',
+    docsLink: 'quire-commands/#start-and-preview-projects',
+    helpText: `
+Examples:
+  quire preview                  Start preview server on default port
+  quire preview --port 3000      Run on custom port
+  quire preview --verbose        Start with detailed progress
+`,
+    version: '1.1.0',
     options: [
-      [ '-p', '--port <port>', 'configure development server port', 8080 ],
-      [ '-q', '--quiet', 'run preview in silent mode' ],
-      [ '-v', '--verbose', 'run preview with verbose console messages' ],
-      [
-        '--11ty <module>', 'use the specified 11ty module', 'cli',
-        // { choices: ['api', 'cli'], default: 'cli' }
-      ],
-      [ '--debug', 'run preview with debug output to console' ],
+      [ '-p, --port <port>', 'configure development server port', 8080 ],
+      // Use Option object syntax to configure this as a hidden option
+      new Option('--11ty <module>', 'use the specified 11ty module')
+        .choices(['api', 'cli']).default('api').hideHelp(),
     ],
-  }
+  })
 
   constructor() {
     super(PreviewCommand.definition)
   }
 
   async action(options, command) {
-    if (options.debug) {
-      console.debug('[CLI] Command \'%s\' called with arguments [%o] and options %o', this.name(), options)
-    }
+    this.debug('called with options %O', options)
 
-    if (options['11ty'] === 'cli') {
-      console.debug('[CLI] running eleventy using lib/11ty cli')
-      cli.serve(options)
-    } else {
-      console.debug('[CLI] running eleventy using lib/11ty api')
+    if (options['11ty'] === 'api') {
+      this.debug('running eleventy using lib/11ty api')
       api.serve(options)
+    } else {
+      this.debug('running eleventy using lib/11ty cli')
+      cli.serve(options)
     }
   }
 
-  preAction(command) {
-    testcwd(command)
+  preAction(thisCommand, actionCommand) {
+    testcwd(thisCommand)
   }
 }