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

package/src/commands/clean.spec.js

@@ -0,0 +1,108 @@
+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() === 'clean')
+})
+
+test('command is registered in CLI program', (t) => {
+  const { command } = t.context
+
+  t.truthy(command, 'command "clean" 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(), 'clean')
+  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, 'clean 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 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')
+  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(progressOption, '--progress 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(dryRunOption instanceof Option, '--dry-run should be Option instance')
+  t.true(dryrunAlias instanceof Option, '--dryrun 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')
+  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)
+  t.false(dryRunOption.required, '--dry-run should not require a value')
+
+  // --dryrun is a hidden alias for --dry-run
+  t.is(dryrunAlias.long, '--dryrun')
+  t.true(dryrunAlias.hidden, '--dryrun should be hidden from help')
+
+  // --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(quietOption.long, '--quiet')
+  t.is(quietOption.short, '-q')
+  t.truthy(quietOption.description)
+  t.false(quietOption.required, '--quiet should not require a value')
+
+  t.is(verboseOption.long, '--verbose')
+  t.is(verboseOption.short, '-v')
+  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('--dry-run'))
+  t.true(optionNames.includes('--dryrun'))
+  t.true(optionNames.includes('--progress'))
+  t.true(optionNames.includes('--quiet'))
+  t.true(optionNames.includes('--verbose'))
+  t.true(optionNames.includes('--debug'))
+})

package/src/commands/clean.test.js

@@ -0,0 +1,260 @@
+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 with build artifacts
+  t.context.vol.fromJSON({
+    '/project/_site/index.html': '<html>Quire Test </html>',
+    '/project/_site/styles.css': 'body { }',
+    '/project/content/index.md': '# Content',
+    '/project/package.json': JSON.stringify({ name: 'test-project' })
+  })
+
+  t.context.projectRoot = '/project'
+
+  // Stub console methods to suppress output during tests
+  // 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()
+  }
+})
+
+test.afterEach.always((t) => {
+  // Restore all mocks
+  t.context.sandbox.restore()
+
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
+
+test('clean command should call clean helper with correct parameters', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  // Mock clean helper
+  const mockClean = sandbox.stub().resolves(['/project/_site'])
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#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()
+
+  // Run action
+  const options = {}
+  await command.action(options, command)
+
+  t.true(mockClean.called, 'clean should be called')
+  t.true(mockClean.calledWith('/project', { output: '_site' }, options), 'clean should be called with correct parameters')
+
+  // Verify user-visible output
+  t.true(mockLogger.info.called, 'logger.info should be called with result')
+  const output = mockLogger.info.firstCall.args[0]
+  t.true(output.includes('Deleted'), 'should report deleted files')
+  t.true(output.includes('/project/_site'), 'should list deleted paths')
+})
+
+test('clean command should handle dry-run option', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  // Mock clean helper to return paths that would be deleted
+  const mockClean = sandbox.stub().resolves(['/project/_site/index.html', '/project/_site/styles.css'])
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#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()
+
+  // Run action with dry-run
+  const options = { dryRun: true }
+  await command.action(options, command)
+
+  t.true(mockClean.called, 'clean should be called')
+  t.true(mockClean.calledWith('/project', { output: '_site' }, options), 'clean should receive dry-run option')
+
+  // Verify dry-run output uses "Will delete" instead of "Deleted"
+  const output = mockLogger.info.firstCall.args[0]
+  t.true(output.includes('Will delete'), 'should use future tense for dry-run')
+})
+
+test('clean command should call testcwd in preAction', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  // Mock clean helper
+  const mockClean = sandbox.stub().resolves([])
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#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')
+
+  // Run preAction
+  command.preAction(command)
+
+  t.true(mockTestcwd.called, 'testcwd should be called in preAction')
+  t.true(mockTestcwd.calledWith(command), 'testcwd should be called with command object')
+})
+
+test('clean command should handle empty deletedPaths', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  // Mock clean helper to return empty array (no files to delete)
+  const mockClean = sandbox.stub().resolves([])
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#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()
+
+  // Run action
+  const options = {}
+  await command.action(options, command)
+
+  t.true(mockClean.called, 'clean should be called')
+
+  // Verify "no files" message
+  const output = mockLogger.info.firstCall.args[0]
+  t.true(output.includes('No files to delete'), 'should report no files to delete')
+})
+
+test('clean command should pass all options to clean helper', async (t) => {
+  const { sandbox, fs, mockLogger } = t.context
+
+  // Mock clean helper
+  const mockClean = sandbox.stub().resolves(['/project/_site'])
+
+  // Mock testcwd helper
+  const mockTestcwd = sandbox.stub()
+
+  // Use esmock to replace imports
+  const CleanCommand = await esmock('./clean.js', {
+    '#helpers/clean.js': {
+      clean: mockClean
+    },
+    '#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()
+
+  // Run action with multiple options
+  const options = { verbose: true, dryRun: false }
+  await command.action(options, command)
+
+  t.true(mockClean.calledWith('/project', { output: '_site' }, options), 'clean should receive all options')
+})

package/src/commands/config.js

@@ -0,0 +1,251 @@
+import Command from '#src/Command.js'
+import {
+  isValidKey,
+  getValidKeys,
+  coerceValue,
+  formatValidationError,
+  getDefault,
+  formatSettings,
+} from '#lib/conf/index.js'
+
+/**
+ * Valid operations for the settings command
+ */
+const OPERATIONS = Object.freeze(['get', 'set', 'delete', 'reset', 'path'])
+
+/**
+ * Quire CLI `settings` Command
+ *
+ * Manages quire-cli configuration with explicit subcommand operations.
+ *
+ * @example
+ * // Show all settings
+ * quire settings
+ *
+ * // Get a single value
+ * quire settings get logLevel
+ *
+ * // Set a value
+ * quire settings set logLevel debug
+ *
+ * // Delete a key (reset to default)
+ * quire settings delete logLevel
+ *
+ * // Reset all settings to defaults
+ * quire settings reset
+ *
+ * // Reset a single key to default
+ * quire settings reset logLevel
+ *
+ * // Show settings file path
+ * quire settings path
+ *
+ * @class      SettingsCommand
+ * @extends    {Command}
+ */
+export default class SettingsCommand extends Command {
+  static definition = {
+    name: 'settings',
+    aliases: ['prefs', 'preferences', 'conf', 'config', 'configure'],
+    description: 'Manage Quire CLI settings.',
+    summary: 'view and modify CLI settings',
+    docsLink: 'quire-commands/',
+    helpText: `
+Examples:
+  quire settings                    Show all settings
+  quire settings get <key>          Get a single value
+  quire settings set <key> <value>  Set a value
+  quire settings delete <key>       Delete (reset to default)
+  quire settings reset [key]        Reset all or single key
+  quire settings path               Show settings file path
+  quire settings --json             Output raw config JSON
+  quire settings get <key> --json   Output single value as JSON
+`,
+    version: '2.0.0',
+    args: [
+      ['[operation]', `operation to perform (${OPERATIONS.join(', ')})`],
+      ['[key]', 'configuration key'],
+      ['[value]', 'value to set (for set operation)'],
+    ],
+    options: [
+      ['--json', 'output raw JSON'],
+      ['--debug', 'enable debug output for troubleshooting'],
+    ],
+  }
+
+  constructor() {
+    super(SettingsCommand.definition)
+  }
+
+  /**
+   * Log an unknown key error with valid keys hint
+   *
+   * @param {string} key - The unknown configuration key
+   */
+  #logUnknownKey(key) {
+    this.logger.error(`Unknown configuration key: ${key}`)
+    this.logger.info(`Valid keys: ${getValidKeys().join(', ')}`)
+  }
+
+  /**
+   * Get a single configuration value
+   *
+   * @param {string} key - Configuration key
+   * @param {Object} options - Command options
+   */
+  #getValue(key, options) {
+    if (!key) {
+      this.logger.error('Usage: quire conf get <key>')
+      return
+    }
+
+    if (!isValidKey(key) && !key.startsWith('__internal__')) {
+      this.#logUnknownKey(key)
+      return
+    }
+
+    const value = this.config.get(key)
+
+    if (options.json) {
+      console.log(JSON.stringify(value))
+      return
+    }
+
+    if (value === undefined) {
+      this.logger.info(`${key}: (not set)`)
+    } else {
+      this.logger.info(`${key}: ${JSON.stringify(value)}`)
+    }
+  }
+
+  /**
+   * Set a configuration value
+   *
+   * @param {string} key - Configuration key
+   * @param {string} value - Value to set
+   */
+  #setValue(key, value) {
+    if (!key || value === undefined) {
+      this.logger.error('Usage: quire conf set <key> <value>')
+      return
+    }
+
+    if (!isValidKey(key)) {
+      this.#logUnknownKey(key)
+      return
+    }
+
+    const coercedValue = coerceValue(key, value)
+
+    try {
+      this.config.set(key, coercedValue)
+      this.logger.info(`${key}: ${JSON.stringify(coercedValue)}`)
+    } catch {
+      this.logger.error(formatValidationError(key, coercedValue))
+    }
+  }
+
+  /**
+   * Delete a configuration key (resets to default)
+   *
+   * @param {string} key - Configuration key
+   */
+  #deleteKey(key) {
+    if (!key) {
+      this.logger.error('Usage: quire conf delete <key>')
+      return
+    }
+
+    if (!isValidKey(key)) {
+      this.#logUnknownKey(key)
+      return
+    }
+
+    this.config.delete(key)
+    const defaultValue = getDefault(key)
+    this.logger.info(`${key}: reset to ${JSON.stringify(defaultValue)}`)
+  }
+
+  /**
+   * Reset configuration to defaults
+   *
+   * @param {string} [key] - Optional key to reset (resets all if omitted)
+   */
+  #reset(key) {
+    if (key) {
+      if (!isValidKey(key)) {
+        this.#logUnknownKey(key)
+        return
+      }
+      this.config.reset(key)
+      const defaultValue = getDefault(key)
+      this.logger.info(`${key}: reset to ${JSON.stringify(defaultValue)}`)
+    } else {
+      this.config.clear()
+      this.logger.info('Configuration reset to defaults')
+    }
+  }
+
+  /**
+   * Show all configuration values with descriptions
+   */
+  #showAll(options) {
+    if (options.json) {
+      const store = options.debug
+        ? this.config.store
+        : Object.fromEntries(
+          Object.entries(this.config.store).filter(([k]) => !k.startsWith('__internal__'))
+        )
+      console.log(JSON.stringify(store, null, 2))
+      return
+    }
+
+    const output = formatSettings(this.config.store, {
+      showInternal: options.debug,
+      configPath: this.config.path,
+      useColor: this.config.get('logUseColor'),
+    })
+    this.logger.info(output)
+  }
+
+  /**
+   * Show config file path
+   */
+  #showPath() {
+    this.logger.info(this.config.path)
+  }
+
+  /**
+   * @param {string} [operation] - Operation to perform
+   * @param {string} [key] - Configuration key
+   * @param {string} [value] - Value to set
+   * @param {Object} options - Command options
+   * @return {Promise}
+   */
+  async action(operation, key, value, options = {}) {
+    this.debug('called with operation=%s key=%s value=%s options=%O', operation, key, value, options)
+
+    // Validate operation if provided
+    if (operation && !OPERATIONS.includes(operation)) {
+      this.logger.error(`Unknown operation: ${operation}`)
+      this.logger.info(`Valid operations: ${OPERATIONS.join(', ')}`)
+      return
+    }
+
+    // Dispatch to operation handler
+    switch (operation) {
+      case 'get':
+        return this.#getValue(key, options)
+      case 'set':
+        return this.#setValue(key, value)
+      case 'delete':
+        return this.#deleteKey(key)
+      case 'reset':
+        return this.#reset(key)
+      case 'path':
+        return this.#showPath()
+      default:
+        return this.#showAll(options)
+    }
+  }
+}