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

package/src/commands/create.js

@@ -1,6 +1,10 @@
 import Command from '#src/Command.js'
+import { Option } from 'commander'
+import { withOutputModes } from '#lib/commander/index.js'
 import fs from 'fs-extra'
-import { quire } from '#src/lib/quire/index.js'
+import { installer } from '#lib/installer/index.js'
+import { DirectoryNotEmptyError, ProjectCreateError } from '#src/errors/index.js'
+import reporter from '#lib/reporter/index.js'
 
 /**
  * Quire CLI `new` Command
@@ -13,10 +17,17 @@ import { quire } from '#src/lib/quire/index.js'
  * @extends    {Command}
  */
 export default class CreateCommand extends Command {
-  static definition = {
+  static definition = withOutputModes({
     name: 'new',
     description: 'Start a new Quire project from a template.',
     summary: 'create a new project',
+    docsLink: 'quire-commands/#start-and-preview-projects',
+    helpText: `
+Examples:
+  quire new my-project                        Use default starter
+  quire new my-project --quire-version 1.0.0  Pin quire-11ty version
+  quire new my-project --verbose              Create with detailed progress
+`,
     version: '1.0.0',
     args: [
       [ '[projectPath]', 'local path to the new project', '.' ],
@@ -25,10 +36,10 @@ export default class CreateCommand extends Command {
     options: [
       [ '--quire-path <path>', 'local path to quire-11ty package' ],
       [ '--quire-version <version>', 'quire-11ty version to install' ],
-      // [ '--eject', 'install quire-11ty into the project directory', true ],
-      [ '--debug', 'debug the `quire new` command', false ],
+      // Use Option object syntax to configure this as a hidden option
+      new Option('--clean-cache', 'force clean the npm cache').default(false).hideHelp(),
     ],
-  }
+  })
 
   constructor() {
     super(CreateCommand.definition)
@@ -41,15 +52,16 @@ export default class CreateCommand extends Command {
    * @return     {Promise}
    */
   async action(projectPath, starter, options = {}) {
-    if (options.debug) {
-      console.info('Command \'%s\' called with options %o', CreateCommand.name, options)
-    }
+    this.debug('called with options %O', options)
+
+    // Configure reporter for this command
+    reporter.configure({ quiet: options.quiet, verbose: options.verbose })
 
     starter = starter || this.config.get('projectTemplate')
 
     if (!projectPath && !starter) {
       // @TODO implement this case of interactively selecting starter templates
-      // from available subtrees in `lib/quire` module
+      // from available subtrees in `lib/installer` module
 
       // await interactivePrompt()
       // list sub-repositories in '@thegetty/quire/packages/starters'
@@ -65,14 +77,30 @@ export default class CreateCommand extends Command {
        */
       let quireVersion
       try {
-        quireVersion = await quire.initStarter(starter, projectPath, options)
+        quireVersion = await installer.initStarter(starter, projectPath, options)
       } catch (error) {
-        console.error(error.message)
-        fs.removeSync(projectPath)
-        return
+        reporter.fail('Failed to initialize project')
+        this.logger.error(error.message)
+        /**
+         * Nota bene: Auto-deletion of projectPath is disabled to prevent accidental data loss.
+         * @TODO implement safe cleaup that either tracks whether quire created the directory,
+         * or prompt the user for confirmation before deleting any files.
+         */
+        // if (!(error instanceof DirectoryNotEmptyError)) {
+        //   fs.removeSync(projectPath)
+        // }
+        throw new ProjectCreateError(projectPath, error.message)
+      }
+
+      // Check if initStarter returned without a version
+      if (!quireVersion) {
+        // Nota bene: Auto-deletion disabled - see comment above
+        // fs.removeSync(projectPath)
+        throw new ProjectCreateError(projectPath, 'Failed to determine Quire version')
       }
 
-      await quire.installInProject(projectPath, quireVersion, options)
+      await installer.installInProject(projectPath, quireVersion, options)
+      reporter.succeed('Project created successfully')
     }
   }
 }

package/src/commands/create.spec.js

@@ -0,0 +1,112 @@
+import { Argument, Command, Option } from 'commander'
+import program from '#src/main.js'
+import test from 'ava'
+
+/**
+ * Command Contract/Interface Tests
+ *
+ * Verifies the command's public API and Commander.js integration.
+ * @see docs/testing-commands.md
+ */
+
+test.before((t) => {
+  // Get the registered command (from program.commands) once and share across all tests
+  t.context.command = program.commands.find((cmd) => cmd.name() === 'new')
+})
+
+test('command is registered in CLI program', (t) => {
+  const { command } = t.context
+
+  t.truthy(command, 'command "new" should be registered in program')
+  t.true(command instanceof Command, 'registered command should be Commander.js Command instance')
+})
+
+test('registered command has correct metadata', (t) => {
+  const { command } = t.context
+
+  t.is(command.name(), 'new')
+  t.truthy(command.description())
+  t.is(typeof command._actionHandler, 'function', 'command should have action handler')
+})
+
+test('registered command has correct arguments', (t) => {
+  const { command } = t.context
+  const registeredArguments = command.registeredArguments
+
+  t.is(registeredArguments.length, 2, 'command should have 2 arguments')
+
+  // First argument: projectPath
+  const projectPath = registeredArguments[0]
+  t.true(projectPath instanceof Argument, 'projectPath should be Argument instance')
+  t.is(projectPath.name(), 'projectPath', 'first argument should be projectPath')
+  t.false(projectPath.required, 'projectPath should be optional')
+  t.truthy(projectPath.description)
+
+  // Second argument: starter
+  const starter = registeredArguments[1]
+  t.true(starter instanceof Argument, 'starter should be Argument instance')
+  t.is(starter.name(), 'starter', 'second argument should be starter')
+  t.false(starter.required, 'starter should be optional')
+  t.truthy(starter.description)
+})
+
+test('registered command has correct options', (t) => {
+  const { command } = t.context
+
+  // Get all options
+  const quirePathOption = command.options.find((opt) => opt.long === '--quire-path')
+  const quireVersionOption = command.options.find((opt) => opt.long === '--quire-version')
+  const quietOption = command.options.find((opt) => opt.long === '--quiet')
+  const verboseOption = command.options.find((opt) => opt.long === '--verbose')
+  const debugOption = command.options.find((opt) => opt.long === '--debug')
+
+  // Verify all options exist
+  t.truthy(quirePathOption, '--quire-path option should exist')
+  t.truthy(quireVersionOption, '--quire-version option should exist')
+  t.truthy(quietOption, '--quiet option should exist')
+  t.truthy(verboseOption, '--verbose option should exist')
+  t.truthy(debugOption, '--debug option should exist')
+
+  // Verify they are Option instances
+  t.true(quirePathOption instanceof Option, '--quire-path should be Option instance')
+  t.true(quireVersionOption instanceof Option, '--quire-version should be Option instance')
+  t.true(quietOption instanceof Option, '--quiet should be Option instance')
+  t.true(verboseOption instanceof Option, '--verbose should be Option instance')
+  t.true(debugOption instanceof Option, '--debug should be Option instance')
+
+  // Verify option properties
+  t.is(quirePathOption.long, '--quire-path')
+  t.truthy(quirePathOption.description)
+  t.true(quirePathOption.required, '--quire-path should require a value')
+
+  t.is(quireVersionOption.long, '--quire-version')
+  t.truthy(quireVersionOption.description)
+  t.true(quireVersionOption.required, '--quire-version should require a value')
+
+  t.is(quietOption.long, '--quiet')
+  t.is(quietOption.short, '-q', '--quiet should have -q short flag')
+  t.truthy(quietOption.description)
+  t.false(quietOption.required, '--quiet should not require a value')
+
+  t.is(verboseOption.long, '--verbose')
+  t.is(verboseOption.short, '-v', '--verbose should have -v short flag')
+  t.truthy(verboseOption.description)
+  t.false(verboseOption.required, '--verbose should not require a value')
+
+  t.is(debugOption.long, '--debug')
+  t.truthy(debugOption.description)
+  t.false(debugOption.required, '--debug should not require a value')
+})
+
+test('command options are accessible via public API', (t) => {
+  const { command } = t.context
+
+  // Test that options can be accessed the way Commander.js does
+  const optionNames = command.options.map((opt) => opt.long)
+
+  t.true(optionNames.includes('--quire-path'))
+  t.true(optionNames.includes('--quire-version'))
+  t.true(optionNames.includes('--quiet'))
+  t.true(optionNames.includes('--verbose'))
+  t.true(optionNames.includes('--debug'))
+})

package/src/commands/create.test.js

@@ -0,0 +1,415 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+import { Volume, createFsFromVolume } from 'memfs'
+
+test.beforeEach((t) => {
+  // Create sinon sandbox for mocking
+  t.context.sandbox = sinon.createSandbox()
+
+  // Create in-memory file system
+  t.context.vol = new Volume()
+  t.context.fs = createFsFromVolume(t.context.vol)
+
+  // Setup mock directory structure
+  t.context.vol.fromJSON({
+    '/starter-template/content/_data/config.yaml': 'title: Starter Template',
+    '/starter-template/package.json': JSON.stringify({ name: 'starter-template' })
+  })
+
+  t.context.projectRoot = '/new-project'
+
+  // Create mock logger (no global console stubbing needed!)
+  t.context.mockLogger = {
+    info: t.context.sandbox.stub(),
+    error: t.context.sandbox.stub(),
+    debug: t.context.sandbox.stub(),
+    log: t.context.sandbox.stub(),
+    warn: t.context.sandbox.stub()
+  }
+
+  // Create mock reporter
+  t.context.mockReporter = {
+    configure: t.context.sandbox.stub().returnsThis(),
+    start: t.context.sandbox.stub().returnsThis(),
+    update: t.context.sandbox.stub().returnsThis(),
+    succeed: t.context.sandbox.stub().returnsThis(),
+    fail: t.context.sandbox.stub().returnsThis(),
+    stop: t.context.sandbox.stub().returnsThis(),
+  }
+})
+
+test.afterEach.always((t) => {
+  // Restore all mocks
+  t.context.sandbox.restore()
+
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
+
+test('create command should initialize starter and install quire', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().callsFake(async (starter, projectPath) => {
+      // Simulate creating project directory
+      fs.mkdirSync(projectPath, { recursive: true })
+      fs.writeFileSync(`${projectPath}/package.json`, JSON.stringify({ name: 'new-project' }))
+      return '1.0.0'
+    }),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('default-starter')
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': {
+      installer: mockQuire
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  // Run action
+  await command.action('/new-project', 'starter-template', {})
+
+  t.true(mockQuire.initStarter.called, 'initStarter should be called')
+  t.true(mockQuire.initStarter.calledWith('starter-template', '/new-project'), 'initStarter should be called with correct arguments')
+  t.true(mockQuire.installInProject.called, 'installInProject should be called')
+  t.true(mockQuire.installInProject.calledWith('/new-project', '1.0.0'), 'installInProject should be called with project path and version')
+  t.true(mockReporter.configure.called, 'reporter.configure should be called')
+  t.true(mockReporter.succeed.called, 'reporter.succeed should be called on success')
+})
+
+test('create command should use default starter from config when not provided', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().callsFake(async (starter, projectPath) => {
+      fs.mkdirSync(projectPath, { recursive: true })
+      fs.writeFileSync(`${projectPath}/package.json`, JSON.stringify({ name: 'new-project' }))
+      return '1.0.0'
+    }),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('https://github.com/thegetty/quire-starter-default')
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': {
+      installer: mockQuire
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  // Run action without starter argument
+  await command.action('/new-project', null, {})
+
+  t.true(mockConfig.get.calledWith('projectTemplate'), 'config.get should be called for projectTemplate')
+  t.true(mockQuire.initStarter.calledWith('https://github.com/thegetty/quire-starter-default', '/new-project'), 'initStarter should use default starter from config')
+})
+
+test('create command should pass quire-version option to installInProject', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().callsFake(async (starter, projectPath) => {
+      fs.mkdirSync(projectPath, { recursive: true })
+      fs.writeFileSync(`${projectPath}/package.json`, JSON.stringify({ name: 'new-project' }))
+      return '1.0.0-rc.10'
+    }),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('default-starter')
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': {
+      installer: mockQuire
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const options = { quireVersion: '1.0.0-rc.10' }
+
+  // Run action with quire-version option
+  await command.action('/new-project', 'starter-template', options)
+
+  t.true(mockQuire.installInProject.called, 'installInProject should be called')
+  const installCall = mockQuire.installInProject.getCall(0)
+  t.true(installCall.args[2] === options, 'installInProject should receive options object')
+})
+
+test('create command should handle initStarter errors gracefully', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  const error = new Error('Failed to initialize starter template')
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().rejects(error),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('default-starter')
+  }
+
+  // Add removeSync to fs if it doesn't exist (memfs compatibility)
+  if (!fs.removeSync) {
+    fs.removeSync = sandbox.stub().callsFake((path) => {
+      if (fs.existsSync(path)) {
+        fs.rmSync(path, { recursive: true, force: true })
+      }
+    })
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': {
+      installer: mockQuire
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  // Run action - should throw ProjectCreateError
+  // Note: We check error properties instead of instanceOf because esmock creates
+  // a separate module instance with its own class reference
+  const thrown = await t.throwsAsync(
+    () => command.action('/new-project', 'starter-template', {})
+  )
+
+  t.is(thrown.name, 'ProjectCreateError', 'error should be ProjectCreateError')
+  t.is(thrown.code, 'PROJECT_CREATE_FAILED', 'error should have correct code')
+  t.is(thrown.exitCode, 2, 'error should have correct exit code')
+  t.true(mockQuire.initStarter.called, 'initStarter should be called')
+  t.false(mockQuire.installInProject.called, 'installInProject should not be called when initStarter fails')
+  t.true(fs.removeSync.called || !fs.existsSync('/new-project'), 'project directory should be removed on error')
+  t.true(mockLogger.error.calledWith(error.message), 'error message should be logged')
+  t.true(mockReporter.fail.called, 'reporter.fail should be called on error')
+})
+
+test('create command should pass through debug option', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  const mockDebug = sandbox.stub()
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().callsFake(async (starter, projectPath) => {
+      fs.mkdirSync(projectPath, { recursive: true })
+      fs.writeFileSync(`${projectPath}/package.json`, JSON.stringify({ name: 'new-project' }))
+      return '1.0.0'
+    }),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('default-starter')
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': { installer: mockQuire },
+    '#lib/reporter/index.js': { default: mockReporter },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = mockDebug
+
+  // Run action with debug option
+  await command.action('/new-project', 'starter-template', { debug: true })
+
+  t.true(mockDebug.called, 'debug should be called with debug option')
+  t.true(mockQuire.initStarter.called, 'initStarter should be called')
+})
+
+test('create command should pass quire-path option to methods', async (t) => {
+  const { sandbox, fs, mockLogger, mockReporter } = t.context
+
+  // Mock quire library
+  const mockQuire = {
+    initStarter: sandbox.stub().callsFake(async (starter, projectPath) => {
+      fs.mkdirSync(projectPath, { recursive: true })
+      fs.writeFileSync(`${projectPath}/package.json`, JSON.stringify({ name: 'new-project' }))
+      return '1.0.0'
+    }),
+    installInProject: sandbox.stub().resolves()
+  }
+
+  // Mock config
+  const mockConfig = {
+    get: sandbox.stub().returns('default-starter')
+  }
+
+  // Use esmock to replace imports
+  const { default: CreateCommand } = await esmock('./create.js', {
+    '#lib/installer/index.js': {
+      installer: mockQuire
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter
+    },
+    'fs-extra': fs
+  }, {
+    '#lib/logger/index.js': {
+      default: () => mockLogger
+    }
+  })
+
+  const command = new CreateCommand()
+  command.config = mockConfig
+  command.logger = mockLogger
+  command.debug = sandbox.stub()
+
+  const options = { quirePath: '/custom/path/to/quire-11ty' }
+
+  // Run action with quire-path option
+  await command.action('/new-project', 'starter-template', options)
+
+  const initCall = mockQuire.initStarter.getCall(0)
+  const installCall = mockQuire.installInProject.getCall(0)
+
+  t.true(initCall.args[2] === options, 'initStarter should receive options with quire-path')
+  t.true(installCall.args[2] === options, 'installInProject should receive options with quire-path')
+})
+
+test('create command initial commit does not include temporary install artifacts', async (t) => {
+  const { sandbox, fs, projectRoot, vol, mockReporter } = t.context
+
+  // Setup project directory
+  fs.mkdirSync(projectRoot)
+
+  // Track filesystem state at the time of git operations
+  let tempDirExistedAtAdd = null
+  let tempDirExistedAtCommit = null
+
+  const tempDir = path.join(projectRoot, '.temp')
+  const tarballPath = path.join(tempDir, 'thegetty-quire-11ty-1.0.0.tgz')
+
+  // Mock npm façade to simulate npm pack behavior
+  const mockNpm = {
+    pack: sandbox.stub().callsFake(() => {
+      // Simulate npm pack creating a tarball in .temp
+      fs.writeFileSync(tarballPath, '')
+    }),
+    cacheClean: sandbox.stub().resolves(),
+    install: sandbox.stub().resolves()
+  }
+
+  // Mock Git class that captures filesystem state when methods are called
+  class MockGit {
+    add() {
+      // Capture filesystem state at the moment add() is called
+      tempDirExistedAtAdd = fs.existsSync(tempDir)
+      return Promise.resolve()
+    }
+    commit() {
+      // Capture filesystem state at the moment commit() is called
+      tempDirExistedAtCommit = fs.existsSync(tempDir)
+      return Promise.resolve()
+    }
+    rm() {
+      return Promise.resolve()
+    }
+  }
+
+  // Mock fs and git
+  // Nota bene: Pass `vol` here as fs because memfs only provides cpSync there
+  const { installer } = await esmock('#lib/installer/index.js', {
+    'fs-extra': vol,
+    '#lib/npm/index.js': {
+      default: mockNpm,
+    },
+    '#lib/git/index.js': {
+      Git: MockGit,
+    },
+    '#lib/reporter/index.js': {
+      default: mockReporter,
+    },
+    'execa': {
+      // Mock tar extraction command (uses array-based execa, not execaCommand)
+      execa: sandbox.stub().resolves(),
+    },
+  })
+
+  await installer.installInProject(projectRoot, '1.0.0')
+
+  // Verify that temp dir was removed BEFORE git add was called
+  t.false(tempDirExistedAtAdd, '.temp directory should be removed before git add')
+
+  // Verify that temp dir was removed BEFORE git commit was called
+  t.false(tempDirExistedAtCommit, '.temp directory should be removed before git commit')
+})