@thegetty/quire-cli 1.0.0-pre-release.0 → 1.0.0-pre-release.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-pre-release.0",
+  "version": "1.0.0-pre-release.2",
   "author": "Getty Digital",
   "license": "J Paul Getty Trust",
   "bugs": {
@@ -45,7 +45,6 @@
     "#lib/*.js": "./src/lib/*.js"
   },
   "dependencies": {
-    "@11ty/eleventy": "^2.0.0-canary.16",
     "boxen": "^7.0.0",
     "chalk": "^5.1.2",
     "commander": "^9.4.1",
@@ -61,7 +60,7 @@
     "loglevel": "^1.8.0",
     "ora": "^6.1.2",
     "semver": "^7.3.8",
-    "simple-git": "^3.14.1",
+    "simple-git": "^3.15.0",
     "update-notifier": "^6.0.2"
   },
   "devDependencies": {

package/src/commands/README.md

@@ -194,6 +194,14 @@ To reinstall a `quire-11ty` version run
 quire version install <version> --force
 ```
 
+#### `link`
+
+Link to a local `quire-11ty` package for development and testing.
+
+```sh
+quire version link [path]
+```
+
 #### `list`
 
 List installed versions of `quire-11ty`
@@ -210,12 +218,20 @@ Remove outdated versions of `quire-11ty`
 quire version prune
 ```
 
-#### `remove` (alias `uninstall`)
+#### `unlink`
+
+Unlink a local `quire-11ty` package
 
 ```sh
-quire version remove <version>
+quire version unlink
 ```
 
+#### `uninstall` (alias `remove`)
+
 ```sh
 quire version uninstall <version>
 ```
+
+```sh
+quire version remove <version>
+```

package/src/commands/create.js

@@ -51,9 +51,8 @@ export default class CreateCommand extends Command {
       // const starter = starters['default']
       // `git clone starter path`
     } else {
-      const version = await quire.latest()
+      const version = await quire.initStarter(starter, projectPath)
       await quire.install(version)
-      await quire.initStarter(starter, projectPath)
     }
   }
 }

package/src/lib/11ty/api.js

@@ -1,6 +1,5 @@
-import Eleventy from '@11ty/eleventy'
 import path from 'node:path'
-import paths from './paths.js'
+import paths, { eleventyRoot, projectRoot } from './paths.js'
 
 /**
  * A factory function to configure an instance of Eleventy
@@ -9,9 +8,18 @@ import paths from './paths.js'
  * @param  {Object}  options  Eleventy configuration options
  * @return  {Eleventy}  A configured instance of Eleventy
  */
-const factory = (options) => {
+const factory = async (options) => {
   const { config, input, output } = paths
 
+  console.info(`[CLI:11ty] projectRoot ${projectRoot}`)
+
+  console.debug('[CLI:11ty] %o', paths)
+
+  /**
+   * Dynamically import the correct version of Eleventy from `lib/quire/versions`
+   */
+  const { default: Eleventy } = await import(path.join(eleventyRoot, 'node_modules', '@11ty', 'eleventy', 'src', 'Eleventy.js'))
+
   return new Eleventy(input, output, {
     config: (eleventyConfig) => {
       // custom configuration
@@ -28,18 +36,22 @@ const factory = (options) => {
  */
 export default {
   build: async (options = {}) => {
-    const projectRoot = path.resolve('../../packages/11ty')
     process.cwd(projectRoot)
 
     console.info('[CLI:11ty] running eleventy build')
     console.info(`[CLI:11ty] projectRoot ${projectRoot}`)
 
-    const eleventy = factory(options)
+    if (options.debug) process.env.DEBUG = 'Eleventy*'
+
+    const eleventy = await factory(options)
     await eleventy.executeBuild()
   },
   serve: async (options = {}) => {
     console.info('[CLI:11ty] running development server')
-    const eleventy = factory(options)
+
+    if (options.debug) process.env.DEBUG = 'Eleventy*'
+
+    const eleventy = await factory(options)
     await eleventy.serve()
   }
 }

package/src/lib/11ty/cli.js

@@ -1,9 +1,7 @@
 import { execa } from 'execa'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
-import paths from './paths.js'
-
-const projectRoot = path.resolve('../../packages/11ty')
+import paths, { projectRoot } from './paths.js'
 
 /**
  * A factory function to configure an Eleventy CLI command
@@ -37,10 +35,22 @@ export default {
 
     const eleventyOptions = factory()
 
+    /**
+     * Set execa environment variables
+     * @see https://github.com/sindresorhus/execa#env
+     */
+    const execaEnv = {}
+
+    if (options.debug) execaEnv.DEBUG = 'Eleventy*'
     if (options.dryRun) eleventyOptions.push('--dryrun')
     if (options.quiet) eleventyOptions.push('--quiet')
 
-    await execa('npx', eleventyOptions, { cwd: projectRoot }).stdout.pipe(process.stdout)
+    await execa('npx', eleventyOptions, {
+      all: true,
+      cwd: projectRoot,
+      env: execaEnv,
+      execPath: process.execPath
+    }).all.pipe(process.stdout)
   },
 
   serve: async (options = {}) => {
@@ -50,10 +60,22 @@ export default {
 
     eleventyOptions.push('--serve')
 
+    /**
+     * Set execa environment variables
+     * @see https://github.com/sindresorhus/execa#env
+     */
+    const execaEnv = {}
+
+    if (options.debug) execaEnv.DEBUG = 'Eleventy*'
     if (options.port) eleventyOptions.push(`--port=${options.port}`)
     if (options.quiet) eleventyOptions.push('--quiet')
     if (options.verbose) eleventyOptions.push('--verbose')
 
-    await execa('npx', eleventyOptions, { cwd: projectRoot }).stdout.pipe(process.stdout)
+    await execa('npx', eleventyOptions, {
+      all: true,
+      cwd: projectRoot,
+      env: execaEnv,
+      execPath: process.execPath
+    }).all.pipe(process.stdout)
   }
 }

package/src/lib/11ty/paths.js

@@ -12,16 +12,23 @@ const __dirname = path.dirname(__filename)
  * `eleventyRoot` is _relative_ to `main.js`, the CLI entry point.
  * Both `input` and `output` are _relative_ to the `config` module.
  *
- * @todo read paths from the Quire project configuration and resolve path
- * to the correct version of the quire/11ty package, for example:
- *   eleventyRoot = `#lib/quire/versions/${config.version}/11ty`
+ * @todo
+ * - refactor the paths module as a concern of the `lib/quire` module
+ * - refactor resolving an absolute path to the correct eleventy version root;
+ *   this needs to use the correct `quire-11ty` version for the project
+ *   and correctly resolve the path to the target of the 'latest' symlink
  */
-export const eleventyRoot = '../../packages/11ty'
-export const projectRoot = '../../packages/11ty'
+const cliRoot = path.resolve(__dirname, path.join('..', '..'))
+const version = 'latest'
+
+// Absolute path to the current version of quire-11ty
+export const eleventyRoot =
+  path.resolve(__dirname, path.join(cliRoot, 'lib', 'quire', 'versions', version))
+export const projectRoot = process.cwd()
 
 export default {
-  config: path.resolve(eleventyRoot, '.eleventy.js'),
-  input: `${projectRoot}/content`,
-  output: './_site',
+  config: path.join(eleventyRoot, '.eleventy.js'),
+  input: path.relative(eleventyRoot, path.join(projectRoot, 'content')),
+  output: path.relative(eleventyRoot, path.join(projectRoot, '_site')),
   public: './public',
 }

package/src/lib/config/index.js

@@ -1,29 +1 @@
-import Conf from 'conf'
 import semver from 'semver'
-
-/**
- * Quire CLI configuration schema
- */
-const schema = {
-
-}
-
-/**
- * Schema migrations
- * @see https://github.com/sindresorhus/conf#migrations
- */
-const migrations = {
-  // '1.0.0': (store) => {}
-}
-
-/**
- * @see https://github.com/sindresorhus/conf
- */
-const store = new Conf({
-  beforeEachMigration: (store, context) => {
-    console.log(`[CLI:conf] migrate from ${context.fromVersion} → ${context.toVersion}`)
-  },
-  configName: 'cli',
-  migrations,
-  schema
-})

package/src/lib/quire/index.js

@@ -1,5 +1,5 @@
-import { cwd } from 'node:process'
-import { execa } from 'execa'
+import { chdir, cwd } from 'node:process'
+import { execa, execaCommand } from 'execa'
 import { fileURLToPath } from 'node:url'
 import { isEmpty } from '#helpers/is-empty.js'
 import fs from 'fs-extra'
@@ -11,6 +11,7 @@ import semver from 'semver'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+// Version install path is relative to process working directory
 const INSTALL_PATH = path.join('src', 'lib', 'quire', 'versions')
 const PACKAGE_NAME = '@thegetty/quire-11ty'
 const VERSION_FILE = '.quire'
@@ -19,23 +20,53 @@ const IS_WINDOWS =
   process.platform === 'win32' || /^(cygwin|msys)$/.test(process.env.OSTYPE)
 
 /**
- * Return full path to the required `quire-11ty` version
+ * Return an absolute path to an installed `quire-11ty` version
  *
- * @return  {String}  version  Quire-11ty semantic version
+ * @return  {String}  path to installed `quire-11ty` version
  */
 function getPath(version='latest') {
-  // console.debug(`${projectName} set to use quire-11ty@${version}`)
-  // return versionPath
+  const absolutePath = path.relative('/', `${INSTALL_PATH}/${version}`)
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`[CLI:quire] \`quire-11ty@${version}\` is not installed`)
+    return null
+  }
+  console.debug(`[CLI:quire] \%`, absolutePath)
+  return absolutePath
 }
 
 /**
  * Read the required `quire-11ty` version for the project `.quire` file
  *
+ * @param    {String}   projectPath  Absolute system path to the project root
+ *
  * @return  {String}  version  Quire-11ty semantic version
  */
-function getVersion() {
-  // console.debug(`${projectName} set to use quire-11ty@${version}`)
-  // return version
+function getVersion(projectPath) {
+  projectPath = projectPath || path.resolve(cwd())
+  const version = fs.readFileSync(path.join(projectPath, VERSION_FILE), { encoding:'utf8' })
+  const projectName = path.basename(projectPath)
+  console.debug(`${projectName} set to use quire-11ty@${version}`)
+  return version
+}
+
+/**
+ * Read the required `quire-11ty` version from starter `package.json` `peerDependencies`
+ *
+ * @param    {String}   projectPath  Absolute system path to the project root
+ *
+ * @return  {String}  version  Quire-11ty semantic version with caret or other
+ * comparators trimmed off the beginning
+ *
+ * @TODO refactor `latest()` function to programmatically return a specific
+ * version of `@thegetty/quire-11ty` from a semantic version string
+ * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`) so this string-trimming
+ * logic can be removed
+ */
+function getVersionFromStarter(projectPath) {
+  const packageConfig = fs.readFileSync(path.join(projectPath, 'package.json'), { encoding:'utf8' })
+  const { peerDependencies } = JSON.parse(packageConfig)
+  const version = peerDependencies[PACKAGE_NAME]
+  return version.substr(version.search(/\d/))
 }
 
 /**
@@ -43,9 +74,9 @@ function getVersion() {
  *
  * @param    {String}   starter   A repository URL or path to local starter
  * @param    {String}   projectPath  Absolute system path to the project root
- * @param    {String}   quireVersion  A string indicating the current version
- * of quire being used with a new project
- * @return   {Promise}
+ *
+ * @return   {String}   quireVersion  A string indicating the current version
+ *                                    of quire being used with a new project
  */
 async function initStarter (starter, projectPath) {
   projectPath = projectPath || cwd()
@@ -68,44 +99,43 @@ async function initStarter (starter, projectPath) {
     `\n  starter: "${starter}"`
   )
 
-  // Clone starter project repository
-  // @TODO pipe `git clone` status to stdout for better UX
+  /**
+   * Clone starter project repository
+   * @todo pipe `git clone` status to stdout for better UX
+   */
   await git
     .cwd(projectPath)
     .clone(starter, '.')
     .catch((error) => console.error('[CLI:error] ', error))
 
   /**
-   * Quire project dot configuration file
-   *
-   * writes the quire-11ty semantic version to a `.quire` file
+   * Determine `quire-11ty` version required by the starter project
+   * and write a `.quire` file with the semantic version string.
    */
-  const quireVersion = await latest()
-  const versionFilePath = path.join(projectPath, VERSION_FILE)
-  fs.writeFileSync(versionFilePath, quireVersion)
-
-  // @TODO Remove 11ty file copying code (lines 79-88) once CLI pathing issues have been sorted out
-  // Copy 11ty files
-  const fullProjectPath = path.resolve(projectPath)
-  const eleventyPath = path.resolve(path.join(INSTALL_PATH, quireVersion))
-  const eleventyFiles = fs.readdirSync(eleventyPath)
-
-  // copies all files in `quire/packages/11ty`
-  eleventyFiles.forEach((filePath) => {
-    const fileToCopy = path.resolve(eleventyPath, filePath)
-    fs.copySync(fileToCopy, path.join(fullProjectPath, path.basename(filePath)))
-  })
+  const quireVersion = getVersionFromStarter(projectPath) || await latest()
+  setVersion(projectPath, quireVersion)
 
-  // Reinitialize project as a new git repository
+  // Re-initialize project directory as a new git repository
   await fs.remove(path.join(projectPath, '.git'))
 
-  // don't git-add copied `node_modules`
-  const starterFiles = fs
-    .readdirSync(projectPath)
-    .filter((filePath) => filePath !== 'node_modules')
+  /**
+   * Remove the starter repository package config file
+   * and create a new package config for the project
+   * (this is necessary for Eleventy to resolve project paths)
+   * @todo allow interactive init using a custom questionnaire
+   * @see https://docs.npmjs.com/creating-a-package-json-file#customizing-the-packagejson-questionnaire
+   */
+  await fs.remove(path.join(projectPath, 'package.json'))
+  await execaCommand('npm init --yes', { cwd: projectPath })
+
+  /**
+   * Create an initial commit of files in new repository
+   * @todo use a localized string for the commit message
+   */
+  const projectFiles = fs.readdirSync(projectPath)
+  await git.init().add(projectFiles).commit('Initial Commit')
 
-  // @TODO add localized string for commit message
-  await git.init().add(starterFiles).commit('Initial Commit')
+  return quireVersion
 }
 
 /**
@@ -116,28 +146,57 @@ async function initStarter (starter, projectPath) {
  * @param  {String}  version  Quire-11ty semantic version
  * @return  {Promise}
  */
-async function install(version='latest') {
+async function install(version, options={}) {
   console.debug(`[CLI:quire] installing quire-11ty@${version}`)
-  fs.ensureDirSync(INSTALL_PATH)
+  const absoluteInstallPath = path.join(__dirname, 'versions')
+  fs.ensureDirSync(absoluteInstallPath)
   /**
-   * Destination is relative to `node_modules` of the working-directory
-   * so we have included a relative path to parent directory to install
-   * versions to a different local path.
+   * `Destination` is relative to `node_modules` of the working-directory
+   * so we have included a relative path to parent directory in order to
+   * install versions to a different local path.
    * @see https://github.com/scott-lin/install-npm-version
    */
-  const options = {
-    Destination: path.join('../', INSTALL_PATH, version),
+  const installOptions = {
+    Destination: path.join('../', version),
     Debug: false,
-    Verbosity: 'Silent',
+    Overwrite: options.force || options.overwrite || false,
+    Verbosity: options.debug ? 'Debug' : 'Silent',
+    WorkingDirectory: absoluteInstallPath
   }
-  await inv.Install(`${PACKAGE_NAME}@${version}`, options)
+  await inv.Install(`${PACKAGE_NAME}@${version}`, installOptions)
+
+  // delete empty `node_modules` directory that `install-npm-version` creates
+  const invNodeModulesDir = path.join(absoluteInstallPath, 'node_modules')
+  if (fs.existsSync(invNodeModulesDir)) fs.rmdir(invNodeModulesDir)
+
   symlinkLatest()
+
+  console.debug('[CLI:quire] installing dev dependencies')
+  /**
+   * Manually install necessary dev dependencies to run 11ty;
+   * these must be `devDependencies` so that they are not bundled into
+   * the final `_site` package when running `quire build`
+   */
+  const currentWorkingDirectory = cwd()
+  const versionDir = path.join(absoluteInstallPath, version)
+  chdir(versionDir)
+  await execaCommand('npm cache clean --force')
+  await execaCommand('npm install --save-dev')
 }
 
 /**
  * Retrieve latest published version of the `quire-11ty` package
+ * Nota bene: `npm view [<@scope>/]<name>[@<version>] version`
+ * @see https://docs.npmjs.com/cli/v7/commands/npm-view
+ * returns a list of versions that satisfy the `<version>` range specifier,
+ * piping this to execa `stdout` we get only the last line of output.
  *
  * @return {String} `quire-11ty@latest` semantic version string
+ *
+ * @TODO refactor `latest()` function to programmatically return a specific
+ * version of `@thegetty/quire-11ty` from a semantic version string
+ * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`) so it may be used like:
+ * await latest('^1.0.0-pre-release.0') => '1.0.0-pre-release.2'
  */
 async function latest() {
   const { stdout: quireVersion } =
@@ -177,30 +236,31 @@ async function remove(version) {
  *
  * @param  {String}  version  Quire-11ty semantic version
  */
-function setVersion(version) {
+function setVersion(projectPath, version) {
   if (!version) {
-    console.error('No version specified')
-    // return version from config
-    // version =
+    console.error('[CLI] no version specified')
   }
+  const projectName = path.basename(projectPath)
   console.info(`${projectName} set to use quire-11ty@${version}`)
+  const versionFilePath = path.join(projectPath, VERSION_FILE)
+  fs.writeFileSync(versionFilePath, version)
 }
 
 /**
  * Update symbolic link to the latest _installed_ version of `quire-11ty`
  *
- * @todo refactor to determine latest _installed_ version using the semver
- * package methods to sort and compare the locally installed versions.
- *
  * @todo why does this not work using `fs-extra` `createSymlinkSync()`
  */
 function symlinkLatest() {
-  const version = fs.readdirSync(INSTALL_PATH).sort()[0]
-  const target = path.relative(__dirname, path.join(INSTALL_PATH, version))
-  const source = path.join(INSTALL_PATH, 'latest')
+  const latestInstalledVersion = fs
+    .readdirSync(path.join(__dirname, 'versions'))
+    .filter((dirent) => semver.valid(semver.coerce(dirent)))
+    .sort(semver.rcompare)[0]
+  const target = path.join(__dirname, 'versions', latestInstalledVersion)
+  const source = path.join(__dirname, 'versions', 'latest')
   const type = IS_WINDOWS ? 'junction' : 'dir'
 
-  console.debug('[CLI:quire] symlinking latest')
+  console.debug('[CLI:quire] symlinking latest installed version')
 
   try {
     return fs.symlinkSync(target, source, type)
@@ -244,11 +304,12 @@ function testVersion(version) {
 }
 
 /**
- * List known versions of the `quire-11ty` package
- * @todo use npm for this
+ * Get an array of published `quire-11ty` package versions
+ *
+ * @return  {Array<String>}  published versions
  */
-function versions() {
-  console.info(`Known versions of @thegetty/quire-11ty...`)
+async function versions() {
+  return await execa('npm', ['show', PACKAGE_NAME, 'versions'])
 }
 
 export const quire = {

package/src/lib/reporter/index.js

@@ -1,24 +0,0 @@
-import chalk from 'chalk'
-
-/**
- * Reporter module for the CLI
- *
- * @class  Reporter
- */
-export class Reporter {
-  constructor() {
-
-  }
-
-  /**
-   * Implicit accessors for reporting level:
-   * verbose...silent
-   */
-  get level() {
-    // return
-  }
-
-  set level() {
-
-  }
-}

package/src/main.js

@@ -1,6 +1,7 @@
-#!/usr/bin/env node
+#!/usr/bin/env node --no-warnings
 import { Command } from 'commander'
 import commands from './commands/index.js'
+import packageConfig from '../package.json' assert { type: 'json' }
 
 /**
  * Quire CLI implements the command pattern.
@@ -14,7 +15,7 @@ const program = new Command()
 program
   .name('quire-cli')
   .description('Quire command-line interface')
-  .version('1.0.0')
+  .version(packageConfig.version)
   .configureHelp({
     helpWidth: 80,
     sortOptions: false,