@thegetty/quire-cli 1.0.0-rc.44 → 1.0.0-rc.46

package/src/commands/preview.js

@@ -1,8 +1,5 @@
 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 reporter from '#lib/reporter/index.js'
+import { api, cli, paths, projectRoot  } from '#lib/11ty/index.js'
 import testcwd from '#helpers/test-cwd.js'
 
 /**
@@ -14,48 +11,50 @@ import testcwd from '#helpers/test-cwd.js'
  * @extends    {Command}
  */
 export default class PreviewCommand extends Command {
-  static definition = withOutputModes({
+  static definition = {
     name: 'preview',
     description: 'Run the development server and watch on file changes',
-    summary: 'start local preview server',
-    docsLink: 'quire-commands/#start-and-preview-projects',
-    helpText: `
-Examples:
-  quire preview                  Start preview server on default port
-  quire preview --port 3000      Run on custom port
-  quire preview --open           Start server and open in browser
-  quire preview --verbose        Start with detailed progress
-`,
-    version: '1.1.0',
+    summary: 'run the development server',
+    version: '1.0.0',
+    args: [
+      // [
+      //   '[formats...]', 'output formats',
+      //   {
+      //     choices: ['pdf', 'epub'],
+      //   }
+      // ],
+    ],
     options: [
-      [ '-p, --port <port>', 'configure development server port', 8080 ],
-      [ '--open', 'open in default browser when server starts' ],
-      // 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(),
+      [ '-p', '--port <port>', 'configure development server port', 8080 ],
+      [ '-q', '--quiet', 'run preview in silent mode' ],
+      [ '-v', '--verbose', 'run preview with verbose console messages' ],
+      [
+        '--11ty <module>', 'use the specified 11ty module', 'cli',
+        // { choices: ['api', 'cli'], default: 'cli' }
+      ],
+      [ '--debug', 'run preview with debug output to console' ],
     ],
-  })
+  }
 
   constructor() {
     super(PreviewCommand.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 })
+    if (options.debug) {
+      console.debug('[CLI] Command \'%s\' called with arguments [%o] and options %o', this.name(), options)
+    }
 
-    if (options['11ty'] === 'api') {
-      this.debug('running eleventy using lib/11ty api')
-      await api.serve(options)
+    if (options['11ty'] === 'cli') {
+      console.debug('[CLI] running eleventy using lib/11ty cli')
+      cli.serve(options)
     } else {
-      this.debug('running eleventy using lib/11ty cli')
-      await cli.serve(options)
+      console.debug('[CLI] running eleventy using lib/11ty api')
+      api.serve(options)
     }
   }
 
-  preAction(thisCommand, actionCommand) {
-    testcwd(thisCommand)
+  preAction(command) {
+    testcwd(command)
   }
 }

package/src/commands/validate.js

@@ -1,108 +1,64 @@
 import Command from '#src/Command.js'
-import { withOutputModes } from '#lib/commander/index.js'
 import { YAMLException } from 'js-yaml'
 import YamlValidationError from '../errors/validation/yaml-validation-error.js'
 import fs from 'fs-extra'
 import path from 'node:path'
-import paths from '#lib/project/index.js'
+import { projectRoot  } from '#lib/11ty/index.js'
 import testcwd from '../helpers/test-cwd.js'
 import yamlValidation from '../validators/validate-yaml.js'
-import { ValidationError } from '#src/errors/index.js'
+
 
 /**
  * Quire CLI `validate` Command
- *
+ *  
  * @class     ValidateCommand
  * @extends   {Command}
  */
 export default class ValidateCommand extends Command {
-  static definition = withOutputModes({
+  static definition = {
     name: 'validate',
     description: 'Validate configuration files',
-    summary: 'check YAML files for errors',
-    docsLink: 'quire-commands/#get-help',
-    helpText: `
-Examples:
-  quire validate               Check YAML syntax in content/_data/
-  quire validate --verbose     Validate with detailed file listing
-  quire validate --json        Output validation results as JSON
-
-Validates YAML files in content/_data/ directory.
-`,
+    summary: 'run validation',
     version: '1.0.0',
     options: [
-      ['--json', 'output validation results as JSON'],
+      [ '--debug', 'run validate with debug output to console' ],
     ],
-  })
+  }
 
   constructor() {
     super(ValidateCommand.definition)
   }
 
   action(options, command){
-    this.debug('called with options %O', options)
-
-    const dataPath = path.join(paths.getProjectRoot(), 'content', '_data')
+    if(options.debug) {
+      console.debug('[CLI] Command \'%s\' called with options %o', this.name(), options)
+    }
+    
+    const dataPath = path.join(projectRoot, 'content', '_data')
     const files = fs.readdirSync(dataPath)
       .filter(file => file.endsWith('.yaml') || file.endsWith('.yml'))
       .map(file => path.join(dataPath, file)
       )
 
-    const results = []
-    if (!options.json) {
-      this.logger.info('Validating YAML files..')
-    }
+    let errorList = []
+    console.log('Validating YAML files..')
 
     for (const file of files) {
       try {
         yamlValidation(file)
-        results.push({ file, status: 'passed' })
       } catch (error){
-        results.push({ file, status: 'failed', error: error.reason })
+        errorList.push(error)
       }
     }
 
-    const errors = results.filter((r) => r.status === 'failed')
-
-    if (options.json) {
-      const output = {
-        summary: {
-          files: results.length,
-          passed: results.length - errors.length,
-          failed: errors.length,
-        },
-        files: results,
-      }
-      console.log(JSON.stringify(output, null, 2))
-
-      // Still throw so exit code reflects failure
-      if (errors.length > 0) {
-        throw new ValidationError(
-          `Validation failed with ${errors.length} error(s)`,
-          {
-            code: 'VALIDATION_FAILED',
-            suggestion: 'Fix the errors listed above and run validation again'
-          }
-        )
-      }
-      return
-    }
-
-    if (errors.length > 0) {
-      errors.forEach((r) => { this.logger.error(`${r.error}`) })
-      throw new ValidationError(
-        `Validation failed with ${errors.length} error(s)`,
-        {
-          code: 'VALIDATION_FAILED',
-          suggestion: 'Fix the errors listed above and run validation again'
-        }
-      )
+    if(errorList.length > 0) {
+      errorList.forEach(err => { console.error(`${err.reason}`) })
     } else {
-      this.logger.info('Validation complete.')
+      console.log('Validation complete.')
     }
   }
 
-  preAction(thisCommand, actionCommand) {
-    testcwd(thisCommand)
+  preAction(options, command) {
+    testcwd(command)
   }
 }

package/src/commands/version.js

@@ -0,0 +1,43 @@
+import Command from '#src/Command.js'
+import { paths, projectRoot  } from '#lib/11ty/index.js'
+import * as quire from '#lib/quire/index.js'
+import testcwd from '#helpers/test-cwd.js'
+
+/**
+ * Quire CLI `version` Command
+ *
+ * Running `quire version` sets the `quire-11ty` version for a project.
+ * The version is written to a `.quire` file in the project directory
+ * or to the `quire-cli` package `.quire` when the `global` flag is used.
+ *
+ * @class      VersionCommand
+ * @extends    {Command}
+ */
+export default class VersionCommand extends Command {
+  static definition = {
+    name: 'version',
+    description: 'Sets the Quire version to use when running commands on the project.',
+    summary: 'set the @thegetty/quire-11ty version',
+    version: '1.0.0',
+    args: [
+      [ '<version>', 'the local quire version to use' ],
+    ],
+    options: [
+      // [ '-g', '--global', 'set the quire version globally' ],
+    ],
+  }
+
+  constructor() {
+    super(VersionCommand.definition)
+  }
+
+  action(args, options = {}) {
+    if (options.debug) {
+      console.info('Command \'%s\' called with options %o', this.name, options)
+    }
+  }
+
+  preAction(command) {
+    testcwd(command)
+  }
+}

package/src/errors/validation/validation-error.js

@@ -1,22 +1,13 @@
-import QuireError from '../quire-error.js'
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * Base validation error class (exit code: 4)
- *
- * Used for YAML validation, schema violations, and configuration errors.
- * Maintains backward compatibility with existing properties (filePath, reason, code).
- */
-export default class ValidationError extends QuireError {
-  constructor(message, { filePath, reason, code, suggestion, docsUrl: docsUrlOverride } = {}) {
-    super(message, {
-      code,
-      exitCode: 4,
-      filePath,
-      suggestion: suggestion || (reason ? `Fix: ${reason}` : undefined),
-      docsUrl: docsUrlOverride || docsUrl('troubleshooting')
-    })
-    // Maintain backward compatibility
+export default class ValidationError extends Error {
+  constructor(message, {filePath, reason, code} = {}) {
+    super(message)
+    this.name = this.constructor.name
+    this.filePath = filePath
     this.reason = reason
+    this.code = code
+
+    if ('captureStackTrace' in Error) {
+      Error.captureStackTrace(this, this.constructor)
+    }
   }
-}
+}

package/src/helpers/clean.js

@@ -36,7 +36,7 @@ export async function clean (projectRoot, paths, options = {}) {
   const deletedPaths = await deleteAsync(pathsToClean, {
     dryRun: options.dryRun,
     force: true,
-    onProgress: options.verbose && progressLogger,
+    onProgress: (options.progress || options.verbose) && progressLogger,
   })
 
   return deletedPaths

package/src/helpers/is-quire.js

@@ -0,0 +1,31 @@
+/**
+ * A helper module to test if a directory is a Quire project root
+ * @module is-quire
+ */
+import fs from 'node:fs'
+
+const QUIRE_DOT_FILES = Object.freeze([
+  '.eleventy.js',
+  '.quire',
+  '.quire-11ty',
+  '.quire-version',
+  'eleventy.config.js',
+])
+
+/**
+ * Test if a directory is a Quire project root
+ *
+ * Nota bene: `dirpath` must be to the Quire project root to positively confirm
+ * a directory is a Quire project, testing a Quire project subdirectory will
+ * return falsely negative result.
+ *
+ * @todo refactor this to throw an Error NOTQUIRE
+ *
+ * @param    {String}   dirpath   path to a local directory
+ * @return   {Promise}
+ */
+export default function (dirpath) {
+  return fs.readdirSync(dirpath)
+    .find((entry) => QUIRE_DOT_FILES.includes(entry))
+}
+

package/src/helpers/test-cwd.js

@@ -1,18 +1,19 @@
 /**
  * A helper module to test the current working directory
- * @module test-cwd
+ * @module test-csd
  */
-import { detect as isQuire } from '#lib/project/index.js'
-import { NotInProjectError } from '#src/errors/index.js'
+import isQuire from '#helpers/is-quire.js'
 
 /**
  * Test current working directory is a Quire project directory
  *
  * @param  {Command}  command  the command from which testcwd was called
- * @throws {NotInProjectError} if not in a Quire project directory
  */
 export default (command) => {
+  const message = `[CLI] ${ command ? command.name() : '' } command must be run while in a Quire project directory. Use 'cd' to navigate to your project directory and re-run the 'quire ${ command ? command.name() : '' }' command.`
+
   if (!isQuire(process.cwd())) {
-    throw new NotInProjectError(command?.name() || '')
+    console.error(message)
+    process.exit(1)
   }
 }

package/src/helpers/which.js

@@ -3,25 +3,19 @@
  * @module which
  */
 import which from 'which'
-import { ToolNotFoundError } from '#src/errors/index.js'
 
 /**
  * A simple wrapper around the `which` utility
  * to find the first instance of an executable in the shell environment PATH
  *
  * @param  {String}  executable  shell executable to find
- * @param  {Object}  [toolInfo]  optional metadata for error messages
- * @param  {String}  [toolInfo.displayName]  human-readable tool name
- * @param  {String}  [toolInfo.installUrl]  URL where tool can be downloaded
- * @param  {String}  [toolInfo.docsUrl]  Quire docs URL for this tool
- * @param  {String}  [toolInfo.fallback]  alternative suggestion
- * @throws {ToolNotFoundError} When executable is not found in PATH
- * @returns {String} Path to the executable
  */
-export default (executable, toolInfo) => {
+export default (executable) => {
   const result = which.sync(executable, { nothrow: true })
   if (!result) {
-    throw new ToolNotFoundError(executable, toolInfo)
+    console.error(`Unable to locate executable '${executable}'\n
+      Ensure that the '${executable}' executable is installed and available in the shell environment PATH.
+    `)
   }
   return result
 }

package/src/lib/11ty/README.md

@@ -1,151 +1,35 @@
 ## CLI 11ty Module
 
-The `lib/11ty` module is a façade for interacting with Eleventy, the static site generator for Quire projects. It follows the singleton pattern established by `lib/npm` and `lib/git`.
+The `quire-cli/lib/11ty` module is a façade for interacting with Eleventy, the static site generator for Quire projects.
 
-### Usage
+### 11ty/API module
 
-**Recommended: Default export**
+The `api` module allows the Quire CLI to programmatical configure an instance of Eleventy on which it can call methods.
 
-```javascript
-import eleventy from '#lib/11ty/index.js'
+See [Eleventy Documentation: Programmatic API](https://www.11ty.dev/docs/programmatic/)
 
-// Run production build
-await eleventy.build({ debug: true })
+### 11ty/CLI module
 
-// Run development server
-await eleventy.serve({ port: 8080 })
+The `cli` module is a wrapper around the Eleventy CLI to run `@11ty/eleventy` commands.
 
-// Access paths through the façade
-const outputDir = eleventy.paths.getOutputDir()
-```
+See [Eleventy Documentation: Command Line Usage](https://www.11ty.dev/docs/usage/#command-line-usage)
 
-**Path-only consumers**
+### Paths module
 
-```javascript
-import { paths } from '#lib/11ty/index.js'
+The `paths` module returns paths for a Quire project to configure the Eleventy instance:
 
-const projectRoot = paths.getProjectRoot()
-const outputDir = paths.getOutputDir()
-```
+- _absolute_ path to the [Eleventy configuration](https://www.11ty.dev/docs/config/) file
+- _relative_ path *from* the `quire-11ty` source *to* the `input` and `output` directories for the project
+- _relative_ path *from* the project `input` *to* the Eleventy `includes` and `layouts` directories
 
-**Legacy usage (deprecated)**
 
-```javascript
-// Deprecated - use default export instead
-import { api, cli, paths } from '#lib/11ty/index.js'
-await api.build(options)
-```
+Set environment variables for paths relative to eleventy `input` dir,
+    * allowing a project agnostic `quire-11ty` eleventy configuration file.
+    * Nota bene: environment variables read into the eleventy configuration
+    * file _must_ be set before the eleventy configuration file is parsed.
 
-### Test Mocking
+`Eleventy` does not expose an API to set the relative `includes` and `layouts` paths on the instance. In order to decouple the Eleventy configuration file from a specific project and its path on the system the exported `paths` are used by the `api` and `cli` modules to set environment variables that can be used in the `.eleventy.js` configuration.
 
-```javascript
-const mockEleventy = {
-  build: sandbox.stub().resolves(),
-  serve: sandbox.stub().resolves(),
-  paths: {
-    getProjectRoot: () => '/project',
-    getOutputDir: () => '_site'
-  }
-}
-const MyCommand = await esmock('./mycommand.js', {
-  '#lib/11ty/index.js': { default: mockEleventy }
-})
-```
+These environment variables **must be set before** the `Eleventy` instance is created and the `.eleventy.js` configuration is parsed.
 
-### Quire11ty Façade
-
-The `Quire11ty` class provides abstracted Eleventy operations:
-
-| Method | Description |
-|--------|-------------|
-| `build(options)` | Run Eleventy production build |
-| `serve(options)` | Run Eleventy development server |
-| `paths` | Access to `Paths` instance for path resolution |
-
-**Build options:**
-- `debug` - Enable debug output
-- `dryRun` - Perform dry run without writing files
-- `quiet` - Suppress output
-
-**Serve options:**
-- `debug` - Enable debug output
-- `port` - Server port
-- `quiet` - Suppress output
-
-### Paths Module
-
-The `paths` property provides a `Paths` instance with accessor methods for Eleventy path configuration. Values are computed on access to reflect the current working directory state.
-
-#### Naming Convention
-
-Method names encode the return type:
-
-| Suffix | Returns |
-|--------|---------|
-| `Path` or `Root` | Absolute filesystem path |
-| `Dir` | Relative directory name |
-
-#### API Reference
-
-**Absolute paths:**
-
-| Method | Description |
-|--------|-------------|
-| `getConfigPath()` | Absolute path to `.eleventy.js` config |
-| `getEleventyRoot()` | Absolute path to Eleventy root directory |
-| `getInputPath()` | Absolute path to content input directory |
-| `getLibQuirePath()` | Absolute path to quire-11ty installation |
-| `getProjectRoot()` | Absolute path to project root (`process.cwd()`) |
-
-**Relative directories:**
-
-| Method | Description |
-|--------|-------------|
-| `getDataDir()` | Data directory relative to input (`_computed`) |
-| `getEpubDir()` | EPUB output directory relative to Eleventy root |
-| `getIncludesDir()` | Includes directory relative to input |
-| `getInputDir()` | Input directory relative to Eleventy root |
-| `getLayoutsDir()` | Layouts directory relative to input |
-| `getOutputDir()` | Output directory relative to Eleventy root (`_site`) |
-| `getPublicDir()` | Public assets directory (`./public`) |
-
-**Utility:**
-
-| Method | Description |
-|--------|-------------|
-| `toObject()` | Returns all paths as an object (for logging/debugging) |
-
-### Environment Variables
-
-The façade sets environment variables before creating the Eleventy instance:
-
-| Variable | Source |
-|----------|--------|
-| `ELEVENTY_DATA` | `paths.getDataDir()` |
-| `ELEVENTY_ENV` | `'production'` or `'development'` |
-| `ELEVENTY_INCLUDES` | `paths.getIncludesDir()` |
-| `ELEVENTY_LAYOUTS` | `paths.getLayoutsDir()` |
-
-These environment variables **must be set before** the Eleventy instance is created and the `.eleventy.js` configuration is parsed.
-
-### Design Notes
-
-**Why a unified façade?**
-
-The façade pattern provides:
-1. **Single point of control** - Eleventy configuration in one place
-2. **Consistent logging** - All operations use `[CLI:lib/11ty]` prefix
-3. **Easy mocking** - Single object to mock in tests
-4. **Implementation hiding** - Consumers don't need to know if we use API or CLI
-
-**Why programmatic API instead of CLI subprocess?**
-
-The façade uses Eleventy's programmatic API internally rather than spawning a subprocess:
-1. **Event access** - Direct access to `eleventy.after` and other hooks
-2. **Better error handling** - Native try/catch with full stack traces
-3. **No spawn overhead** - Eliminates ~100-200ms process startup time
-4. **Debugging** - Easier to trace issues in-process
-
-The `cli.js` module is retained for backwards compatibility but is deprecated.
-
-**Known limitation:** The Eleventy `TemplatePathResolver` requires layouts and includes directories to be within the input directory, which prevents fully decoupling Quire project content from `quire-11ty` code. See [eleventy#2655](https://github.com/11ty/eleventy/issues/2655) (still open).
+**Nota bene** The current implementation of the `Eleventy` `TemplatePathResolver` assumes that the `layouts` directory is a child of the `input` directory and prevents decoupling the Quire project content from the `quire-11ty` code; see [eleventy#2655](https://github.com/11ty/eleventy/issues/2655).