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

package/src/Command.js

@@ -1,4 +1,6 @@
 import config from '#src/lib/conf/config.js'
+import createLogger from '#lib/logger/index.js'
+import createDebug from '#debug'
 
 /**
  * Command
@@ -13,10 +15,13 @@ export default class Command {
 
   /**
    * @typedef CommandDefinition
-   * @property {String} name
-   * @property {String} alias
-   * @property {Array<String>} aliases
-   * @property {String} descriptions
+   * @property {String} name - Command name used to invoke it
+   * @property {String} alias - Single alias for the command
+   * @property {Array<String>} aliases - Multiple aliases for the command
+   * @property {String} description - Full description shown in command's own help
+   * @property {String} summary - One-line summary shown in parent help listing
+   * @property {String} [docsLink] - Path appended to docs base URL (e.g., 'quire-commands/#output-files')
+   * @property {String} [helpText] - Custom help text shown after built-in help (examples, notes)
    * @property {Array<CommandArgument>} args
    * @property {Array<CommandOption>} options
    * @property {String} version
@@ -32,12 +37,24 @@ export default class Command {
    * @param {CommandDefinition}  definition  The definition
    */
   constructor(definition) {
-    if (this.constructor.prototype === Command) {
+    if (this.constructor === Command) {
       throw new Error('Command is an *abstract* class')
     }
 
     this.config = config // quire-cli configuration
 
+    /**
+     * Command-specific debug instance for internal debugging
+     * Enable via: DEBUG=quire:commands:name or DEBUG=quire:commands:*
+     */
+    this.debug = createDebug(`commands:${definition.name}`)
+
+    /**
+     * Command-specific logger with prefix including command name
+     * Output format: [quire] LEVEL commands:name message
+     */
+    this.logger = createLogger(`commands:${definition.name}`)
+
     /**
      * Merge and deduplicate command definition alias and aliases
      * Nota bene: Only the first command alias is displayed in the help.
@@ -48,6 +65,9 @@ export default class Command {
     this.name = definition.name
     this.aliases = definition.aliases
     this.description = definition.description
+    this.summary = definition.summary
+    this.docsLink = definition.docsLink
+    this.helpText = definition.helpText
     this.args = definition.args
     this.options = definition.options
     this.version = definition.version
@@ -55,7 +75,7 @@ export default class Command {
   }
 
   definition() {
-    return this.prototype.definition
+    return this.constructor.definition
   }
 
   action() {

package/src/Command.spec.js

@@ -0,0 +1,99 @@
+import Command from './Command.js'
+import test from 'ava'
+
+/**
+ * Command Base Class Unit Tests
+ *
+ * Tests the abstract Command base class API contract.
+ * These tests verify the class cannot be instantiated directly
+ * and that the base methods behave correctly.
+ */
+
+test('Command cannot be instantiated directly', (t) => {
+  const error = t.throws(() => {
+    new Command({ name: 'test', description: 'test command' })
+  })
+
+  t.truthy(error)
+  t.regex(error.message, /abstract/i, 'error message should mention abstract')
+})
+
+test('Command.action() throws not-implemented error', (t) => {
+  // Create a minimal subclass that does not override action
+  class TestCommand extends Command {
+    constructor() {
+      super({ name: 'test', description: 'test command' })
+    }
+  }
+
+  const command = new TestCommand()
+  const error = t.throws(() => command.action())
+
+  t.truthy(error)
+  t.regex(error.message, /not been implemented/i, 'error message should indicate not implemented')
+  t.regex(error.message, /test/i, 'error message should include the command name')
+})
+
+test('subclass can override action without error', (t) => {
+  class TestCommand extends Command {
+    constructor() {
+      super({ name: 'test', description: 'test command' })
+    }
+
+    action() {
+      return 'action executed'
+    }
+  }
+
+  const command = new TestCommand()
+  const result = command.action()
+
+  t.is(result, 'action executed')
+})
+
+test('Command constructor sets properties from definition', (t) => {
+  const definition = {
+    name: 'test',
+    description: 'A test command',
+    summary: 'test summary',
+    aliases: ['t', 'tst'],
+    args: [['<input>', 'input file']],
+    options: [['--verbose', 'enable verbose output']],
+    version: '1.0.0',
+    hidden: true,
+  }
+
+  class TestCommand extends Command {
+    constructor() {
+      super(definition)
+    }
+
+    action() {}
+  }
+
+  const command = new TestCommand()
+
+  t.is(command.name, 'test')
+  t.is(command.description, 'A test command')
+  t.is(command.summary, 'test summary')
+  t.deepEqual(command.aliases, ['t', 'tst'])
+  t.deepEqual(command.args, [['<input>', 'input file']])
+  t.deepEqual(command.options, [['--verbose', 'enable verbose output']])
+  t.is(command.version, '1.0.0')
+  t.is(command.hidden, true)
+})
+
+test('Command constructor injects shared configuration', (t) => {
+  class TestCommand extends Command {
+    constructor() {
+      super({ name: 'test', description: 'test command' })
+    }
+
+    action() {}
+  }
+
+  const command = new TestCommand()
+
+  t.truthy(command.config, 'config should be injected')
+  t.is(typeof command.config.get, 'function', 'config should have get method')
+})

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