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

package/src/commands/README.md

@@ -1,201 +1,292 @@
-## Quire CLI Commands
+# Quire CLI Commands
 
-### `build`
+This directory contains the Quire CLI command implementations and their corresponding tests.
 
-Build Quire publication outputs.
+## Command Class Pattern
 
-```sh
-quire build
-```
+All Quire CLI commands extend the base `Command` class and follow a consistent pattern:
 
-#### `epub`
+### Command Structure
 
-Build Quire publication EPUB format.
+```javascript
+import Command from '#src/Command.js'
 
-```sh
-quire build epub
-```
+export default class MyCommand extends Command {
+  static definition = {
+    name: 'my-command',
+    description: 'Description of what the command does',
+    summary: 'short summary for help text',
+    version: '1.0.0',
+    args: [
+      ['<required-arg>', 'description of required argument'],
+      ['[optional-arg]', 'description of optional argument', 'default-value']
+    ],
+    options: [
+      ['-f', '--flag', 'description of flag'],
+      ['-o', '--option <value>', 'description of option with value', 'default']
+    ]
+  }
 
-#### `info`
+  constructor() {
+    super(MyCommand.definition)
+  }
 
-List `quire-11ty`, `quire-cli`, and starter package versions; use the `--debug` option to include node, npm, and os versions.
+  async action(args, options, command) {
+    // Use this.debug for developer debugging (controlled by DEBUG env var)
+    this.debug('called with options %O', options)
 
-```sh
-quire build info
-```
+    // Use this.logger for user-facing output
+    this.logger.info('Starting operation...')
 
-#### `pdf`
+    // Command implementation
+  }
 
-Build Quire publication PDF format.
+  preAction(command) {
+    // Optional: runs before action()
+  }
 
-```sh
-quire build pdf
+  postAction(command) {
+    // Optional: runs after action()
+  }
+}
 ```
 
-#### `site`
+### Inherited Properties
 
-Build Quire publication HTML format.
+The base `Command` class provides these properties to all commands:
 
-```sh
-quire build site
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `this.logger` | Logger | User-facing output with prefix `commands:{name}` |
+| `this.debug` | Function | Developer debugging via `DEBUG` env var |
+| `this.config` | Conf | CLI configuration store |
 
-### `clean`
+#### Using Logger vs Debug
 
-Remove build outputs.
+```javascript
+// Developer debugging - only shown when DEBUG=quire:commands:* is set
+this.debug('processing file: %s', filename)
+this.debug('options: %O', options)
 
-Note that this command is distinct from the [quire/11ty package](https://github.com/thegetty/quire/packages/11ty/package.json) script `clean`, to allow different behavoirs for Quire editors and developers.
-
-```sh
-quire clean --dry-run
+// User-facing output - always shown (unless silenced by log level)
+this.logger.info('Building PDF...')
+this.logger.warn('Deprecated option used')
+this.logger.error('Build failed: %s', error.message)
 ```
 
-### `configure` **not yet implemented**
+### File Organization
 
-Edit the Quire CLI configuration.
+For each command, you'll find up to three types of files:
 
-```sh
-quire configure
+```
+src/commands/
+├── my-command.js        # Command implementation
+├── my-command.spec.js   # Unit tests (structure, options, definitions)
+└── my-command.test.js   # Integration tests (functionality with mocked deps)
 ```
 
-### `install` **not yet implemented**
+## Testing Strategy
 
-Clone an existing Quire project from a git repository.
+The Quire CLI uses a comprehensive three-tier testing strategy to ensure reliable command functionality:
 
-```sh
-quire install <repository>
-```
+| Test Type | Pattern | Purpose | Location | Speed |
+|-----------|---------|---------|----------|-------|
+| **Unit** | `*.spec.js` | Command structure, options, definitions | `src/commands/` | Very Fast (seconds) |
+| **Integration** | `*.test.js` | Command functionality with mocked dependencies | `src/commands/` | Fast (seconds) |
+| **E2E** | `*.e2e.js` | Complete workflows with real dependencies | `test/e2e/` | Slow (minutes) |
 
-### `new`
+### Unit Tests (`*.spec.js`)
 
-Start a new Quire publication from a template project or clone an existing project from a git repository (equivalent to `install`).
+Unit tests verify the command structure and configuration without executing any logic.
 
-Running the `new` without any arguments will start an interactive prompt.
+**What they test:**
+- Command is properly defined: name, description, and version
+- Command is properly instantiated
+- Arguments and options are properly defined
+- Method existence (action, preAction)
+- No actual functionality testing
 
-```sh
-quire new
+**Example:**
+```javascript
+test('build command should have a dry-run option', (t) => {
+  const { command } = t.context
+  const dryRunOption = command.options.find((opt) => opt.flags.includes('--dry-run'))
+  t.truthy(dryRunOption)
+})
 ```
 
-To start a new Quire project using the default starter run the following command:
+### Integration Tests (`*.test.js`)
 
-```sh
-quire new <path>
-```
+Integration tests verify command functionality with all external dependencies mocked.
 
-To create a new project from a starter template
+**What they test:**
+- Command execution flow
+- Interaction with mocked dependencies
+- Option handling
+- Error scenarios
 
-```sh
-quire new <path> <starter>
-```
+Test command functionality with mocked dependencies:
+- Uses `esmock` for ES module mocking
+- Uses `memfs` for in-memory file system
+- Uses `sinon` for function stubs
 
-#### Specifying the `quire-11ty` version
+**Example:**
+```javascript
+test('build command should call eleventy CLI with default options', async (t) => {
+  const { sandbox, fs } = t.context
 
-When the `--quire` flag is used the new project will be started using the specified version of `quire-11ty`
+  const mockEleventyCli = {
+    build: sandbox.stub().resolves({ exitCode: 0 })
+  }
 
-```sh
-quire new <path> <starter> --quire <version>
-```
-
-##### Version identifiers
+  const BuildCommand = await esmock('./build.js', {
+    '#lib/11ty/index.js': {
+      cli: mockEleventyCli,
+      paths: { output: '_site' },
+      projectRoot: '/project'
+    },
+    'fs-extra': fs
+  })
 
-The `--quire` flag must be either a semantic version identifier or a npm distribution tag. For example:
+  const command = new BuildCommand()
+  await command.action({ '11ty': 'cli' }, command)
 
-```sh
-quire new ./blargh --quire 1.0.0-rc.5
+  t.true(mockEleventyCli.build.called)
+})
 ```
 
-```sh
-quire new ./blargh --quire latest
-```
+### E2E Tests (`*.e2e.js`)
 
-### `preview`
+E2E tests verify complete workflows using real dependencies.
 
-Build and server the Quire site in development mode.
+**What they test:**
+- Complete command workflows
+- Cross-platform compatibility
+- Real file system operations
+- Real external processes
+- Actual PDF/EPUB generation
 
-```sh
-quire preview --port 8080
+**Example:**
+```javascript
+test('build command should create _site directory', async (t) => {
+  await exec('quire build')
+  t.true(fs.existsSync('./_site'))
+})
 ```
 
-#### `epub` **not yet implemented**
-
-Preview the Quire publication epub in the default application.
+## Running Tests
 
 ```sh
-quire preview epub --open
-```
+# Run all tests (unit + integration + e2e)
+npm test
 
-#### `pdf` **not yet implemented**
+# Run only unit tests (fast)
+npm run test:unit
 
-Preview the Quire publication PDF in the default application.
+# Run only integration tests (fast, mocked)
+npm run test:integration
 
-```sh
-quire preview pdf --open
+# Run only E2E tests (slow, real dependencies)
+npm run test:e2e
+
+# Watch mode for development
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
 ```
 
-#### `site` **default subcommand**
+## Writing Tests
 
-Build and serve the Quire site in development mode.
+### When to Write Each Type
 
-```sh
-quire preview site
-```
+✅ **Always write `*.spec.js`** - Unit tests for every command
+✅ **Always write `*.test.js`** - Integration tests for command logic
+⚠️ **Optionally write `*.e2e.js`** - E2E tests for critical workflows
 
-### `server` **not yet implemented**
+### Integration Test Pattern
 
-Start a local web server to serve a previously built Quire site.
+```javascript
+import test from 'ava'
+import { Volume, createFsFromVolume } from 'memfs'
+import sinon from 'sinon'
+import esmock from 'esmock'
 
-```sh
-quire server --port 8080
-```
+test.beforeEach((t) => {
+  // Create sinon sandbox for mocking
+  t.context.sandbox = sinon.createSandbox()
 
-### `version` **partial implementation**
+  // Create in-memory file system
+  t.context.vol = new Volume()
+  t.context.fs = createFsFromVolume(t.context.vol)
 
-Sets the Quire version to use when running commands on the project.
+  // Setup mock directory structure
+  t.context.vol.fromJSON({
+    '/project/content/_data/config.yaml': 'title: Test Project',
+    '/project/package.json': JSON.stringify({ name: 'test-project' })
+  })
 
-```sh
-quire version 1.0.0
-```
+  t.context.projectRoot = '/project'
+})
 
-To set the quire version globally use the `--global` command flag.
+test.afterEach.always((t) => {
+  // Restore all mocks
+  t.context.sandbox.restore()
 
-```sh
-quire version 1.0.0 --global
-```
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
 
-#### `install`
+test('command should perform expected operation', async (t) => {
+  const { sandbox, fs } = t.context
 
-```sh
-quire version install <version>
-```
+  // Mock dependencies
+  const mockDependency = sandbox.stub().resolves()
 
-To reinstall a `quire-11ty` version run
+  // Use esmock to load command with mocked dependencies
+  const MyCommand = await esmock('./mycommand.js', {
+    '#lib/dependency/index.js': mockDependency,
+    'fs-extra': fs
+  })
 
-```sh
-quire version install <version> --force
+  const command = new MyCommand()
+  await command.action({}, command)
+
+  t.true(mockDependency.called)
+})
 ```
 
-#### `list`
+## Testing Dependencies
 
-List installed versions of `quire-11ty`
+All testing dependencies are managed in [package.json](../../package.json):
 
-```sh
-quire version list
-```
+- **ava** - Test runner with ES module support
+- **esmock** - ES module mocking for imports
+- **memfs** - In-memory file system for fast, isolated tests
+- **sinon** - Stubbing and mocking for function calls
 
-#### `prune`
+## Test Quality Standards
 
-Remove outdated versions of `quire-11ty`
+- Each command must have integration test scenarios
+- Critical workflows must have end-to-end tests
+- All error paths must be tested
+- Test execution time should be < 5 minutes total (with mocking: < 30 seconds)
+- Code coverage target: 80% for integration paths
 
-```sh
-quire version prune
-```
+## Creating a New Command
 
-#### `remove` (alias `uninstall`)
+1. **Create the command file** (`src/commands/my-command.js`)
+   - Extend the `Command` class
+   - Define static `definition` object
+   - Implement `action()` method
 
-```sh
-quire version remove <version>
-```
+2. **Create integration tests** (`src/commands/my-command.test.js`)
+   - Test main functionality with mocked dependencies
+   - Test error handling
+   - Test option passing
 
-```sh
-quire version uninstall <version>
-```
+3. **Create unit tests** (optional, `src/commands/my-command.spec.js`)
+   - Validate command structure and configuration
+
+4. **Create e2e tests** (optional, `test/e2e/my-command.e2e.js`)
+   - Test critical workflows with real dependencies

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'))
+})