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

package/src/lib/11ty/api.js

@@ -1,133 +1,216 @@
+/**
+ * Quire11ty façade for Eleventy integration
+ *
+ * Provides a unified interface for Eleventy operations with path resolution.
+ * Follows the singleton pattern like lib/npm and lib/git for consistency
+ * and easy mocking in tests.
+ *
+ * @example Production usage
+ * import eleventy from '#lib/11ty/index.js'
+ * await eleventy.build({ debug: true })
+ * const outputDir = eleventy.paths.getOutputDir()
+ *
+ * @example Path-only usage
+ * import { paths } from '#lib/11ty/index.js'
+ * const projectRoot = paths.getProjectRoot()
+ *
+ * @example Test mocking
+ * 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 }
+ * })
+ *
+ * @see https://www.11ty.dev/docs/programmatic/
+ * @module lib/11ty
+ */
 import { dynamicImport } from '#helpers/os-utils.js'
-import { pathToFileURL } from 'node:url'
 import path from 'node:path'
-import paths, { eleventyRoot, projectRoot } from './paths.js'
+import paths from '#lib/project/index.js'
+import { logger } from '#lib/logger/index.js'
+import createDebug from '#debug'
+
+const debug = createDebug('lib:11ty:api')
 
 /**
- * A factory function to configure an instance of Eleventy
- * @see https://www.11ty.dev/docs/config/#configuration-options
+ * Configure environment variables required for Eleventy.
+ *
+ * These must be set before the Eleventy instance is created and the
+ * `.eleventy.js` configuration file is parsed.
  *
- * @param  {Object}  options  Eleventy configuration options
- * @return  {Eleventy}  A configured instance of Eleventy
+ * @see https://github.com/11ty/eleventy/issues/2655
+ *
+ * @param {Object} options
+ * @param {'production'|'development'} options.mode - Build mode
+ * @param {boolean} options.debug - Enable Eleventy debug output
  */
-const factory = async (options = {}) => {
-  const { config, input, output } = paths
-
-  if (options.debug) {
-    console.debug('[CLI:11ty] projectRoot %s\n%o', projectRoot, paths)
+const configureEleventyEnv = ({ mode = 'production', debug = false } = {}) => {
+  // Path configuration for decoupling quire-11ty from project input directory
+  process.env.ELEVENTY_DATA = paths.getDataDir()
+  process.env.ELEVENTY_INCLUDES = paths.getIncludesDir()
+  process.env.ELEVENTY_LAYOUTS = paths.getLayoutsDir()
+
+  // Build mode
+  process.env.ELEVENTY_ENV = mode
+
+  // Debug output
+  if (debug) {
+    process.env.DEBUG = 'Eleventy*'
   }
+}
 
-  /**
-   * Dynamically import the correct version of Eleventy
-   */
-  const modulePath = path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy', 'src', 'Eleventy.js')
-  const { default: Eleventy } = await dynamicImport(modulePath)
+/**
+ * Create an instance of Eleventy configured for Quire projects
+ *
+ * @param {Object} options - Eleventy configuration options
+ * @param {boolean} [options.debug=false] - Enable debug output
+ * @param {boolean} [options.quiet=false] - Suppress output
+ * @param {string} [options.config] - Custom config path override
+ * @param {'build'|'serve'|'watch'} [options.runMode='build'] - Eleventy run mode
+ * @returns {Promise<Eleventy>} Configured Eleventy instance
+ */
+const createEleventyInstance = async (options = {}) => {
+  const config = paths.getConfigPath()
+  const eleventyRoot = paths.getEleventyRoot()
+  const input = paths.getInputDir()
+  const output = paths.getOutputDir()
+  const projectRoot = paths.getProjectRoot()
 
-  /**
-   * Set Eleventy passthrough copy options
-   * @see https://www.11ty.dev/docs/copy/#advanced-options
-   * @see https://github.com/timkendrick/recursive-copy
-   */
-  const copyOptions = {
-    debug: options.debug || false
-  }
+  debug('projectRoot: %s', projectRoot)
+  debug('paths: %O', paths.toObject())
 
-  /**
-   * Set environment variables for paths relative to eleventy `input` dir,
-   * to allow `quire-11ty` to be decouple from the project input directory.
-   * Nota bene: environment variables read into the eleventy configuration
-   * file _must_ be set before the eleventy configuration file is parsed.
-   * @see https://github.com/11ty/eleventy/issues/2655
-   */
-  process.env.ELEVENTY_DATA = paths.data
-  process.env.ELEVENTY_INCLUDES = paths.includes
-  process.env.ELEVENTY_LAYOUTS = paths.layouts
+  // Dynamically import the correct version of Eleventy
+  const modulePath = path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy', 'src', 'Eleventy.js')
+  const { default: Eleventy } = await dynamicImport(modulePath)
 
-  /**
-   * Get an instance of the runtime of eleventy.
-   * @see https://github.com/11ty/eleventy/blob/src/Eleventy.js
-   *
-   * @param {String} input  Path from which to read content templates
-   * @param {String} output  Path where rendered files will be written
-   * @param {Object} options  Options are merged with the Eleventy UserConfig
-   * @param {Object} config  An eleventy configurtion object
-   *
-   * @returns {module:11ty/eleventy/Eleventy~Eleventy}
-   */
+  // Create Eleventy instance
+  // @see https://github.com/11ty/eleventy/blob/src/Eleventy.js
   const eleventy = new Eleventy(input, output, {
     config: (eleventyConfig) => {
-      /**
-       * Override addPassthroughCopy to use _absolute_ system paths.
-       * @see https://www.11ty.dev/docs/copy/#passthrough-file-copy
-       * Nota bene: Eleventy addPassthroughCopy assumes paths are _relative_
-       * to the `config` file however the quire-cli separates 11ty from the
-       * project directory (`input`) and needs to use absolute system paths.
-       */
-      const addPassthroughCopy = eleventyConfig.addPassthroughCopy.bind(eleventyConfig)
-      eleventyConfig.addPassthroughCopy = (entry) => {
-        if (typeof entry === 'string') {
-          const filePath = path.resolve(entry) //path.join(projectRoot, file)
-          // console.debug('[11ty:API] passthrough copy %s', filePath)
-          return addPassthroughCopy(filePath, copyOptions)
-        } else {
-          // console.debug('[11ty:API] passthrough copy %o', entry)
-          entry = Object.fromEntries(
-            Object.entries(entry).map(([ src, dest ]) => {
-              return [ path.join(eleventyRoot, src), path.resolve(dest) ]
-            })
-          )
-          // console.debug('[11ty:API] passthrough copy %o', entry)
-          return addPassthroughCopy(entry, copyOptions)
-        }
-      }
-
-      /**
-       * Event callback when a build completes
-       * @see https://www.11ty.dev/docs/events/#eleventy.after
-       */
+      // Event callback when a build completes
+      // @see https://www.11ty.dev/docs/events/#eleventy.after
       eleventyConfig.on('eleventy.after', async () => {
-        console.debug('[11ty:API] build complete')
+        debug('build complete')
       })
 
       return eleventyConfig
     },
     configPath: options.config || config,
     quietMode: options.quiet || false,
+    runMode: options.runMode || 'build',
   })
 
   return eleventy
 }
 
 /**
- * A wrapper module for using the Eleventy programmatic API
- * @see https://www.11ty.dev/docs/programmatic/
- * @todo read paths from the Quire project configuration
+ * Quire11ty façade class
+ *
+ * Provides abstracted Eleventy operations with unified logging,
+ * error handling, and path resolution. Stores active Eleventy
+ * instance for cleanup registration with ProcessManager.
  */
-export default {
-  build: async (options = {}) => {
-    process.cwd(projectRoot)
+class Quire11ty {
+  /**
+   * Create Quire11ty instance
+   * @param {Object} pathsInstance - Paths instance for path resolution
+   */
+  constructor(pathsInstance) {
+    this.paths = pathsInstance
+    /**
+     * Active Eleventy instance (for API mode)
+     * @type {Eleventy|null}
+     */
+    this.activeInstance = null
+  }
+
+  /**
+   * Check if an Eleventy process is currently active
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.activeInstance !== null
+  }
+
+  /**
+   * Gracefully close any active Eleventy process
+   *
+   * Calls eleventy.close() to stop the dev server and file watchers.
+   * This method is registered with ProcessManager for signal handling.
+   *
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (this.activeInstance) {
+      debug('shutting down Eleventy')
+      try {
+        await this.activeInstance.close()
+      } catch (error) {
+        // Ignore errors during shutdown (may already be closing)
+        debug('close error (may be expected): %s', error.message)
+      }
+      this.activeInstance = null
+    }
+  }
+
+  /**
+   * Run Eleventy production build
+   *
+   * @param {Object} options - Build options
+   * @param {boolean} [options.debug=false] - Enable debug output
+   * @param {boolean} [options.dryRun=false] - Perform dry run without writing files
+   * @param {boolean} [options.quiet=false] - Suppress output
+   * @returns {Promise<void>}
+   */
+  async build(options = {}) {
+    const projectRoot = this.paths.getProjectRoot()
+    process.chdir(projectRoot)
 
-    console.info('[CLI:11ty] running eleventy build')
+    logger.info('Building site...')
 
-    process.env.ELEVENTY_ENV = 'production'
-    if (options.debug) process.env.DEBUG = 'Eleventy*'
+    configureEleventyEnv({ mode: 'production', debug: options.debug })
 
-    const eleventy = await factory(options)
+    const eleventy = await createEleventyInstance(options)
 
-    eleventy.setDryRun(options.dryrun)
+    eleventy.setDryRun(options.dryRun)
 
     await eleventy.write()
-  },
-  serve: async (options = {}) => {
-    process.cwd(projectRoot)
+  }
 
-    console.info('[CLI:11ty] running development server')
+  /**
+   * Run Eleventy development server
+   *
+   * @param {Object} options - Serve options
+   * @param {boolean} [options.debug=false] - Enable debug output
+   * @param {number} [options.port] - Server port
+   * @param {boolean} [options.quiet=false] - Suppress output
+   * @returns {Promise<void>}
+   */
+  async serve(options = {}) {
+    const projectRoot = this.paths.getProjectRoot()
+    process.chdir(projectRoot)
+
+    logger.info('Starting development server...')
 
-    process.env.ELEVENTY_ENV = 'development'
-    if (options.debug) process.env.DEBUG = 'Eleventy*'
+    configureEleventyEnv({ mode: 'development', debug: options.debug })
 
-    const eleventy = await factory(options)
+    const eleventy =
+      await createEleventyInstance({ ...options, runMode: 'serve' })
+
+    // Store reference for lifecycle management (graceful shutdown)
+    this.activeInstance = eleventy
+
+    // Initialize Eleventy before serving (required for eleventyServe)
+    await eleventy.init()
 
     await eleventy.serve(options.port)
   }
 }
+
+export { Quire11ty, createEleventyInstance, configureEleventyEnv }

package/src/lib/11ty/cli.js

@@ -1,7 +1,35 @@
 import { execa } from 'execa'
 import fs from 'node:fs'
 import path from 'node:path'
-import paths, { eleventyRoot, projectRoot } from './paths.js'
+import paths from '#lib/project/index.js'
+import processManager from '#lib/process/manager.js'
+import { BuildFailedError } from '#src/errors/index.js'
+import { logger } from '#lib/logger/index.js'
+import createDebug from '#debug'
+
+const debug = createDebug('lib:11ty')
+
+/**
+ * Spawn a cancellable subprocess with output piped to stdout
+ *
+ * @param {string[]} command - Command arguments for node
+ * @param {Object} options - Spawn options
+ * @param {string} options.cwd - Working directory
+ * @param {Object} options.env - Environment variables
+ * @returns {import('execa').ExecaChildProcess}
+ */
+const spawn = (command, { cwd, env }) => {
+  const subprocess = execa('node', command, {
+    all: true,
+    cwd,
+    env,
+    execPath: process.execPath,
+    cancelSignal: processManager.signal,
+    gracefulCancel: true,
+  })
+  subprocess.all.pipe(process.stdout)
+  return subprocess
+}
 
 /**
  * A factory function to configure an Eleventy CLI command
@@ -10,20 +38,21 @@ import paths, { eleventyRoot, projectRoot } from './paths.js'
  * @return  {Array} Eleventy CLI options
  */
 const factory = (options = {}) => {
-  const { config, input, output } = paths
+  const config = paths.getConfigPath()
+  const eleventyRoot = paths.getEleventyRoot()
+  const input = paths.getInputDir()
+  const output = paths.getOutputDir()
+  const projectRoot = paths.getProjectRoot()
 
-  if (options.debug) {
-    console.debug('[CLI:11ty] projectRoot %s\n%o', projectRoot, paths)
-  }
+  debug('projectRoot: %s', projectRoot)
+  debug('paths: %O', paths.toObject())
 
   /**
    * Use the version of Eleventy installed to `lib/quire/versions`
-   * 
-   * NB: in eleventy v3 the CLI extension (".cjs") is load-bearing but v2 is simply ".js"
-   * 
+   * Nota bene: in eleventy v3 the CLI extension (".cjs") is load-bearing but v2 is simply ".js"
    */
   const eleventyModuleDir = path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy')
-  const packagePath = path.join(eleventyModuleDir,'package.json')  
+  const packagePath = path.join(eleventyModuleDir,'package.json')
 
   const pack = JSON.parse(fs.readFileSync(packagePath))
 
@@ -59,14 +88,14 @@ const factory = (options = {}) => {
    * @see https://github.com/11ty/eleventy/issues/2655
    */
   const env = {
-    ELEVENTY_DATA: paths.data,
-    ELEVENTY_INCLUDES: paths.includes,
-    ELEVENTY_LAYOUTS: paths.layouts,
+    ELEVENTY_DATA: paths.getDataDir(),
+    ELEVENTY_INCLUDES: paths.getIncludesDir(),
+    ELEVENTY_LAYOUTS: paths.getLayoutsDir(),
   }
 
   if (options.debug) env.DEBUG = 'Eleventy*'
 
-  return { command, env }
+  return { command, env, projectRoot }
 }
 
 /**
@@ -74,33 +103,43 @@ const factory = (options = {}) => {
  * @see https://www.11ty.dev/docs/usage/#command-line-usage
  */
 export default {
+  /**
+   * Run Eleventy build via CLI
+   * @param {Object} options - Build options
+   */
   build: async (options = {}) => {
-    console.info('[CLI:11ty] running eleventy build')
+    logger.info('Building site...')
 
-    const { command, env } = factory(options)
+    const { command, env, projectRoot } = factory(options)
 
     if (options.dryRun) command.push('--dryrun')
 
     env.ELEVENTY_ENV = 'production'
 
-    const build = execa('node', command, {
-      all: true,
-      cwd: projectRoot,
-      env,
-      execPath: process.execPath
-    })
-    build.all.pipe(process.stdout)
-    await build
-
-    if (build.exitCode !== 0) {
-      process.exit(build.exitCode)
+    try {
+      const build = spawn(command, { cwd: projectRoot, env })
+      await build
+
+      if (build.exitCode !== 0) {
+        throw new BuildFailedError(`Eleventy exited with code ${build.exitCode}`)
+      }
+    } catch (error) {
+      if (error.isCanceled) {
+        debug('build cancelled')
+        return
+      }
+      throw error
     }
   },
 
+  /**
+   * Run Eleventy development server via CLI
+   * @param {Object} options - Serve options
+   */
   serve: async (options = {}) => {
-    console.info(`[CLI:11ty] running eleventy serve`)
+    logger.info('Starting development server...')
 
-    const { command, env } = factory(options)
+    const { command, env, projectRoot } = factory(options)
 
     command.push('--serve')
 
@@ -108,11 +147,14 @@ export default {
 
     env.ELEVENTY_ENV = 'development'
 
-    await execa('node', command, {
-      all: true,
-      cwd: projectRoot,
-      env,
-      execPath: process.execPath
-    }).all.pipe(process.stdout)
-  }
+    try {
+      await spawn(command, { cwd: projectRoot, env })
+    } catch (error) {
+      if (error.isCanceled) {
+        debug('server stopped')
+        return
+      }
+      throw error
+    }
+  },
 }

package/src/lib/11ty/index.js

@@ -1,11 +1,70 @@
-import cli from './cli.js'
-import api from './api.js'
-import paths, { eleventyRoot, projectRoot } from './paths.js'
+/**
+ * Quire Eleventy integration module
+ *
+ * Provides a unified façade for Eleventy operations following the singleton
+ * pattern established by lib/npm and lib/git. Integrates with the central
+ * ProcessManager for graceful shutdown on process signals.
+ *
+ * @example Recommended usage
+ * import eleventy from '#lib/11ty/index.js'
+ * await eleventy.build({ debug: true })
+ * const outputDir = eleventy.paths.getOutputDir()
+ *
+ * @example Path-only usage (for consumers that only need paths)
+ * import { paths } from '#lib/11ty/index.js'
+ * const projectRoot = paths.getProjectRoot()
+ *
+ * @example Legacy usage (deprecated)
+ * import { api, cli, paths } from '#lib/11ty/index.js'
+ *
+ * @module lib/11ty
+ */
+import { Quire11ty } from './api.js'
+import cliModule from './cli.js'
+import paths, { Paths } from '#lib/project/index.js'
+import processManager from '#lib/process/manager.js'
 
+/**
+ * Quire11ty singleton instance
+ * @type {Quire11ty}
+ */
+const eleventy = new Quire11ty(paths)
+
+/**
+ * CLI wrapper - delegates to cli.js which imports processManager directly
+ */
+const cli = {
+  build: async (options) => cliModule.build(options),
+  serve: async (options) => cliModule.serve(options),
+}
+
+/**
+ * Legacy API export for backwards compatibility
+ *
+ * Wraps the singleton methods to register cleanup handlers with
+ * ProcessManager for graceful shutdown support.
+ *
+ * @deprecated Use default export instead: `import eleventy from '#lib/11ty/index.js'`
+ */
+const api = {
+  build: async (options) => eleventy.build(options),
+  serve: async (options) => {
+    processManager.onShutdown('eleventy', () => eleventy.close())
+    try {
+      return await eleventy.serve(options)
+    } finally {
+      processManager.onShutdownComplete('eleventy')
+    }
+  },
+}
+
+// Default export: unified façade
+export default eleventy
+
+// Named exports for backwards compatibility and path-only consumers
 export {
   api,
   cli,
-  eleventyRoot,
   paths,
-  projectRoot,
+  Paths,
 }