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

package/src/lib/git/README.md

@@ -1,152 +1,3 @@
-# Git Façade
+## CLI Git Module
 
-A façade module that abstracts git command-line operations for the Quire CLI.
-
-## Purpose
-
-This module provides a unified interface for git operations with:
-
-- Encapsulation of git implementation details
-- Consistent logging prefixed with `[CLI:lib/git]`
-- Unified error handling
-- Easy mockability for testing
-
-## Usage
-
-### Singleton (for global operations)
-
-```javascript
-import git from '#lib/git/index.js'
-
-// Check git availability
-if (!git.isAvailable()) {
-  console.error('git is not installed')
-}
-
-// Get git version
-// @see https://git-scm.com/docs/git-version
-const version = await git.version()
-```
-
-### Git Class (for repository-scoped operations)
-
-```javascript
-import { Git } from '#lib/git/index.js'
-
-// Create instance with working directory
-const repo = new Git('/path/to/project')
-
-// Clone a repository
-// @see https://git-scm.com/docs/git-clone
-await repo.clone('https://github.com/user/repo', '.')
-
-// Initialize a repository
-// @see https://git-scm.com/docs/git-init
-await repo.init()
-
-// Stage files
-// @see https://git-scm.com/docs/git-add
-await repo.add('.')
-await repo.add(['file1.js', 'file2.js'])
-
-// Create a commit
-// @see https://git-scm.com/docs/git-commit
-await repo.commit('Initial commit')
-
-// Remove files from tracking
-// @see https://git-scm.com/docs/git-rm
-await repo.rm('package.json')
-await repo.rm(['file1.js', 'file2.js'])
-```
-
-## API
-
-### Constructor
-
-#### `new Git(cwd)`
-
-Create a Git façade instance scoped to a working directory.
-
-**Parameters:**
-- `cwd` (string, optional) - Working directory for all operations
-
-### Methods
-
-#### `isAvailable()`
-
-Check if git is available in PATH.
-
-#### `version()`
-
-Get the installed git version.
-
-#### `add(files)`
-
-Stage files for commit.
-
-**Parameters:**
-- `files` (string|string[]) - Files to stage (use `'.'` for all)
-
-#### `clone(url, destination)`
-
-Clone a repository.
-
-**Parameters:**
-- `url` (string) - Repository URL
-- `destination` (string, default: `'.'`) - Destination directory
-
-#### `commit(message)`
-
-Create a commit with staged changes.
-
-**Parameters:**
-- `message` (string) - Commit message
-
-#### `init()`
-
-Initialize a new git repository.
-
-#### `rm(files)`
-
-Remove files from the working tree and index.
-
-**Parameters:**
-- `files` (string|string[]) - Files to remove
-
-## Testing
-
-### Mocking the singleton
-
-```javascript
-import esmock from 'esmock'
-
-const mockGit = {
-  isAvailable: sandbox.stub().returns(true),
-  version: sandbox.stub().resolves('2.39.0'),
-}
-
-const MyCommand = await esmock('./mycommand.js', {
-  '#lib/git/index.js': { default: mockGit }
-})
-```
-
-### Mocking the Git class
-
-```javascript
-import esmock from 'esmock'
-
-const MockGit = class {
-  constructor(cwd) {
-    this.cwd = cwd
-    this.add = sandbox.stub().resolves()
-    this.clone = sandbox.stub().resolves()
-    this.commit = sandbox.stub().resolves()
-    this.init = sandbox.stub().resolves()
-    this.rm = sandbox.stub().resolves()
-  }
-}
-
-const MyCommand = await esmock('./mycommand.js', {
-  '#lib/git/index.js': { Git: MockGit }
-})
-```
+This `quire-cli/lib/git` module is a façade for interacting with `git` when creating new Quire projects and contributing to the `quire` code base, including the `quire-cli`.

package/src/lib/git/index.js

@@ -1,226 +1,22 @@
-/**
- * Git façade providing abstracted git operations
- *
- * Provides a consistent interface for git commands with unified
- * logging, error handling, and testability.
- *
- * @example using default singleton for global operations
- * import git from '#lib/git/index.js'
- * const version = await git.version()
- * if (!git.isAvailable()) { ... }
- *
- * @example using Git class for repository-scoped operations
- * import { Git } from '#lib/git/index.js'
- * const repo = new Git('/path/to/project')
- * await repo.init()
- * await repo.add('.')
- * await repo.commit('Initial commit')
- *
- * @example mocking in tests
- * const mockGit = {
- *   clone: sandbox.stub().resolves(),
- *   commit: sandbox.stub().resolves(),
- * }
- * const MyCommand = await esmock('./mycommand.js', {
- *   '#lib/git/index.js': { default: mockGit }
- * })
- *
- * @see https://git-scm.com/docs - git documentation
- * @module git
- */
-import { execa } from 'execa'
-import fs from 'node:fs'
-import path from 'node:path'
-import which from '#helpers/which.js'
-import createDebug from '#debug'
-
-const debug = createDebug('lib:git')
-
-/**
- * Check if a source string is a remote URL (vs local path)
- *
- * Git supports various remote URL formats:
- * - https://github.com/user/repo.git
- * - git@github.com:user/repo.git
- * - ssh://git@github.com/user/repo.git
- * - http://github.com/user/repo.git
- * - git://github.com/user/repo.git
- *
- * @param {string} source - Source string to check
- * @returns {boolean} True if source appears to be a remote URL
- */
-export function isRemoteUrl(source) {
-  return source.startsWith('https://') ||
-         source.startsWith('git@') ||
-         source.startsWith('ssh://') ||
-         source.startsWith('http://') ||
-         source.startsWith('git://')
-}
+import { simpleGit } from 'simple-git'
 
 /**
- * Check if a path is a git repository
- *
- * A directory is considered a git repository if it contains a .git directory.
- *
- * @param {string} dirPath - Path to check
- * @returns {boolean} True if the path is a git repository
+ * SimpleGit configuration
+ * @see https://github.com/steveukx/git-js#configuration
  */
-export function isGitRepository(dirPath) {
-  const gitDir = path.join(dirPath, '.git')
-  return fs.existsSync(gitDir)
+const options = {
+  baseDir: process.cwd(),
+  binary: 'git',
+  maxConcurrentProcesses: 6,
+  trimmed: false,
 }
 
 /**
- * Validate a clone source before attempting to clone
+ * Configured SimpleGit instance
+ * @see https://github.com/steveukx/git-js#api
  *
- * For remote URLs, validation is skipped (let git clone handle network errors).
- * For local paths, validates the path exists and is a git repository.
- *
- * @param {string} source - Clone source (URL or local path)
- * @returns {{ valid: boolean, reason?: string }} Validation result
+ * @type  {SimpleGit}
  */
-export function validateCloneSource(source) {
-  // Remote URLs are assumed valid - let git clone handle errors
-  if (isRemoteUrl(source)) {
-    return { valid: true }
-  }
-
-  // Local path validation
-  if (!fs.existsSync(source)) {
-    return { valid: false, reason: 'path does not exist' }
-  }
-
-  if (!isGitRepository(source)) {
-    return { valid: false, reason: 'not a git repository' }
-  }
-
-  return { valid: true }
-}
-
-/**
- * Git façade class
- */
-class Git {
-  /**
-   * Create a Git façade instance
-   * @param {string} [cwd] - Working directory for all operations
-   */
-  constructor(cwd) {
-    this.cwd = cwd
-  }
-
-  /**
-   * Get execa options with working directory
-   * @private
-   * @returns {Object} Options object for execa
-   */
-  #getOptions() {
-    return this.cwd ? { cwd: this.cwd } : {}
-  }
-
-  /**
-   * Get resolved working directory for logging
-   * @private
-   * @returns {string} Resolved absolute path
-   */
-  #resolvedCwd() {
-    return path.resolve(this.cwd || process.cwd())
-  }
-
-  /**
-   * Stage files for commit
-   * @see https://git-scm.com/docs/git-add
-   * @param {string|string[]} files - Files to stage (use '.' for all)
-   * @returns {Promise<void>}
-   */
-  async add(files) {
-    const fileList = Array.isArray(files) ? files : [files]
-    debug('staging files in %s: %s', this.#resolvedCwd(), fileList.join(', '))
-    const { stderr } = await execa('git', ['add', ...fileList], this.#getOptions())
-    if (stderr) {
-      debug('git add stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Clone a repository
-   * @see https://git-scm.com/docs/git-clone
-   * @param {string} url - Repository URL
-   * @param {string} [destination='.'] - Destination directory
-   * @returns {Promise<void>}
-   */
-  async clone(url, destination = '.') {
-    const resolvedDest = path.resolve(this.#resolvedCwd(), destination)
-    debug('cloning %s to %s', url, resolvedDest)
-    const { stderr } = await execa('git', ['clone', url, destination], this.#getOptions())
-    if (stderr) {
-      debug('git clone stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Create a commit
-   * @see https://git-scm.com/docs/git-commit
-   * @param {string} message - Commit message
-   * @returns {Promise<void>}
-   */
-  async commit(message) {
-    debug('committing in %s: %s...', this.#resolvedCwd(), message.substring(0, 50))
-    const { stderr } = await execa('git', ['commit', '-m', message], this.#getOptions())
-    if (stderr) {
-      debug('git commit stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Initialize a new repository
-   * @see https://git-scm.com/docs/git-init
-   * @returns {Promise<void>}
-   */
-  async init() {
-    debug('initializing repository in %s', this.#resolvedCwd())
-    const { stderr } = await execa('git', ['init'], this.#getOptions())
-    if (stderr) {
-      debug('git init stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Check if git is available in PATH
-   * @returns {boolean} True if git is available
-   */
-  isAvailable() {
-    return !!which('git')
-  }
-
-  /**
-   * Remove files from the working tree and index
-   * @see https://git-scm.com/docs/git-rm
-   * @param {string|string[]} files - Files to remove
-   * @returns {Promise<void>}
-   */
-  async rm(files) {
-    const fileList = Array.isArray(files) ? files : [files]
-    debug('removing files in %s: %s', this.#resolvedCwd(), fileList.join(', '))
-    const { stderr } = await execa('git', ['rm', ...fileList], this.#getOptions())
-    if (stderr) {
-      debug('git rm stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Get git version
-   * @see https://git-scm.com/docs/git-version
-   * @returns {Promise<string>} git version string
-   */
-  async version() {
-    const { stdout } = await execa('git', ['--version'])
-    return stdout.replace('git version ', '')
-  }
-}
-
-// Export class for repository-scoped operations
-export { Git }
+const git = simpleGit(options)
 
-// Export singleton instance for global operations
-export default new Git()
+export default git

package/src/lib/i18n/README.md

@@ -0,0 +1,3 @@
+## CLI Internationalization (i18n) & Localization Module
+
+This `quire-cli/lib/i18n` module manages localized message strings for the `quire-cli` and implements a façade for a separate i18n service.

package/src/lib/i18n/config.js

@@ -0,0 +1,53 @@
+/**
+ * i18next configuration
+ * @see https://www.i18next.com/overview/configuration-options
+ *
+ * @todo
+ * set debug using cli `--debug` option
+ * set resources by loading data files
+ */
+const configuration = {
+  debug: true,
+  /**
+   * Languages
+   */
+  fallbackLng: 'en',
+  lng: 'en',
+  supportedLngs: ['en'],
+  /**
+   * Namespaces
+   */
+  defaultNS: 'translation',
+  fallbackNS: false,
+  ns: 'translation',
+  /**
+   * Resources
+   */
+  partialBundledLanguages: false,
+  resources: {
+    en: {
+      translation: {
+        'gradoo': 'blargh',
+      }
+    },
+  },
+  /**
+   * Missing Keys
+   * @ https://www.i18next.com/overview/configuration-options#missing-keys
+   */
+  saveMissing: false,
+  /**
+   * Translation defaults
+   * @ https://www.i18next.com/overview/configuration-options#translation-defaults
+   */
+
+  /**
+   * Plugin options
+   * @see https://www.i18next.com/overview/configuration-options#plugin-options
+   */
+
+  /**
+   * Other
+   * @see https://www.i18next.com/overview/configuration-options#others
+   */
+}

package/src/lib/i18n/index.js

@@ -0,0 +1,43 @@
+import { LocaleService } from './LocaleService.js'
+import I18nextCLILanguageDetector from 'i18next-cli-language-detector'
+import i18next from 'i18next'
+
+/**
+ * i18next configuration
+ * @see https://www.i18next.com/overview/configuration-options
+ *
+ * @todo
+ * set debug using cli `--debug` option
+ * set resources by loading data files
+ */
+const configuration = {
+  debug: true,
+  /**
+   * Languages
+   */
+  fallbackLng: 'en',
+  lng: 'en',
+  supportedLngs: ['en'],
+  /**
+   * Namespaces
+   */
+  defaultNS: 'translation',
+  fallbackNS: false,
+  ns: 'translation',
+  /**
+   * Resources
+   */
+  resources: {
+    en: {
+      translation: {
+        'gradoo': 'blargh',
+      }
+    },
+  },
+}
+
+await i18next
+  .use(I18nextCLILanguageDetector)
+  .init(configuration)
+
+export default new LocaleService(i18next)

package/src/lib/i18n/localeService.js

@@ -0,0 +1,58 @@
+/**
+ * Localization service
+ *
+ * @class  LocaleService
+ */
+export class LocaleService {
+  /**
+   * @param  {Object}  i18nProvider
+   */
+  constructor(i18nProvider) {
+    this.i18nProvider = i18nProvider
+  }
+
+  /**
+   * Gets the current locale
+   *
+   * @return  {String}  current locale code
+   */
+  getCurrentLocale() {
+    return this.i18nProvider.getLocale()
+  }
+
+  /**
+   * Get a list of supported locales
+   *
+   * @return {Array}  List of supported locale codes
+   */
+  getLocales() {
+    return this.i18nProvider.getLocales()
+  }
+
+  /**
+   * Sets the current locale
+   *
+   * @param  {String}  locale  i18n locale code
+   * @return  {String}  the current locale code
+   */
+  setLocale(locale) {
+    const locales = this.getLocales()
+    if (!locales.includes(locale)) {
+      throw new Error(`
+        Unknown locale code ${locale} Unable to set current locale;
+        supported locales: ${locales}
+      `)
+    }
+    return this.i18nProvider.setLocale(locale)
+  }
+
+  /**
+   * Translate a string
+   *
+   * @param  {String}  string   string to translate
+   * @param  {Object}  options  translation options
+   */
+  translate(string, options) {
+    return this.i18nProvider.t(string)
+  }
+}

package/src/lib/pdf/README.md

@@ -2,66 +2,6 @@
 
 This module provides an abstraction to ease PDF generation across PrinceXML and Paged.js. The exported module dynamically loads a wrapper to align the libraries' JS APIs by exporting a single method that accepts a `lib` option and returns an async function that takes input, output, and option params.
 
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      lib/pdf/index.js                       │
-│  • Façade: resolves engine, validates prerequisites         │
-│  • Checks engine availability (fail-fast before reporter)   │
-│  • Owns reporter lifecycle (start/succeed/fail)             │
-└─────────────────┬─────────────────────────┬─────────────────┘
-                  │                         │
-        ┌─────────┴─────────┐     ┌─────────┴─────────┐
-        │   paged.js        │     │    prince.js      │
-        │   (Paged.js CLI)  │     │   (Prince CLI)    │
-        └─────────┬─────────┘     └─────────┬─────────┘
-                  │                         │
-                  └───────────┬─────────────┘
-                              │
-                    ┌─────────┴─────────┐
-                    │     split.js      │
-                    │  (pdf-lib logic)  │
-                    └───────────────────┘
-```
-
-### Usage
-
-```javascript
-import generatePdf from '#lib/pdf/index.js'
-
-// Basic usage (uses project config for output path)
-const pdfPath = await generatePdf({ lib: 'pagedjs' })
-
-// With custom output path
-const pdfPath = await generatePdf({
-  lib: 'prince',
-  output: 'downloads/my-book.pdf'  // relative to project root
-})
-
-// With absolute path
-const pdfPath = await generatePdf({
-  lib: 'pagedjs',
-  output: '/tmp/publication.pdf'
-})
-```
-
-### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `lib` | string | `'pagedjs'` | PDF engine: `'pagedjs'` or `'prince'` |
-| `output` | string | from config | Output path (overrides project config) |
-| `debug` | boolean | `false` | Enable debug output |
-
-### Output Path Resolution
-
-1. If `options.output` is provided, it is used (relative paths resolved against project root)
-2. Otherwise, uses `config.pdf.outputDir` + `config.pdf.filename` from project config
-3. If no config, falls back to `{projectRoot}/{libName}.pdf`
-
-### Page Mapping
-
 The module also provides plugins for Prince and Paged.js to map quire webpages to PDF pages. In both cases this is achieved after PDF rendering by querying the HTML document that was printed for `.quire-page` elements and using the PDF generator's APIs to determine content page ids, page data like titles and contributors, and first / last pages. They then use a simple stripping algorithm with `pdf-lib` to split the pages for `--page-pdf` flagged runs.
 
 ### Paged.js Façade
@@ -77,74 +17,3 @@ The Prince abstraction wraps the command line execution of the Prince executable
 See the [Prince Command-line Reference](https://www.princexml.com/doc/command-line/). Prince's [scripting documentation](https://www.princexml.com/doc/javascript/) has details on its runtime Javascript implementation, *which is only compatible up to ES5*.
 
 The Prince plugin passes page map data as JSON to STDOUT.
-
-### Test Strategy
-
-The PDF module uses a layered testing approach:
-
-| Layer | Test Type | Coverage |
-|-------|-----------|----------|
-| `index.js` | Unit tests | Engine resolution, path resolution, availability checks |
-| `paged.js` | Integration tests | Error paths (Puppeteer failures, file write errors) |
-| `prince.js` | Integration tests | Error paths (Prince failures, cancellation handling) |
-| `split.js` | Unit tests | Pure PDF manipulation logic with mocked pdf-lib |
-| Full flow | E2E tests | Happy paths with real tools |
-
-#### Why This Strategy?
-
-**Façade (`index.js`)** - Unit tests verify:
-- Engine name normalization (`pagedjs`, `paged`, `paged.js` → same engine)
-- Output path resolution priority (CLI > config > fallback)
-- Engine availability checking (Prince binary in PATH)
-- Error handling for missing prerequisites
-
-**Engine implementations (`paged.js`, `prince.js`)** - Integration tests for error paths:
-- These are orchestration code that wire external tools (Puppeteer, Prince CLI) with reporter updates
-- Happy paths are well-covered by E2E tests with real tools
-- Error paths (tool crashes, permission errors, cancellation) are hard to trigger in E2E
-- Tests mock `execa`/`pagedjs-cli` to verify error wrapping and cleanup
-
-**PDF splitting (`split.js`)** - Unit tests:
-- Pure logic that manipulates PDFs using pdf-lib
-- No external tool dependencies
-- Tests mock pdf-lib's `PDFDocument` to verify page extraction, cover insertion, and error handling
-
-**E2E tests** - Full integration:
-- Test the complete `quire pdf` command with real publications
-- Verify actual PDF output with both engines (when available)
-- Cover the happy path that unit/integration tests intentionally skip
-
-#### Running Tests
-
-```bash
-# All PDF module tests
-npm run test:unit -- src/lib/pdf/
-
-# Specific test files
-npm run test:unit -- src/lib/pdf/index.test.js    # façade tests
-npm run test:unit -- src/lib/pdf/paged.test.js    # Paged.js error paths
-npm run test:unit -- src/lib/pdf/prince.test.js   # Prince error paths
-npm run test:unit -- src/lib/pdf/split.test.js    # PDF splitting logic
-```
-
-### Error Handling
-
-All errors are wrapped in typed `PdfGenerationError` with:
-- Tool name (`'Prince'`, `'Paged.js'`)
-- Operation that failed (`'PDF rendering'`, `'page map extraction'`, etc.)
-- Underlying error details
-
-Example error flow:
-```
-Prince CLI fails → execa rejects with stderr
-  → prince.js catches, wraps in PdfGenerationError
-    → index.js catches, calls reporter.fail(), re-throws
-      → Command handler displays formatted error to user
-```
-
-### Graceful Shutdown
-
-Both engines support Ctrl+C cancellation:
-- `prince.js` uses `execa`'s `cancelSignal` option
-- `paged.js` registers cleanup with `processManager.onShutdown()`
-- On cancellation, `reporter.warn('PDF generation cancelled')` notifies the user