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

package/src/lib/npm/index.js

@@ -1,198 +0,0 @@
-/**
- * NPM façade class providing abstracted npm operations
- *
- * Provides a consistent interface for npm commands with unified
- * logging, error handling, and testability. Follows the singleton
- * pattern like lib/logger.js for easy mocking in tests.
- *
- * @example in production code
- * import npm from '#lib/npm/index.js'
- * await npm.install(projectPath, { saveDev: true })
- *
- * @example in test code
- * const mockNpm = {
- *   install: sandbox.stub().resolves(),
- *   version: sandbox.stub().resolves('10.2.4')
- * }
- * const MyCommand = await esmock('./mycommand.js', {
- *   '#lib/npm/index.js': { default: mockNpm }
- * })
- *
- * @see https://docs.npmjs.com/cli/ - npm CLI documentation
- * @module npm
- */
-import { execa } from 'execa'
-import fetch from 'node-fetch'
-import semver from 'semver'
-import which from '#helpers/which.js'
-import createDebug from '#debug'
-
-const debug = createDebug('lib:npm')
-
-/**
- * NPM façade class
- */
-class Npm {
-  /**
-   * Clean npm cache
-   * @see https://docs.npmjs.com/cli/commands/npm-cache
-   * @param {string} [cwd] - Working directory (optional)
-   * @returns {Promise<void>}
-   */
-  async cacheClean(cwd) {
-    debug('cleaning npm cache')
-    const options = cwd ? { cwd } : {}
-    const { stderr } = await execa('npm', ['cache', 'clean', '--force'], options)
-    if (stderr) {
-      debug('npm cache clean stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Fetch package metadata directly from npm registry
-   * @see https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
-   * @param {string} packageName - Package name
-   * @returns {Promise<Object>} Package metadata from registry
-   */
-  async fetchFromRegistry(packageName) {
-    debug('fetching registry metadata for %s', packageName)
-    const response = await fetch(`https://registry.npmjs.org/${packageName}`)
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch package metadata for ${packageName}: ${response.statusText}`
-      )
-    }
-    return await response.json()
-  }
-
-  /**
-   * Get latest version compatible with a semver range
-   * @see https://docs.npmjs.com/about-semantic-versioning
-   * @see https://github.com/npm/node-semver#ranges
-   * @param {string} packageName - Package name
-   * @param {string} range - Semver range (e.g., "^1.0.0")
-   * @returns {Promise<string|null>} Latest compatible version or null if none found
-   */
-  async getCompatibleVersion(packageName, range) {
-    debug('finding version of %s compatible with %s', packageName, range)
-    const metadata = await this.fetchFromRegistry(packageName)
-    const versions = Object.keys(metadata.versions)
-    return semver.maxSatisfying(versions, range)
-  }
-
-  /**
-   * Initialize a new package.json
-   * @see https://docs.npmjs.com/cli/commands/npm-init
-   * @param {string} cwd - Working directory
-   * @param {Object} options - Configuration options
-   * @param {boolean} [options.yes=true] - Auto-accept defaults
-   * @returns {Promise<void>}
-   */
-  async init(cwd, options = {}) {
-    const { yes = true } = options
-    const args = ['init']
-    if (yes) args.push('--yes')
-
-    debug('initializing package.json in %s', cwd)
-    const { stderr } = await execa('npm', args, { cwd })
-    if (stderr) {
-      debug('npm init stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Install dependencies
-   * @see https://docs.npmjs.com/cli/commands/npm-install
-   * @param {string} cwd - Working directory
-   * @param {Object} options - Configuration options
-   * @param {boolean} [options.saveDev=false] - Install as devDependencies
-   * @param {boolean} [options.preferOffline=false] - Prefer cached packages
-   * @returns {Promise<void>}
-   */
-  async install(cwd, options = {}) {
-    const { preferOffline = false, saveDev = false } = options
-    const args = ['install']
-    if (preferOffline) args.push('--prefer-offline')
-    if (saveDev) args.push('--save-dev')
-
-    debug('installing dependencies in %s', cwd)
-    const { stderr } = await execa('npm', args, { cwd })
-    if (stderr) {
-      debug('npm install stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Check if npm is available in PATH
-   * @returns {boolean} True if npm is available
-   */
-  isAvailable() {
-    return !!which('npm')
-  }
-
-  /**
-   * Create a tarball (.tgz file) of the npm package
-   * @see https://docs.npmjs.com/cli/commands/npm-pack
-   * @param {string} packageSpec - Package name with version (e.g., "@thegetty/quire-11ty@1.0.0")
-   * @param {string} destination - Destination directory for the tarball
-   * @param {Object} options - Configuration options
-   * @param {boolean} [options.quiet=true] - Suppress output
-   * @param {boolean} [options.debug=false] - Enable debug output
-   * @returns {Promise<void>}
-   */
-  async pack(packageSpec, destination, options = {}) {
-    const { debug: debugMode = false, quiet = true } = options
-    const args = ['pack']
-    if (debugMode) {
-      args.push('--debug')
-    } else if (quiet) {
-      args.push('--quiet')
-    }
-    args.push('--pack-destination', destination, packageSpec)
-
-    debug('packing %s to %s', packageSpec, destination)
-    const { stderr } = await execa('npm', args)
-    if (stderr) {
-      debug('npm pack stderr: %s', stderr)
-    }
-  }
-
-  /**
-   * Show package info (similar to view)
-   * @see https://docs.npmjs.com/cli/commands/npm-view
-   * @param {string} packageName - Package name
-   * @param {string} [field='versions'] - Field to retrieve
-   * @returns {Promise<string>} The requested field value
-   */
-  async show(packageName, field = 'versions') {
-    debug('showing %s for %s', field, packageName)
-    const result = await execa('npm', ['show', packageName, field])
-    return result
-  }
-
-  /**
-   * Get npm version
-   * @see https://docs.npmjs.com/cli/commands/npm-version
-   * @returns {Promise<string>} npm version string
-   */
-  async version() {
-    const { stdout } = await execa('npm', ['--version'])
-    return stdout
-  }
-
-  /**
-   * View package info from registry
-   * @see https://docs.npmjs.com/cli/commands/npm-view
-   * @param {string} packageName - Package name
-   * @param {string} [field='version'] - Field to retrieve
-   * @returns {Promise<string>} The requested field value
-   */
-  async view(packageName, field = 'version') {
-    debug('viewing %s for %s', field, packageName)
-    const { stdout } = await execa('npm', ['view', packageName, field])
-    return stdout
-  }
-}
-
-// Export singleton instance
-export default new Npm()

package/src/lib/npm/index.spec.js

@@ -1,60 +0,0 @@
-import test from 'ava'
-import npm from './index.js'
-
-/**
- * NPM Façade Unit Tests
- *
- * Tests the npm façade module interface and API contract.
- * These tests verify the module exports and method signatures
- * without actually executing npm commands.
- */
-
-test('npm façade exports a singleton object', (t) => {
-  t.truthy(npm, 'npm should be exported')
-  t.is(typeof npm, 'object', 'npm should be an object')
-})
-
-test('npm façade has isAvailable method', (t) => {
-  t.is(typeof npm.isAvailable, 'function', 'isAvailable should be a function')
-})
-
-test('npm façade has version method', (t) => {
-  t.is(typeof npm.version, 'function', 'version should be a function')
-})
-
-test('npm façade has init method', (t) => {
-  t.is(typeof npm.init, 'function', 'init should be a function')
-})
-
-test('npm façade has install method', (t) => {
-  t.is(typeof npm.install, 'function', 'install should be a function')
-})
-
-test('npm façade has pack method', (t) => {
-  t.is(typeof npm.pack, 'function', 'pack should be a function')
-})
-
-test('npm façade has cacheClean method', (t) => {
-  t.is(typeof npm.cacheClean, 'function', 'cacheClean should be a function')
-})
-
-test('npm façade has view method', (t) => {
-  t.is(typeof npm.view, 'function', 'view should be a function')
-})
-
-test('npm façade has show method', (t) => {
-  t.is(typeof npm.show, 'function', 'show should be a function')
-})
-
-test('npm façade has fetchFromRegistry method', (t) => {
-  t.is(typeof npm.fetchFromRegistry, 'function', 'fetchFromRegistry should be a function')
-})
-
-test('npm façade has getCompatibleVersion method', (t) => {
-  t.is(typeof npm.getCompatibleVersion, 'function', 'getCompatibleVersion should be a function')
-})
-
-test('isAvailable returns a boolean', (t) => {
-  const result = npm.isAvailable()
-  t.is(typeof result, 'boolean', 'isAvailable should return a boolean')
-})

package/src/lib/npm/index.test.js

@@ -1,355 +0,0 @@
-import esmock from 'esmock'
-import sinon from 'sinon'
-import test from 'ava'
-
-/**
- * NPM Façade Integration Tests
- *
- * Tests the npm façade module behavior with mocked dependencies.
- * Uses esmock to replace execa and node-fetch calls.
- */
-
-test.beforeEach((t) => {
-  t.context.sandbox = sinon.createSandbox()
-})
-
-test.afterEach.always((t) => {
-  t.context.sandbox.restore()
-})
-
-test('version() calls npm --version and returns stdout', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({ stdout: '10.2.4' })
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = await npm.version()
-
-  t.is(result, '10.2.4')
-  t.true(mockExeca.calledOnce)
-  t.true(mockExeca.calledWith('npm', ['--version']))
-})
-
-test('init() calls npm init with --yes flag by default', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.init('/path/to/project')
-
-  t.true(mockExeca.calledOnce)
-  t.true(mockExeca.calledWith('npm', ['init', '--yes'], { cwd: '/path/to/project' }))
-})
-
-test('init() omits --yes flag when yes option is false', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.init('/path/to/project', { yes: false })
-
-  t.true(mockExeca.calledWith('npm', ['init'], { cwd: '/path/to/project' }))
-})
-
-test('install() calls npm install with correct flags', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.install('/path/to/project', { saveDev: true, preferOffline: true })
-
-  t.true(mockExeca.calledOnce)
-  t.true(mockExeca.calledWith('npm', ['install', '--prefer-offline', '--save-dev'], { cwd: '/path/to/project' }))
-})
-
-test('install() calls npm install without flags when no options provided', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.install('/path/to/project')
-
-  t.true(mockExeca.calledWith('npm', ['install'], { cwd: '/path/to/project' }))
-})
-
-test('pack() calls npm pack with package spec and destination', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.pack('@thegetty/quire-11ty@1.0.0', '/tmp/dest', { quiet: true })
-
-  t.true(mockExeca.calledOnce)
-  t.true(mockExeca.calledWith('npm', ['pack', '--quiet', '--pack-destination', '/tmp/dest', '@thegetty/quire-11ty@1.0.0']))
-})
-
-test('pack() uses --debug flag when debug option is true', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.pack('@thegetty/quire-11ty@1.0.0', '/tmp/dest', { debug: true, quiet: false })
-
-  t.true(mockExeca.calledWith('npm', ['pack', '--debug', '--pack-destination', '/tmp/dest', '@thegetty/quire-11ty@1.0.0']))
-})
-
-test('cacheClean() calls npm cache clean --force', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({})
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.cacheClean('/path/to/project')
-
-  t.true(mockExeca.calledOnce)
-  t.true(mockExeca.calledWith('npm', ['cache', 'clean', '--force'], { cwd: '/path/to/project' }))
-})
-
-test('view() calls npm view with package name and field', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({ stdout: '1.0.0' })
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = await npm.view('@thegetty/quire-11ty', 'version')
-
-  t.is(result, '1.0.0')
-  t.true(mockExeca.calledWith('npm', ['view', '@thegetty/quire-11ty', 'version']))
-})
-
-test('show() calls npm show with package name and field', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({ stdout: "['1.0.0', '1.0.1']" })
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await npm.show('@thegetty/quire-11ty', 'versions')
-
-  t.true(mockExeca.calledWith('npm', ['show', '@thegetty/quire-11ty', 'versions']))
-})
-
-test('fetchFromRegistry() fetches package metadata from npm registry', async (t) => {
-  const { sandbox } = t.context
-
-  const mockResponse = {
-    ok: true,
-    json: sandbox.stub().resolves({
-      name: '@thegetty/quire-11ty',
-      versions: { '1.0.0': {}, '1.0.1': {} }
-    })
-  }
-  const mockFetch = sandbox.stub().resolves(mockResponse)
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    'node-fetch': { default: mockFetch },
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = await npm.fetchFromRegistry('@thegetty/quire-11ty')
-
-  t.deepEqual(result, { name: '@thegetty/quire-11ty', versions: { '1.0.0': {}, '1.0.1': {} } })
-  t.true(mockFetch.calledWith('https://registry.npmjs.org/@thegetty/quire-11ty'))
-})
-
-test('fetchFromRegistry() throws error when response is not ok', async (t) => {
-  const { sandbox } = t.context
-
-  const mockResponse = {
-    ok: false,
-    statusText: 'Not Found'
-  }
-  const mockFetch = sandbox.stub().resolves(mockResponse)
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    'node-fetch': { default: mockFetch },
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  await t.throwsAsync(
-    () => npm.fetchFromRegistry('nonexistent-package'),
-    { message: /Failed to fetch package metadata/ }
-  )
-})
-
-test('getCompatibleVersion() returns latest version matching semver range', async (t) => {
-  const { sandbox } = t.context
-
-  const mockResponse = {
-    ok: true,
-    json: sandbox.stub().resolves({
-      versions: {
-        '1.0.0': {},
-        '1.0.1': {},
-        '1.1.0': {},
-        '2.0.0': {}
-      }
-    })
-  }
-  const mockFetch = sandbox.stub().resolves(mockResponse)
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    'node-fetch': { default: mockFetch },
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = await npm.getCompatibleVersion('@thegetty/quire-11ty', '^1.0.0')
-
-  t.is(result, '1.1.0')
-})
-
-test('getCompatibleVersion() returns null when no compatible version found', async (t) => {
-  const { sandbox } = t.context
-
-  const mockResponse = {
-    ok: true,
-    json: sandbox.stub().resolves({
-      versions: {
-        '2.0.0': {},
-        '3.0.0': {}
-      }
-    })
-  }
-  const mockFetch = sandbox.stub().resolves(mockResponse)
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    'node-fetch': { default: mockFetch },
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = await npm.getCompatibleVersion('@thegetty/quire-11ty', '^1.0.0')
-
-  t.is(result, null)
-})
-
-test('isAvailable() returns true when npm is found in PATH', async (t) => {
-  const { sandbox } = t.context
-
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = npm.isAvailable()
-
-  t.true(result)
-  t.true(mockWhich.calledWith('npm'))
-})
-
-test('isAvailable() returns false when npm is not found in PATH', async (t) => {
-  const { sandbox } = t.context
-
-  const mockWhich = sandbox.stub().returns(null)
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: sandbox.stub() },
-    '#helpers/which.js': { default: mockWhich }
-  })
-
-  const result = npm.isAvailable()
-
-  t.false(result)
-})
-
-test('install() logs stderr via debug when present', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({ stderr: 'npm WARN deprecated' })
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-  const mockDebug = sandbox.stub()
-  const mockCreateDebug = sandbox.stub().returns(mockDebug)
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich },
-    '#debug': { default: mockCreateDebug }
-  })
-
-  await npm.install('/path/to/project')
-
-  t.true(mockDebug.calledWith('npm install stderr: %s', 'npm WARN deprecated'))
-})
-
-test('cacheClean() logs stderr via debug when present', async (t) => {
-  const { sandbox } = t.context
-
-  const mockExeca = sandbox.stub().resolves({ stderr: 'cache warning' })
-  const mockWhich = sandbox.stub().returns('/usr/bin/npm')
-  const mockDebug = sandbox.stub()
-  const mockCreateDebug = sandbox.stub().returns(mockDebug)
-
-  const npm = await esmock('./index.js', {
-    execa: { execa: mockExeca },
-    '#helpers/which.js': { default: mockWhich },
-    '#debug': { default: mockCreateDebug }
-  })
-
-  await npm.cacheClean('/path/to/project')
-
-  t.true(mockDebug.calledWith('npm cache clean stderr: %s', 'cache warning'))
-})

package/src/lib/pdf/engines.js

@@ -1,46 +0,0 @@
-/**
- * PDF Engine Registry
- *
- * Centralized metadata for PDF engines. Each engine module re-exports
- * its metadata from here, ensuring single source of truth.
- *
- * The façade imports this registry to:
- * 1. Resolve engine names to implementations
- * 2. Check binary availability before loading heavy modules
- * 3. Provide helpful error messages with install URLs
- */
-import { docsUrl } from '#helpers/docs-url.js'
-
-/**
- * @typedef {Object} EngineMetadata
- * @property {string} name - Human-readable display name
- * @property {string} module - Module filename (e.g., 'paged.js')
- * @property {string|null} requiresBinary - CLI binary name, or null if built-in
- * @property {Object} [toolInfo] - Error metadata (only for engines requiring binaries)
- * @property {string} [toolInfo.displayName] - Display name for error messages
- * @property {string} [toolInfo.installUrl] - URL to download the tool
- * @property {string} [toolInfo.docsUrl] - Quire docs URL
- * @property {string} [toolInfo.fallback] - Alternative suggestion
- */
-
-/** @type {Record<string, EngineMetadata>} */
-const ENGINES = {
-  pagedjs: {
-    name: 'Paged.js',
-    module: 'paged.js',
-    requiresBinary: null, // Built-in Node.js library
-  },
-  prince: {
-    name: 'Prince',
-    module: 'prince.js',
-    requiresBinary: 'prince',
-    toolInfo: {
-      displayName: 'PrinceXML',
-      installUrl: 'https://www.princexml.com/download/',
-      docsUrl: docsUrl('pdf-output'),
-      fallback: 'Or use the default PDF engine: quire pdf --engine pagedjs',
-    },
-  },
-}
-
-export default ENGINES