@thegetty/quire-cli 1.0.0-rc.45 → 1.0.0-rc.47

package/src/commands/README.md

@@ -1,292 +1,201 @@
-# Quire CLI Commands
+## Quire CLI Commands
 
-This directory contains the Quire CLI command implementations and their corresponding tests.
+### `build`
 
-## Command Class Pattern
+Build Quire publication outputs.
 
-All Quire CLI commands extend the base `Command` class and follow a consistent pattern:
+```sh
+quire build
+```
 
-### Command Structure
+#### `epub`
 
-```javascript
-import Command from '#src/Command.js'
+Build Quire publication EPUB format.
 
-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']
-    ]
-  }
+```sh
+quire build epub
+```
 
-  constructor() {
-    super(MyCommand.definition)
-  }
+#### `info`
 
-  async action(args, options, command) {
-    // Use this.debug for developer debugging (controlled by DEBUG env var)
-    this.debug('called with options %O', options)
+List `quire-11ty`, `quire-cli`, and starter package versions; use the `--debug` option to include node, npm, and os versions.
 
-    // Use this.logger for user-facing output
-    this.logger.info('Starting operation...')
+```sh
+quire build info
+```
 
-    // Command implementation
-  }
+#### `pdf`
 
-  preAction(command) {
-    // Optional: runs before action()
-  }
+Build Quire publication PDF format.
 
-  postAction(command) {
-    // Optional: runs after action()
-  }
-}
+```sh
+quire build pdf
 ```
 
-### Inherited Properties
+#### `site`
 
-The base `Command` class provides these properties to all commands:
+Build Quire publication HTML format.
 
-| 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 |
+```sh
+quire build site
+```
 
-#### Using Logger vs Debug
+### `clean`
 
-```javascript
-// Developer debugging - only shown when DEBUG=quire:commands:* is set
-this.debug('processing file: %s', filename)
-this.debug('options: %O', options)
+Remove build outputs.
 
-// 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)
+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
 ```
 
-### File Organization
+### `configure` **not yet implemented**
 
-For each command, you'll find up to three types of files:
+Edit the Quire CLI configuration.
 
-```
-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)
+```sh
+quire configure
 ```
 
-## Testing Strategy
+### `install` **not yet implemented**
 
-The Quire CLI uses a comprehensive three-tier testing strategy to ensure reliable command functionality:
+Clone an existing Quire project from a git 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) |
+```sh
+quire install <repository>
+```
 
-### Unit Tests (`*.spec.js`)
+### `new`
 
-Unit tests verify the command structure and configuration without executing any logic.
+Start a new Quire publication from a template project or clone an existing project from a git repository (equivalent to `install`).
 
-**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
+Running the `new` without any arguments will start an interactive prompt.
 
-**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)
-})
+```sh
+quire new
 ```
 
-### Integration Tests (`*.test.js`)
-
-Integration tests verify command functionality with all external dependencies mocked.
-
-**What they test:**
-- Command execution flow
-- Interaction with mocked dependencies
-- Option handling
-- Error scenarios
+To start a new Quire project using the default starter run the following command:
 
-Test command functionality with mocked dependencies:
-- Uses `esmock` for ES module mocking
-- Uses `memfs` for in-memory file system
-- Uses `sinon` for function stubs
+```sh
+quire new <path>
+```
 
-**Example:**
-```javascript
-test('build command should call eleventy CLI with default options', async (t) => {
-  const { sandbox, fs } = t.context
+To create a new project from a starter template
 
-  const mockEleventyCli = {
-    build: sandbox.stub().resolves({ exitCode: 0 })
-  }
+```sh
+quire new <path> <starter>
+```
 
-  const BuildCommand = await esmock('./build.js', {
-    '#lib/11ty/index.js': {
-      cli: mockEleventyCli,
-      paths: { output: '_site' },
-      projectRoot: '/project'
-    },
-    'fs-extra': fs
-  })
+#### Specifying the `quire-11ty` version
 
-  const command = new BuildCommand()
-  await command.action({ '11ty': 'cli' }, command)
+When the `--quire` flag is used the new project will be started using the specified version of `quire-11ty`
 
-  t.true(mockEleventyCli.build.called)
-})
+```sh
+quire new <path> <starter> --quire <version>
 ```
 
-### E2E Tests (`*.e2e.js`)
-
-E2E tests verify complete workflows using real dependencies.
+##### Version identifiers
 
-**What they test:**
-- Complete command workflows
-- Cross-platform compatibility
-- Real file system operations
-- Real external processes
-- Actual PDF/EPUB generation
+The `--quire` flag must be either a semantic version identifier or a npm distribution tag. For example:
 
-**Example:**
-```javascript
-test('build command should create _site directory', async (t) => {
-  await exec('quire build')
-  t.true(fs.existsSync('./_site'))
-})
+```sh
+quire new ./blargh --quire 1.0.0-rc.5
 ```
 
-## Running Tests
-
 ```sh
-# Run all tests (unit + integration + e2e)
-npm test
+quire new ./blargh --quire latest
+```
 
-# Run only unit tests (fast)
-npm run test:unit
+### `preview`
 
-# Run only integration tests (fast, mocked)
-npm run test:integration
+Build and server the Quire site in development mode.
 
-# Run only E2E tests (slow, real dependencies)
-npm run test:e2e
+```sh
+quire preview --port 8080
+```
 
-# Watch mode for development
-npm run test:watch
+#### `epub` **not yet implemented**
 
-# Generate coverage report
-npm run test:coverage
+Preview the Quire publication epub in the default application.
+
+```sh
+quire preview epub --open
 ```
 
-## Writing Tests
+#### `pdf` **not yet implemented**
 
-### When to Write Each Type
+Preview the Quire publication PDF in the default application.
 
-✅ **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
+```sh
+quire preview pdf --open
+```
 
-### Integration Test Pattern
+#### `site` **default subcommand**
 
-```javascript
-import test from 'ava'
-import { Volume, createFsFromVolume } from 'memfs'
-import sinon from 'sinon'
-import esmock from 'esmock'
+Build and serve the Quire site in development mode.
 
-test.beforeEach((t) => {
-  // Create sinon sandbox for mocking
-  t.context.sandbox = sinon.createSandbox()
+```sh
+quire preview site
+```
 
-  // Create in-memory file system
-  t.context.vol = new Volume()
-  t.context.fs = createFsFromVolume(t.context.vol)
+### `server` **not yet implemented**
 
-  // Setup mock directory structure
-  t.context.vol.fromJSON({
-    '/project/content/_data/config.yaml': 'title: Test Project',
-    '/project/package.json': JSON.stringify({ name: 'test-project' })
-  })
+Start a local web server to serve a previously built Quire site.
 
-  t.context.projectRoot = '/project'
-})
+```sh
+quire server --port 8080
+```
 
-test.afterEach.always((t) => {
-  // Restore all mocks
-  t.context.sandbox.restore()
+### `version` **partial implementation**
 
-  // Clear in-memory file system
-  t.context.vol.reset()
-})
+Sets the Quire version to use when running commands on the project.
 
-test('command should perform expected operation', async (t) => {
-  const { sandbox, fs } = t.context
+```sh
+quire version 1.0.0
+```
 
-  // Mock dependencies
-  const mockDependency = sandbox.stub().resolves()
+To set the quire version globally use the `--global` command flag.
 
-  // 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 1.0.0 --global
+```
 
-  const command = new MyCommand()
-  await command.action({}, command)
+#### `install`
 
-  t.true(mockDependency.called)
-})
+```sh
+quire version install <version>
 ```
 
-## Testing Dependencies
+To reinstall a `quire-11ty` version run
 
-All testing dependencies are managed in [package.json](../../package.json):
+```sh
+quire version install <version> --force
+```
 
-- **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
+#### `list`
 
-## Test Quality Standards
+List installed 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 list
+```
 
-## Creating a New Command
+#### `prune`
 
-1. **Create the command file** (`src/commands/my-command.js`)
-   - Extend the `Command` class
-   - Define static `definition` object
-   - Implement `action()` method
+Remove outdated versions of `quire-11ty`
 
-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 prune
+```
+
+#### `remove` (alias `uninstall`)
 
-3. **Create unit tests** (optional, `src/commands/my-command.spec.js`)
-   - Validate command structure and configuration
+```sh
+quire version remove <version>
+```
 
-4. **Create e2e tests** (optional, `test/e2e/my-command.e2e.js`)
-   - Test critical workflows with real dependencies
+```sh
+quire version uninstall <version>
+```

package/src/commands/build.js

@@ -1,11 +1,6 @@
 import Command from '#src/Command.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 { api, cli, paths, projectRoot  } from '#lib/11ty/index.js'
 import { clean } from '#helpers/clean.js'
-import { recordStatus } from '#lib/conf/build-status.js'
-import reporter from '#lib/reporter/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -17,59 +12,56 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class BuildCommand extends Command {
-  static definition = withOutputModes({
+  static definition = {
     name: 'build',
     description: 'Generate publication outputs',
-    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',
+    summary: 'run build',
+    version: '1.0.0',
+    args: [
+      // [
+      //   '[formats...]', 'output formats',
+      //   {
+      //     choices: ['pdf', 'epub'],
+      //   }
+      // ],
+    ],
     options: [
       [ '-d', '--dry-run', 'run build without writing files' ],
-      [ '--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(),
+      [ '-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' ],
     ],
-  })
+  }
 
   constructor() {
     super(BuildCommand.definition)
   }
 
-  async action(options, command) {
-    this.debug('called with options %O', options)
-
-    // Configure reporter for this command
-    reporter.configure({ quiet: options.quiet, verbose: options.verbose })
+  action(options, command) {
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
 
-    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)
-      }
-      recordStatus(paths.getProjectRoot(), 'build', 'ok')
-    } catch (error) {
-      recordStatus(paths.getProjectRoot(), 'build', 'failed')
-      throw error
+    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)
     }
   }
 
-  preAction(thisCommand, actionCommand) {
-    testcwd(thisCommand)
+  preAction(command) {
+    testcwd(command)
 
-    const options = thisCommand.opts()
-    this.debug('pre-action with options %O', options)
-    clean(paths.getProjectRoot(), paths.toObject(), options)
+    const options = command.opts()
+    if (options.debug) {
+      console.debug('[CLI] Calling \'build\' command pre-action with options', options)
+    }
+    clean(projectRoot, paths, options)
   }
 }

package/src/commands/clean.js

@@ -1,8 +1,6 @@
 import Command from '#src/Command.js'
-import { withOutputModes } from '#lib/commander/index.js'
 import { clean } from '#helpers/clean.js'
-import { clearStatus } from '#lib/conf/build-status.js'
-import paths from '#lib/project/index.js'
+import { paths, projectRoot  } from '#lib/11ty/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -17,51 +15,39 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class CleanCommand extends Command {
-  static definition = withOutputModes({
+  static definition = {
     name: 'clean',
     description: '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
-`,
+    summary: 'remove build outputs',
     version: '1.0.0',
+    args: [],
     options: [
-      [ '-d, --dry-run', 'show paths to be cleaned without deleting files' ],
-      [ '--dryrun', 'alias for --dry-run', { hidden: true, implies: { dryRun: true } } ],
-      [ '--status', 'also clear stored build status for this project' ],
+      [ '-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' ],
     ],
-  })
+  }
 
   constructor() {
     super(CleanCommand.definition)
   }
 
   async action(options, command) {
-    this.debug('called with options %O', options)
-
-    const projectRoot = paths.getProjectRoot()
-    const deletedPaths = await clean(projectRoot, paths.toObject(), options)
-
-    if (options.status && !options.dryRun) {
-      clearStatus(projectRoot)
-      this.logger.info('Cleared build status for this project')
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
     }
 
-    if (!deletedPaths || !deletedPaths.length) {
-      if (!options.status) this.logger.info('No files to delete')
-      return
-    }
+    const deletedPaths = await clean(projectRoot, paths, options)
+
+    const message = deletedPaths && deletedPaths.length
+      ? `the following files ${options.dryRun ? 'will be' : 'have been'} deleted:`
+      : 'no files to delete'
 
-    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}`)
+    console.debug(`[CLI] ${message}\n${deletedPaths.join('\n')}`)
   }
 
-  preAction(thisCommand, actionCommand) {
-    testcwd(thisCommand)
+  preAction(command) {
+    testcwd(command)
   }
 }

package/src/commands/conf.js

@@ -0,0 +1,43 @@
+import Command from '#src/Command.js'
+
+/**
+ * Quire CLI `conf` Command
+ *
+ * @class      ConfCommand
+ * @extends    {Command}
+ */
+export default class ConfCommand extends Command {
+  static definition = {
+    name: 'conf',
+    aliases: ['config', 'configure'],
+    description: 'Manage the Quire CLI configuration.',
+    summary: 'read/write quire-cli configuration options',
+    version: '1.0.0',
+    options: [
+      [ '--debug', 'run command in debug mode' ],
+    ],
+  }
+
+  constructor() {
+    super(ConfCommand.definition)
+  }
+
+  /**
+   * @param      {Object}  options
+   * @return     {Promise}
+   */
+  async action(key, value, options = {}) {
+    if (options.debug) {
+      console.info('Command \'%s\' called with options %o', this.name(), options)
+    }
+
+    // this.outputHelp()
+
+    console.info('quire-cli configuration %s', this.config.path)
+
+    for (const [ key, value ] of Object.entries(this.config.store)) {
+      if (key.startsWith('__internal__') && !options.debug) continue
+      console.info('%s: %O', key, value)
+    }
+  }
+}