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

package/CHANGELOG.md

@@ -12,6 +12,42 @@ Changelog entries are classified using the following labels:
 - `Fixed`: for any bug fixes
 - `Removed`: for deprecated features removed in this release
 
+## [Unreleased]
+
+### Added
+
+- New `quire validate` command to check YAML syntax in `content/_data/` directory
+- New `quire use <version>` command (renamed from `quire version`) to change quire-11ty version
+- Config settings for default PDF and EPUB engines via `quire settings set pdfEngine <engine>` and `quire settings set epubEngine <engine>`
+- Config settings for default log level via `quire settings set logLevel <level>`
+- Debug logger module with namespace support (`DEBUG=quire:*`)
+- Process manager for graceful shutdown handling (Ctrl+C) during long-running operations
+- `--build` flag for `quire pdf` and `quire epub` commands to run build first if output is missing
+- `--engine` option for `quire pdf` and `quire epub` commands (deprecates `--lib`)
+- Helper functions for build output detection (`hasSiteOutput`, `hasEpubOutput`, `hasPdfOutput`)
+- Comprehensive error handling system with domain-specific error classes
+- Documentation for CLI architecture, error handling, and testing
+
+### Changed
+
+- Renamed `quire conf` command to `quire config` (aliased as `quire settings`)
+- Renamed `quire version` command to `quire use`
+- Refactored error handling to use thrown errors instead of `process.exit()` for better testability
+- Commands now inherit `debug()` and `logger` methods from base Command class
+- Improved log output with configurable log levels (trace, debug, info, warn, error, silent)
+- Replaced `simple-git` dependency with a lightweight git façade module
+- Replaced `execaCommand` with `execa` for improved command execution
+- Encapsulated project concerns into dedicated `lib/project` module
+- Encapsulated 11ty interactions into a façade module with process lifecycle management
+
+### Fixed
+
+- `quire new` command arguments and options validation
+- Command lifecycle hook errors are now correctly handled and reported
+- Disabled auto-deletion of project directory on `quire new` failures to prevent accidental data loss
+- Package schema files validation
+- Process manager import paths for logger module
+
 ## [1.0.0-rc.33]
 
 ### Bumped

package/README.md

@@ -24,3 +24,12 @@ npm install quire-cli --install-strategy=nested
 ```sh
 npx quire-cli --help
 ```
+
+### Testing
+
+The CLI uses two types of test files for commands:
+
+- **`*.spec.js`** - Contract/interface tests that verify the command definition is correctly transformed into Commander.js Command object instance and the public API is correct
+- **`*.test.js`** - Integration/behavior tests that verify command execution with real dependencies
+
+See [docs/testing-commands.md](docs/testing-commands.md) for the complete testing guide and patterns.

package/bin/cli.js

@@ -1,11 +1,29 @@
 #!/usr/bin/env -S node --no-warnings
-import cli from '#src/main.js'
 import config from '#src/lib/conf/config.js'
 import packageConfig from '#src/packageConfig.js'
 import updateNotifier from 'update-notifier'
 
+// Import process manager to register signal handlers for graceful shutdown
+import '#lib/process/manager.js'
+
 process.removeAllListeners('warning')
 
+/**
+ * Set log level from config before importing CLI modules
+ *
+ * This env var is read by the logger at module creation time.
+ * Setting it here ensures all loggers (including module-level ones)
+ * use the configured level.
+ *
+ * @see lib/logger/index.js
+ */
+process.env.QUIRE_LOG_LEVEL = config.get('logLevel') || 'info'
+
+/**
+ * Dynamic import ensures env var is set before logger modules are loaded
+ */
+const { default: cli } = await import('#src/main.js')
+
 /**
  * Interval constants in milliseconds
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.34",
+  "version": "1.0.0-rc.36",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -20,6 +20,7 @@
   "files": [
     "bin/",
     "patches/",
+    "schemas/",
     "scripts/",
     "src/",
     "CHANGELOG.md",
@@ -38,21 +39,28 @@
     "docs": "jsdoc2md --configure jsdoc.json --files src/**/*.js > docs/cli.md",
     "lint": "eslint src --ext .js",
     "lint:fix": "npm run lint -- --fix",
-    "test": "echo \"No test specified\" && exit 0"
+    "test": "ava",
+    "test:watch": "ava --watch",
+    "test:unit": "ava src/commands/**/*.spec.js src/lib/**/*.spec.js",
+    "test:integration": "ava src/commands/**/*.test.js src/helpers/**/*.test.js src/lib/**/*.test.js",
+    "test:e2e": "ava test/e2e/**/*.e2e.js",
+    "test:coverage": "c8 ava"
   },
   "imports": {
     "#root/*": "./*",
     "#src/*.js": "./src/*.js",
     "#helpers/*.js": "./src/helpers/*.js",
-    "#lib/*.js": "./src/lib/*.js"
+    "#lib/*.js": "./src/lib/*.js",
+    "#debug": "./src/lib/logger/debug.js"
   },
   "dependencies": {
     "ajv": "^8.16.0",
     "boxen": "^7.0.1",
     "chalk": "^5.2.0",
-    "commander": "^12.1.0",
-    "conf": "^13.1.0",
+    "commander": "^14.0.2",
+    "conf": "^15.0.2",
     "cross-env": "^7.0.3",
+    "debug": "^4.4.0",
     "del": "^7.0.0",
     "epubjs-cli": "^0.1.6",
     "execa": "^6.1.0",
@@ -66,14 +74,19 @@
     "open": "^8.4.0",
     "ora": "^6.1.2",
     "pagedjs-cli": "^0.4.3",
+    "pdf-lib": "^1.17.1",
     "read-package-up": "^11.0.0",
     "semver": "^7.3.8",
-    "simple-git": "^3.16.0",
-    "update-notifier": "^7.3.1"
+    "update-notifier": "^7.3.1",
+    "which": "^2.0.2"
   },
   "devDependencies": {
+    "ava": "^6.2.0",
     "eslint": "^8.32.0",
-    "jsdoc-to-markdown": "^9.1.1"
+    "esmock": "^2.7.3",
+    "jsdoc-to-markdown": "^9.1.1",
+    "memfs": "^4.51.1",
+    "sinon": "^17.0.1"
   },
   "engines": {
     "node": ">=22"

package/schemas/config.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Quire Config Schema",
+  "type": "object",
+  "properties": {
+    "accordion": {
+      "type": "object",
+      "properties": {
+        "controls": {
+          "type": "string",
+          "enum": ["arrow", "plus-minus"]
+        },
+        "copyButton": {
+          "type": "object",
+          "properties": {
+            "ariaLabel": { "type": "string" },
+            "successText": { "type": "string" },
+            "symbol": { "type": "string" }
+          },
+          "required": ["ariaLabel", "successText", "symbol"]
+        },
+        "globalControls": {
+          "type": "object",
+          "properties": {
+            "collapseText": { "type": "string" },
+            "expandText": { "type": "string" }
+          },
+          "required": ["collapseText", "expandText"]
+        }
+      },
+      "required": ["controls", "copyButton", "globalControls"]
+    },
+    "analytics": {
+      "type": "object",
+      "properties": {
+        "googleId": { "type": "string" }
+      },
+      "required": ["googleId"]
+    },
+    "bylineFormat": {
+      "oneOf": [
+        { "type": "string", "enum": ["name", "name-title"] },
+        { "type": "boolean", "enum": [false] }
+      ]
+    },
+    "bibliography": {
+      "type": "object",
+      "properties": {
+        "displayOnPage": { "type": "boolean" },
+        "displayShort": { "type": "boolean" },
+        "heading": { "type": "string" }
+      },
+      "required": ["displayOnPage", "displayShort", "heading"]
+    },
+    "citations": {
+      "type": "object",
+      "properties": {
+        "divider": { "type": "string" },
+        "popupStyle": {
+          "type": "string",
+          "enum": ["text", "icon"]
+        }
+      },
+      "required": ["divider", "popupStyle"]
+    },
+    "entryPage": {
+      "type": "object",
+      "properties": {
+        "sideBySide": { "type": "boolean" },
+        "objectLinkText": { "type": "string" }
+      },
+      "required": ["sideBySide", "objectLinkText"]
+    },
+    "epub": {
+      "type": "object",
+      "properties": {
+        "defaultCoverImage": { "type": "string" },
+        "outputDir": { "type": "string" }
+      },
+      "required": ["defaultCoverImage", "outputDir"]
+    },
+    "footnotes": {
+      "type": "object",
+      "properties": {
+        "backlinkSymbol": { "type": "string" }
+      },
+      "required": ["backlinkSymbol"]
+    },
+    "figures": {
+      "type": "object",
+      "properties": {
+        "assetDir": { "type": "string" },
+        "enableModal": { "type": "boolean" },
+        "imageDir": { "type": "string" }
+      },
+      "required": ["assetDir", "enableModal", "imageDir"]
+    },
+    "licenseIcons": { "type": "boolean" },
+    "localization": {
+      "type": "object",
+      "properties": {
+        "defaultLocale": { "type": "string" }
+      },
+      "required": ["defaultLocale"]
+    },
+    "menuType": {
+      "type": "string",
+      "enum": ["full", "brief"]
+    },
+    "navigation": {
+      "type": "object",
+      "properties": {
+        "nextButtonText": { "type": "string" },
+        "prevButtonText": { "type": "string" }
+      },
+      "required": ["nextButtonText", "prevButtonText"]
+    },
+    "pageTitle": {
+      "type": "object",
+      "properties": {
+        "labelDivider": { "type": "string" }
+      },
+      "required": ["labelDivider"]
+    },
+    "pdf": {
+      "type": "object",
+      "properties": {
+        "filename": { "type": "string" },
+        "outputDir": { "type": "string" },
+        "pagePDF": {
+          "type": "object",
+          "properties": {
+            "accessLinks": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "header": { "type": "boolean" },
+                  "footer": { "type": "boolean" },
+                  "label": { "type": "string" }
+                }
+              }
+            },
+            "coverPage": { "type": "boolean" },
+            "output": { "type": "boolean" }
+          },
+          "required": ["accessLinks", "coverPage", "output"]
+        },
+        "publicationPDF": {
+          "type": "object",
+          "properties": {
+            "output": { "type": "boolean" }
+          },
+          "required": ["output"]
+        }
+      },
+      "required": ["filename", "outputDir", "pagePDF", "publicationPDF"]
+    },
+    "ref": {
+      "type": "object",
+      "properties": {
+        "sequenceTransition": { "type": "number" }
+      },
+      "required": ["sequenceTransition"]
+    },
+    "searchEnabled": { "type": "boolean" },
+    "tableOfContents": {
+      "type": "object",
+      "properties": {
+        "contributorDivider": { "type": "string" }
+      },
+      "required": ["contributorDivider"]
+    }
+  },
+  "required": [
+    "accordion",
+    "bylineFormat",
+    "bibliography",
+    "citations",
+    "entryPage",
+    "epub",
+    "footnotes",
+    "figures",
+    "licenseIcons",
+    "localization",
+    "menuType",
+    "navigation",
+    "pageTitle",
+    "pdf",
+    "ref",
+    "searchEnabled",
+    "tableOfContents"
+  ]
+}

package/schemas/figures.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Figures YAML Schema",
+  "type": "object",
+  "properties": {
+    "figure_list": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "src": { "type": "string" },
+          "caption": { "type": "string" },
+          "credit": { "type": ["string", "null"] },
+          "alt": { "type": ["string", "null"] },
+          "poster": { "type": "string" },
+          "download": { "type": "boolean" },
+          "zoom": { "type": "boolean" },
+          "media_id": { "type": "string" },
+          "media_type": {
+            "type": "string",
+            "enum": ["youtube", "soundcloud", "table"]
+          },
+          "annotations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["input", "items"],
+              "properties": {
+                "input": {
+                  "type": "string",
+                  "enum": ["radio", "checkbox"]
+                },
+                "items": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "src": { "type": "string" },
+                      "label": { "type": "string" },
+                      "selected": { "type": "boolean" }
+                    },
+                    "required": ["src"]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "required": ["figure_list"]
+}

package/schemas/layout.schema.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Layout Schema",
+  "type": "string"
+}

package/schemas/objects.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Objects Schema",
+  "type": "object",
+  "required": [
+    "object_card",
+    "object_display_order",
+    "object_filters",
+    "object_list"
+  ],
+  "properties": {
+    "object_filters": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 0
+    },
+    "object_card": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 0
+    },
+    "object_display_order": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 0
+    },
+    "object_list": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "artist": { "type": "string" },
+          "year": { "type": "string" },
+          "medium": { "type": "string" },
+          "dimensions": { "type": "string" },
+          "location": { "type": "string" },
+          "link": { "type": "string", "format": "uri" },
+          "figure": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string" }
+              },
+              "required": [
+                "id"
+              ]
+            },
+            "minItems": 0
+          }
+        },
+        "required": [
+          "id",
+          "title"
+        ]
+      },
+      "minItems": 0
+    }
+  }
+}

package/schemas/publication.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Publication Schema",
+  "type": "object",
+  "required": [
+    "url",
+    "title",
+    "subtitle",
+    "description",
+    "pub_date",
+    "language",
+    "pub_type",
+    "identifier",
+    "publisher",
+    "contributor",
+    "copyright",
+    "license",
+    "resource_link",
+    "subject",
+    "revision_history",
+    "promo_image"
+  ],
+  "properties": {
+    "url": { "type": "string" },
+    "title": { "type": "string" },
+    "subtitle": { "type": "string" },
+    "reading_line": { "type": ["string", "null"] },
+    "short_title": { "type": ["string", "null"] },
+    "description": {
+      "type": "object",
+      "required": ["full"],
+      "properties": {
+        "one_line": { "type": ["string", "null"] },
+        "full": { "type": "string" }
+      }
+    },
+    "pub_date": { 
+        "oneOf": [
+            { "type": "string" },
+            { "type": "object" }
+  ] },
+    "language": { "type": "string" },
+    "pub_type": { "type": "string" },
+    "identifier": {
+      "type": "object",
+      "properties": {
+        "isbn": { "type": ["string", "null"] }
+      }
+    },
+    "publisher": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/publisher" }
+    },
+    "contributor_as_it_appears": { "type": ["string", "null"] },
+    "contributor": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/contributor" }
+    },
+    "copyright": { "type": "string" },
+    "license": { "$ref": "#/definitions/license" },
+    "resource_link": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/resourceLink" }
+    },
+    "subject": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/subject" }
+    },
+    "revision_history": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/revision" }
+    },
+    "repository_url": { "type": ["string", "null"] },
+    "promo_image": { "type": "string" }
+  },
+  "definitions": {
+    "publisher": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "location": { "type": ["string", "null"] },
+        "url": { "type": ["string", "null"] },
+        "logo": { "type": ["string", "null"] }
+      }
+    },
+    "contributor": {
+      "type": "object",
+      "required": ["id", "type", "first_name", "last_name"],
+      "properties": {
+        "id": { "type": "string" },
+        "type": { "type": "string" },
+        "first_name": { "type": "string" },
+        "last_name": { "type": "string" },
+        "title": { "type": ["string", "null"] },
+        "affiliation": { "type": ["string", "null"] },
+        "bio": { "type": ["string", "null"] },
+        "url": { "type": ["string", "null"] },
+        "image": { "type": ["string", "null"] }
+      }
+    },
+    "license": {
+      "type": "object",
+      "required": ["name", "abbreviation", "url", "scope"],
+      "properties": {
+        "name": { "type": "string" },
+        "abbreviation": { "type": "string" },
+        "url": { "type": "string" },
+        "scope": { "type": "string" }
+      }
+    },
+    "resourceLink": {
+      "type": "object",
+      "required": ["type", "name", "link_relation"],
+      "properties": {
+        "type": { "type": "string" },
+        "name": { "type": "string" },
+        "media_type": { "type": ["string", "null"] },
+        "link_relation": { "type": "string" },
+        "url": { "type": ["string", "null"] }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": ["type", "name"],
+      "properties": {
+        "type": { "type": "string" },
+        "name": { "type": "string" },
+        "identifier": { "type": ["string", "null"] }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "properties": {
+        "date": { "type": ["string", "null"] },
+        "summary": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/schemas/references.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "References Schema",
+  "type": "object",
+  "required": [
+    "entries"
+  ],
+  "properties": {
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "full": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "full",
+          "id"
+        ]
+      },
+      "minItems": 0
+    }
+  }
+}