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

package/src/helpers/docs-url.js

@@ -0,0 +1,32 @@
+/**
+ * Helper module for constructing documentation URLs
+ * @module helpers/docs-url
+ */
+
+/**
+ * Base URL for Quire documentation
+ */
+const DOCS_BASE = 'https://quire.getty.edu/docs-v1/'
+
+/**
+ * Export the base URL for cases where direct access is needed
+ */
+export { DOCS_BASE }
+
+/**
+ * Construct a full documentation URL from a path segment
+ *
+ * Uses the URL constructor for automatic path normalization.
+ *
+ * @param {string} path - Documentation path segment (e.g., 'install-uninstall')
+ * @returns {string} Full documentation URL
+ *
+ * @example
+ * docsUrl('install-uninstall')
+ * // => 'https://quire.getty.edu/docs-v1/install-uninstall'
+ *
+ * @example
+ * docsUrl('quire-commands')
+ * // => 'https://quire.getty.edu/docs-v1/quire-commands'
+ */
+export const docsUrl = (path) => new URL(path, DOCS_BASE).href

package/src/helpers/test-cwd.js

@@ -1,19 +1,18 @@
 /**
  * A helper module to test the current working directory
- * @module test-csd
+ * @module test-cwd
  */
-import isQuire from '#helpers/is-quire.js'
+import { detect as isQuire } from '#lib/project/index.js'
+import { NotInProjectError } from '#src/errors/index.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())) {
-    console.error(message)
-    process.exit(1)
+    throw new NotInProjectError(command?.name() || '')
   }
 }

package/src/helpers/test-cwd.test.js

@@ -0,0 +1,192 @@
+import test from 'ava'
+import { Volume, createFsFromVolume } from 'memfs'
+import sinon from 'sinon'
+import esmock from 'esmock'
+import { NotInProjectError } from '#src/errors/index.js'
+
+test.beforeEach((t) => {
+  // Create in-memory file system
+  t.context.vol = new Volume()
+  t.context.fs = createFsFromVolume(t.context.vol)
+})
+
+test.afterEach.always((t) => {
+  // Restore all mocks if sandbox exists
+  if (t.context.sandbox) {
+    t.context.sandbox.restore()
+  }
+
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
+
+test.serial('testcwd should not error when called in a Quire project directory', async (t) => {
+  const { fs, vol } = t.context
+
+  // Create sandbox for this test
+  const sandbox = sinon.createSandbox()
+  t.context.sandbox = sandbox
+
+  // Setup a Quire project directory with .eleventy.js
+  vol.fromJSON({
+    '/quire-project/.eleventy.js': 'module.exports = function() {}',
+    '/quire-project/content/_data/config.yaml': 'title: Test Project',
+    '/quire-project/package.json': JSON.stringify({ name: 'test-project' })
+  })
+
+  // Create stubs
+  const cwdStub = sandbox.stub(process, 'cwd').returns('/quire-project')
+
+  // Create mock process object with stubbed methods
+  const mockProcess = {
+    cwd: cwdStub
+  }
+
+  // Mock detect module with memfs
+  const mockDetect = await esmock('../lib/project/detect.js', {
+    'node:fs': fs
+  })
+
+  // Mock node:fs and node:process to use memfs and stubbed process
+  const testcwd = await esmock('./test-cwd.js', {
+    'node:process': mockProcess,
+    '#lib/project/index.js': {
+      detect: mockDetect
+    }
+  })
+
+  // Create mock command
+  const mockCommand = {
+    name: sandbox.stub().returns('build')
+  }
+
+  // Call testcwd - should not throw
+  t.notThrows(() => testcwd(mockCommand))
+})
+
+test.serial('testcwd should throw NotInProjectError when called outside a Quire project directory', async (t) => {
+  const { fs, vol } = t.context
+
+  // Create sandbox for this test
+  const sandbox = sinon.createSandbox()
+  t.context.sandbox = sandbox
+
+  // Setup a non-Quire directory (no .eleventy.js or other Quire marker files)
+  vol.fromJSON({
+    '/not-quire/some-file.txt': 'not a quire project',
+    '/not-quire/package.json': JSON.stringify({ name: 'not-a-quire-project' })
+  })
+
+  // Create stubs
+  const cwdStub = sandbox.stub(process, 'cwd').returns('/not-quire')
+
+  // Create mock process object with stubbed methods
+  const mockProcess = {
+    cwd: cwdStub
+  }
+
+  // Mock detect module with memfs
+  const mockDetect = await esmock('../lib/project/detect.js', {
+    'node:fs': fs
+  })
+
+  // Mock node:fs and node:process to use memfs and stubbed process
+  const testcwd = await esmock('./test-cwd.js', {
+    'node:process': mockProcess,
+    '#lib/project/index.js': {
+      detect: mockDetect
+    }
+  })
+
+  // Create mock command
+  const mockCommand = {
+    name: sandbox.stub().returns('build')
+  }
+
+  // Call testcwd - should throw NotInProjectError
+  const error = t.throws(() => testcwd(mockCommand), { instanceOf: NotInProjectError })
+  t.is(error.code, 'NOT_IN_PROJECT')
+  t.is(error.exitCode, 2)
+  t.true(error.message.includes('build'))
+})
+
+test.serial('testcwd should include command name in error message', async (t) => {
+  const { fs, vol } = t.context
+
+  // Create sandbox for this test
+  const sandbox = sinon.createSandbox()
+  t.context.sandbox = sandbox
+
+  // Setup a non-Quire directory
+  vol.fromJSON({
+    '/non-quire-directory/file.txt': 'test'
+  })
+
+  // Create stubs
+  const cwdStub = sandbox.stub(process, 'cwd').returns('/non-quire-directory')
+
+  // Create mock process object with stubbed methods
+  const mockProcess = {
+    cwd: cwdStub
+  }
+
+  // Mock detect module with memfs
+  const mockDetect = await esmock('../lib/project/detect.js', {
+    'node:fs': fs
+  })
+
+  // Mock node:fs and node:process to use memfs and stubbed process
+  const testcwd = await esmock('./test-cwd.js', {
+    'node:process': mockProcess,
+    '#lib/project/index.js': {
+      detect: mockDetect
+    }
+  })
+
+  // Create mock command with specific name
+  const mockCommand = {
+    name: sandbox.stub().returns('clean')
+  }
+
+  // Call testcwd - should throw with command name in message
+  const error = t.throws(() => testcwd(mockCommand), { instanceOf: NotInProjectError })
+  t.true(error.message.includes('clean'), 'error message should include command name')
+})
+
+test.serial('testcwd should work when command is null', async (t) => {
+  const { fs, vol } = t.context
+
+  // Create sandbox for this test
+  const sandbox = sinon.createSandbox()
+  t.context.sandbox = sandbox
+
+  // Setup a non-Quire directory
+  vol.fromJSON({
+    '/not-a-quire-directory/file.txt': 'test'
+  })
+
+  // Create stubs
+  const cwdStub = sandbox.stub(process, 'cwd').returns('/not-a-quire-directory')
+
+  // Create mock process object with stubbed methods
+  const mockProcess = {
+    cwd: cwdStub
+  }
+
+  // Mock detect module with memfs
+  const mockDetect = await esmock('../lib/project/detect.js', {
+    'node:fs': fs
+  })
+
+  // Mock node:fs and node:process to use memfs and stubbed process
+  const testcwd = await esmock('./test-cwd.js', {
+    'node:process': mockProcess,
+    '#lib/project/index.js': {
+      detect: mockDetect
+    }
+  })
+
+  // Call testcwd with null command - should throw but not crash
+  const error = t.throws(() => testcwd(null), { instanceOf: NotInProjectError })
+  t.is(error.exitCode, 2)
+})

package/src/helpers/which.js

@@ -3,19 +3,25 @@
  * @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) => {
+export default (executable, toolInfo) => {
   const result = which.sync(executable, { nothrow: true })
   if (!result) {
-    console.error(`Unable to locate executable '${executable}'\n
-      Ensure that the '${executable}' executable is installed and available in the shell environment PATH.
-    `)
+    throw new ToolNotFoundError(executable, toolInfo)
   }
   return result
 }

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

@@ -1,35 +1,151 @@
 ## CLI 11ty Module
 
-The `quire-cli/lib/11ty` module is a façade for interacting with Eleventy, the static site generator for Quire projects.
+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`.
 
-### 11ty/API module
+### Usage
 
-The `api` module allows the Quire CLI to programmatical configure an instance of Eleventy on which it can call methods.
+**Recommended: Default export**
 
-See [Eleventy Documentation: Programmatic API](https://www.11ty.dev/docs/programmatic/)
+```javascript
+import eleventy from '#lib/11ty/index.js'
 
-### 11ty/CLI module
+// Run production build
+await eleventy.build({ debug: true })
 
-The `cli` module is a wrapper around the Eleventy CLI to run `@11ty/eleventy` commands.
+// Run development server
+await eleventy.serve({ port: 8080 })
 
-See [Eleventy Documentation: Command Line Usage](https://www.11ty.dev/docs/usage/#command-line-usage)
+// Access paths through the façade
+const outputDir = eleventy.paths.getOutputDir()
+```
 
-### Paths module
+**Path-only consumers**
 
-The `paths` module returns paths for a Quire project to configure the Eleventy instance:
+```javascript
+import { paths } from '#lib/11ty/index.js'
 
-- _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
+const projectRoot = paths.getProjectRoot()
+const outputDir = paths.getOutputDir()
+```
 
+**Legacy usage (deprecated)**
 
-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.
+```javascript
+// Deprecated - use default export instead
+import { api, cli, paths } from '#lib/11ty/index.js'
+await api.build(options)
+```
 
-`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.
+### Test Mocking
 
-These environment variables **must be set before** the `Eleventy` instance is created and the `.eleventy.js` configuration is parsed.
+```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 }
+})
+```
 
-**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).
+### 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).