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

package/src/commands/build.js

@@ -1,6 +1,10 @@
 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 paths from '#lib/project/index.js'
 import { clean } from '#helpers/clean.js'
+import reporter from '#lib/reporter/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -12,56 +16,61 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class BuildCommand extends Command {
-  static definition = {
+  static definition = withOutputModes({
     name: 'build',
     description: 'Generate publication outputs',
-    summary: 'run build',
-    version: '1.0.0',
-    args: [
-      // [
-      //   '[formats...]', 'output formats',
-      //   {
-      //     choices: ['pdf', 'epub'],
-      //   }
-      // ],
-    ],
+    summary: 'generate HTML site files',
+    docsLink: 'quire-commands/#output-files',
+    helpText: `
+Examples:
+  quire build                Build the site
+  quire build --verbose      Build with detailed progress
+  quire build --debug        Build with debug output
+
+Note: Run before "quire pdf" or "quire epub" commands.
+`,
+    version: '1.1.0',
     options: [
       [ '-d', '--dry-run', 'run build without writing files' ],
-      [ '-q', '--quiet', 'run build with no console messages' ],
-      [ '-v', '--verbose', 'run build with verbose console messages' ],
-      [
-        '--11ty <module>', 'use the specified 11ty module', 'cli',
-        // { choices: ['api', 'cli'], default: 'cli' }
-      ],
-      [ '--debug', 'run build with debug output to console' ],
+      [ '--dryrun', 'alias for --dry-run', { hidden: true, implies: { dryRun: true } } ],
+      // 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(BuildCommand.definition)
   }
 
-  action(options, command) {
-    if (options.debug) {
-      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
-    }
+  async action(options, command) {
+    this.debug('called with options %O', options)
 
-    if (options['11ty'] === 'cli') {
-      console.debug('[CLI] running eleventy using lib/11ty cli')
-      cli.build(options)
-    } else {
-      console.debug('[CLI] running eleventy using lib/11ty api')
-      api.build(options)
+    // 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')
+        await api.build(options)
+      } else {
+        this.debug('running eleventy using lib/11ty cli')
+        await cli.build(options)
+      }
+      reporter.succeed('Build complete')
+    } catch (error) {
+      reporter.fail('Build failed')
+      throw error
     }
   }
 
-  preAction(command) {
-    testcwd(command)
+  preAction(thisCommand, actionCommand) {
+    testcwd(thisCommand)
 
-    const options = command.opts()
-    if (options.debug) {
-      console.debug('[CLI] Calling \'build\' command pre-action with options', options)
-    }
-    clean(projectRoot, paths, options)
+    const options = thisCommand.opts()
+    this.debug('pre-action with options %O', options)
+    clean(paths.getProjectRoot(), paths.toObject(), options)
   }
 }

package/src/commands/build.spec.js

@@ -0,0 +1,113 @@
+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() === 'build')
+})
+
+test('command is registered in CLI program', (t) => {
+  const { command } = t.context
+
+  t.truthy(command, 'command "build" 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(), 'build')
+  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, 'build command should have no arguments')
+})
+
+test('registered command has correct options', (t) => {
+  const { command } = t.context
+
+  // Get all options
+  const dryRunOption = command.options.find((opt) => opt.long === '--dry-run')
+  const dryrunAlias = command.options.find((opt) => opt.long === '--dryrun')
+  const quietOption = command.options.find((opt) => opt.long === '--quiet')
+  const verboseOption = command.options.find((opt) => opt.long === '--verbose')
+  const progressOption = command.options.find((opt) => opt.long === '--progress')
+  const eleventyOption = command.options.find((opt) => opt.long === '--11ty')
+  const debugOption = command.options.find((opt) => opt.long === '--debug')
+
+  // Verify all options exist
+  t.truthy(dryRunOption, '--dry-run option should exist')
+  t.truthy(dryrunAlias, '--dryrun alias should exist')
+  t.truthy(quietOption, '--quiet option should exist')
+  t.truthy(verboseOption, '--verbose option should exist')
+  t.truthy(progressOption, '--progress option should exist')
+  t.truthy(eleventyOption, '--11ty option should exist')
+  t.truthy(debugOption, '--debug option should exist')
+
+  // 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(quietOption instanceof Option, '--quiet should be Option instance')
+  t.true(verboseOption instanceof Option, '--verbose should be Option instance')
+  t.true(progressOption instanceof Option, '--progress should be Option instance')
+  t.true(eleventyOption instanceof Option, '--11ty should be Option instance')
+  t.true(debugOption instanceof Option, '--debug should be Option instance')
+
+  // Verify option properties
+  t.is(dryRunOption.long, '--dry-run')
+  t.is(dryRunOption.short, '-d')
+  t.truthy(dryRunOption.description)
+
+  // --dryrun is a hidden alias for --dry-run
+  t.is(dryrunAlias.long, '--dryrun')
+  t.true(dryrunAlias.hidden, '--dryrun should be hidden from help')
+
+  t.is(quietOption.long, '--quiet')
+  t.is(quietOption.short, '-q')
+  t.truthy(quietOption.description)
+
+  t.is(verboseOption.long, '--verbose')
+  t.is(verboseOption.short, '-v')
+  t.truthy(verboseOption.description)
+
+  // --progress is a hidden alias for --verbose
+  t.is(progressOption.long, '--progress')
+  t.truthy(progressOption.description)
+  t.true(progressOption.hidden, '--progress should be hidden from help')
+
+  t.is(eleventyOption.long, '--11ty')
+  t.truthy(eleventyOption.description)
+  t.true(eleventyOption.required, '--11ty should 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('--dry-run'))
+  t.true(optionNames.includes('--dryrun'))
+  t.true(optionNames.includes('--quiet'))
+  t.true(optionNames.includes('--verbose'))
+  t.true(optionNames.includes('--progress'))
+  t.true(optionNames.includes('--11ty'))
+  t.true(optionNames.includes('--debug'))
+})

package/src/commands/build.test.js

@@ -0,0 +1,402 @@
+import test from 'ava'
+import { Volume, createFsFromVolume } from 'memfs'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  // Create sinon sandbox for mocking
+  t.context.sandbox = sinon.createSandbox()
+
+  // Create in-memory file system
+  t.context.vol = new Volume()
+  t.context.fs = createFsFromVolume(t.context.vol)
+
+  // Setup mock directory structure
+  t.context.vol.fromJSON({
+    '/project/content/_data/config.yaml': 'title: Test Project',
+    '/project/content/index.md': '# Quire Test Project',
+    '/project/package.json': JSON.stringify({ name: 'test-project' })
+  })
+
+  t.context.projectRoot = '/project'
+
+  // Create mock logger (no global console stubbing needed!)
+  t.context.mockLogger = {
+    info: t.context.sandbox.stub(),
+    error: t.context.sandbox.stub(),
+    debug: t.context.sandbox.stub(),
+    log: t.context.sandbox.stub(),
+    warn: t.context.sandbox.stub()
+  }
+
+  // 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) => {
+  // Restore all mocks
+  t.context.sandbox.restore()
+
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
+
+test('build command should call eleventy CLI with default options', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock eleventy CLI module
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  // Mock eleventy API module
+  const mockEleventyApi = {
+    build: sandbox.stub().resolves()
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      api: mockEleventyApi,
+      cli: mockEleventyCli
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+  command.opts = sandbox.stub().returns({})
+
+  // Run preAction
+  command.preAction(command)
+
+  // Run action with default options (uses cli by default)
+  await command.action({ '11ty': 'cli' }, command)
+
+  t.true(mockTestcwd.called, 'testcwd should be called in preAction')
+  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) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock eleventy CLI module
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  // Mock eleventy API module
+  const mockEleventyApi = {
+    build: sandbox.stub().resolves()
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      cli: mockEleventyCli,
+      api: mockEleventyApi
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+
+  // Run action with api option
+  await command.action({ '11ty': 'api' }, command)
+
+  t.false(mockEleventyCli.build.called, 'eleventy CLI build should not be called')
+  t.true(mockEleventyApi.build.called, 'eleventy API build should be called')
+})
+
+test('build command should call clean with correct parameters in preAction', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock eleventy modules
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  const mockEleventyApi = {
+    build: sandbox.stub().resolves()
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      cli: mockEleventyCli,
+      api: mockEleventyApi
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+  const options = { verbose: true }
+  command.opts = sandbox.stub().returns(options)
+
+  // Run preAction
+  command.preAction(command)
+
+  t.true(mockClean.called, 'clean should be called')
+  t.true(mockClean.calledWith('/project', { output: '_site' }, options), 'clean should be called with correct parameters')
+})
+
+test('build command should pass options to eleventy build', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock eleventy CLI module
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  // Mock eleventy API module
+  const mockEleventyApi = {
+    build: sandbox.stub().resolves()
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      cli: mockEleventyCli,
+      api: mockEleventyApi
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+
+  const options = { '11ty': 'cli', verbose: true, quiet: false }
+
+  // Run action with options
+  await command.action(options, command)
+
+  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) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  const buildError = new Error('Build failed')
+
+  // Mock eleventy API module to throw error
+  const mockEleventyApi = {
+    build: sandbox.stub().rejects(buildError)
+  }
+
+  // Mock eleventy CLI module
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      api: mockEleventyApi,
+      cli: mockEleventyCli
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+
+  // Run action and expect it to throw
+  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) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock eleventy CLI module
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
+
+  // Mock eleventy API module
+  const mockEleventyApi = {
+    build: sandbox.stub().resolves()
+  }
+
+  // Mock clean helper
+  const mockClean = sandbox.stub()
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      cli: mockEleventyCli,
+      api: mockEleventyApi
+    },
+    '#lib/project/index.js': {
+      default: {
+        getProjectRoot: () => '/project',
+        toObject: () => ({ output: '_site' })
+      }
+    },
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#helpers/test-cwd.js': {
+      default: mockTestcwd
+    },
+    '#lib/logger/index.js': {
+      logger: mockLogger
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  })
+
+  const command = new BuildCommand()
+  command.name = sandbox.stub().returns('build')
+
+  const options = { '11ty': 'api', quiet: true }
+
+  // Run action with quiet option
+  await command.action(options, command)
+
+  t.true(
+    mockReporter.configure.calledWith(sinon.match({ quiet: true })),
+    'reporter.configure should be called with quiet option'
+  )
+})

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 { paths, projectRoot  } from '#lib/11ty/index.js'
+import paths from '#lib/project/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -15,39 +16,44 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class CleanCommand extends Command {
-  static definition = {
+  static definition = withOutputModes({
     name: 'clean',
     description: 'Remove build outputs',
-    summary: 'remove build outputs',
+    summary: 'delete generated files',
+    docsLink: 'quire-commands/#output-files',
+    helpText: `
+Examples:
+  quire clean                  Remove build outputs
+  quire clean --dry-run        Preview files to be deleted
+  quire clean --verbose        Clean with detailed progress
+`,
     version: '1.0.0',
-    args: [],
     options: [
-      [ '-d', '--dry-run', 'show paths to be cleaned without deleting files' ],
-      [ '-p', '--progress', 'display progress of removing files' ],
-      [ '-v', '--verbose', 'run clean with verbose console messages' ],
-      [ '--debug', 'run clean with debug output to console' ],
+      [ '-d, --dry-run', 'show paths to be cleaned without deleting files' ],
+      [ '--dryrun', 'alias for --dry-run', { hidden: true, implies: { dryRun: true } } ],
     ],
-  }
+  })
 
   constructor() {
     super(CleanCommand.definition)
   }
 
   async action(options, command) {
-    if (options.debug) {
-      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
-    }
+    this.debug('called with options %O', options)
 
-    const deletedPaths = await clean(projectRoot, paths, options)
+    const deletedPaths = await clean(paths.getProjectRoot(), paths.toObject(), options)
 
-    const message = deletedPaths && deletedPaths.length
-      ? `the following files ${options.dryRun ? 'will be' : 'have been'} deleted:`
-      : 'no files to delete'
+    if (!deletedPaths || !deletedPaths.length) {
+      this.logger.info('No files to delete')
+      return
+    }
 
-    console.debug(`[CLI] ${message}\n${deletedPaths.join('\n')}`)
+    const verb = options.dryRun ? 'Will delete' : 'Deleted'
+    const listing = deletedPaths.map((p) => `  ${p}`).join('\n')
+    this.logger.info(`${verb} ${deletedPaths.length} file(s):\n${listing}`)
   }
 
-  preAction(command) {
-    testcwd(command)
+  preAction(thisCommand, actionCommand) {
+    testcwd(thisCommand)
   }
 }