@antora/cli 3.0.0-alpha.7 → 3.0.0-beta.2

package/README.md

@@ -3,9 +3,9 @@
 The command line interface (CLI) for Antora.
 
 [Antora](https://antora.org) is a modular static site generator designed for creating documentation sites from AsciiDoc documents.
-Its site generator pipeline aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
+Its site generator aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
 
-To run Antora, you need both the CLI and a site generator pipeline.
+To run Antora, you need both the CLI and a site generator.
 Once these packages are installed, you can use the `antora` command to generate your site.
 
 ## How to Install

package/lib/cli.js

@@ -1,15 +1,11 @@
-#!/usr/bin/env node
-
 'use strict'
 
+const buildPlaybook = require('@antora/playbook-builder')
 const cli = require('./commander')
-// Q: can we ask the playbook builder for the config schema?
-const configSchema = require('@antora/playbook-builder/lib/config/schema')
 const convict = require('@antora/playbook-builder/lib/solitary-convict')
-const { finalizeLogger } = require('@antora/logger')
 const ospath = require('path')
+const userRequire = require('@antora/user-require-helper')
 
-const DOT_RELATIVE_RX = new RegExp(`^\\.{1,2}[/${ospath.sep.replace('/', '').replace('\\', '\\\\')}]`)
 const { version: VERSION } = require('../package.json')
 
 async function run (argv = process.argv) {
@@ -17,112 +13,160 @@ async function run (argv = process.argv) {
   return cli.parseAsync(args.length ? args : ['help'], { from: 'user' })
 }
 
-function exitWithError (err, showStack, msg = undefined) {
+function exitWithError (err, opts, msg = undefined) {
+  const { getLogger, configureLogger } = requireLogger()
   if (!msg) msg = err.message || err
-  if (showStack) {
-    let stack
+  const name = msg.startsWith('asciidoctor: FAILED: ') ? (msg = msg.slice(21)) && 'asciidoctor' : cli.name()
+  if (!getLogger(null)) {
+    configureLogger({ format: 'pretty', level: opts.silent ? 'silent' : 'fatal', failureLevel: 'fatal' })
+  }
+  const logger = getLogger(name)
+  if (opts.stacktrace) {
+    let loc, stack
     if ((stack = err.backtrace)) {
-      msg = [`error: ${msg}`, ...stack.slice(1)].join('\n')
+      err = Object.assign(new Error(msg), { stack: ['Error', ...stack.slice(1)].join('\n') })
     } else if ((stack = err.stack)) {
-      msg = stack.startsWith(`${err.name}: ${msg}\n`) ? stack : [msg, ...stack.split('\n').slice(1)].join('\n')
+      if (err instanceof SyntaxError && stack.includes('\nSyntaxError: ')) {
+        ;[loc, stack] = stack.split(/\n+SyntaxError: [^\n]+/)
+        err = Object.assign(new SyntaxError(msg), { stack: stack.replace('\n', `SyntaxError\n    at ${loc}\n`) })
+      } else if (stack.startsWith(`${err.name}: ${msg}`)) {
+        stack = stack.replace(`${err.name}: ${msg}`, '').replace(/^\n/, '')
+        err = Object.assign(new err.constructor(msg), { stack: stack ? `${err.name}\n${stack}` : undefined })
+      }
     } else {
-      msg = `error: ${msg} (no stack)`
+      err = Object.assign(new Error(msg), { stack: undefined })
     }
-    console.error(msg)
+    if ({}.propertyIsEnumerable.call(err, 'name')) Object.defineProperty(err, 'name', { enumerable: false })
+    err.stack = `Cause: ${err.stack || '(no stacktrace)'}`
+    logger.fatal(err, msg)
   } else {
-    console.error(`error: ${msg}\nAdd the --stacktrace option to see the cause.`)
+    logger.fatal(msg + '\nAdd the --stacktrace option to see the cause of the error.')
   }
-  process.exit(1)
+  return exit()
+}
+
+function exit () {
+  return requireLogger()
+    .finalizeLogger()
+    .then((failOnExit) => process.exit(failOnExit ? 1 : process.exitCode))
 }
 
 function getTTYColumns () {
   return process.env.COLUMNS || process.stdout.columns || 80
 }
 
-function requireLibraries (requirePaths) {
-  if (requirePaths) requirePaths.forEach((requirePath) => requireLibrary(requirePath))
+function outputError (str, write) {
+  write(str.replace(/^error: /, cli.name() + ': '))
 }
 
-function requireLibrary (requirePath, cwd = process.cwd()) {
-  if (requirePath.charAt() === '.' && DOT_RELATIVE_RX.test(requirePath)) {
-    // NOTE require resolves a dot-relative path relative to current file; resolve relative to cwd instead
-    requirePath = ospath.resolve(requirePath)
-  } else if (!ospath.isAbsolute(requirePath)) {
-    // NOTE appending node_modules prevents require from looking elsewhere before looking in these paths
-    const paths = [cwd, ospath.dirname(__dirname)].map((start) => ospath.join(start, 'node_modules'))
-    requirePath = require.resolve(requirePath, { paths })
-  }
-  return require(requirePath)
+function requireLogger (fromPath = undefined, moduleName = '@antora/logger') {
+  try {
+    return (
+      requireLogger.cache ||
+      (requireLogger.cache = fromPath ? userRequire(moduleName, { paths: [fromPath] }) : require(moduleName))
+    )
+  } catch {}
+  return fromPath && (requireLogger.cache = require(moduleName))
 }
 
 cli
   .allowExcessArguments(false)
-  .configureOutput({ getOutHelpWidth: getTTYColumns, getErrHelpWidth: getTTYColumns })
+  .configureOutput({ getOutHelpWidth: getTTYColumns, getErrHelpWidth: getTTYColumns, outputError })
   .storeOptionsAsProperties()
   .name('antora')
-  .version(VERSION, '-v, --version', 'Output the version number.')
+  .version(
+    {
+      toString () {
+        const generator = cli._findCommand('generate').getOptionValue('generator')
+        const buffer = ['@antora/cli: ' + VERSION]
+        let generatorVersion
+        const generatorPackageJson = generator + '/package.json'
+        try {
+          generatorVersion = require(generatorPackageJson).version
+        } catch {
+          try {
+            generatorVersion = require(require.resolve(generatorPackageJson, { paths: [''] })).version
+          } catch {}
+        }
+        buffer.push(generator + ': ' + (generatorVersion || 'not installed'))
+        return buffer.join('\n')
+      },
+    },
+    '-v, --version',
+    'Output the version of the CLI and default site generator.'
+  )
   .description('A modular, multi-repository documentation site generator for AsciiDoc.')
   .usage('[options] [[command] [args]]')
   .helpOption('-h, --help', 'Output usage information.')
-  .addHelpText(
-    'after',
-    function () {
-      const name = this.name()
-      return this.createHelp().wrap(
+  .addHelpText('after', () => {
+    const name = cli.name()
+    return cli
+      .createHelp()
+      .wrap(
         ` \nRun '${name} <command> --help' to see options and examples for a command (e.g., ${name} generate --help).`,
         getTTYColumns(),
         0
       )
-    }.bind(cli)
-  )
-  .option('-r, --require <library>', 'Require library (aka node module) or script before executing command.')
-  .on('option:require', (requirePath) => (cli.requirePaths = [...(cli.requirePaths || []), requirePath]))
+  })
+  .option('-r, --require <library>', 'Require library (aka node module) or script path before executing command.')
+  .on('option:require', (requireRequest) => (cli.requireRequests = cli.requireRequests || []).push(requireRequest))
   .option('--stacktrace', 'Print the stacktrace to the console if the application fails.')
 
 cli
   .command('generate <playbook>', { isDefault: true })
-  .description('Generate a documentation site specified in <playbook>.')
-  .optionsFromConvict(convict(configSchema), { exclude: 'playbook' })
-  .addOption(
-    cli
-      .createOption('--generator <library>', 'The site generator library.')
-      .default('@antora/site-generator-default', '@antora/site-generator-default')
-  )
+  .description('Generate a documentation site as specified by <playbook>.')
+  .optionsFromConvict(convict(buildPlaybook.defaultSchema), { exclude: 'playbook' })
+  .trackOptions()
   .action(async (playbookFile, options, command) => {
+    const errorOpts = { stacktrace: cli.stacktrace, silent: command.silent }
+    const playbookDir = ospath.resolve(playbookFile, '..')
+    const userRequireContext = { dot: playbookDir, paths: [playbookDir, __dirname] }
+    if (cli.requireRequests) {
+      try {
+        cli.requireRequests.forEach((requireRequest) => userRequire(requireRequest, userRequireContext))
+      } catch (err) {
+        return exitWithError(err, errorOpts)
+      }
+    }
+    const args = command.optionArgs.concat('--playbook', playbookFile)
+    let generator, generatorPath, playbook
     try {
-      requireLibraries(cli.requirePaths)
+      playbook = buildPlaybook(args, process.env, buildPlaybook.defaultSchema, (config) => {
+        try {
+          generatorPath = userRequire.resolve((generator = config.get('antora.generator')), userRequireContext)
+        } catch {}
+        try {
+          requireLogger(generatorPath).configureLogger(config.getModel('runtime.log'), playbookDir)
+        } catch {}
+      })
     } catch (err) {
-      exitWithError(err, cli.stacktrace)
+      return exitWithError(err, errorOpts)
     }
-    const generator = options.generator
     let generateSite
     try {
-      generateSite = requireLibrary(generator, ospath.resolve(playbookFile, '..'))
+      generateSite =
+        (generateSite = require(generatorPath || userRequire.resolve(generator, userRequireContext))).length === 1
+          ? generateSite.bind(null, playbook)
+          : generateSite.bind(null, args, process.env)
     } catch (err) {
       let msg = 'Generator not found or failed to load.'
       if (generator && generator.charAt() !== '.') msg += ` Try installing the '${generator}' package.`
-      exitWithError(err, cli.stacktrace, msg)
+      return exitWithError(err, errorOpts, msg)
     }
-    const args = cli.rawArgs.slice(cli.rawArgs.indexOf(command.name()) + 1)
-    args.splice(args.indexOf(playbookFile), 0, '--playbook')
-    // TODO support passing a preloaded convict config as third option; gets new args and env
-    return generateSite(args, process.env)
-      .then(finalizeLogger)
-      .then((failOnExit) => process.exit(failOnExit ? 1 : process.exitCode))
-      .catch((err) => finalizeLogger().then(() => exitWithError(err, cli.stacktrace)))
+    return generateSite()
+      .then(exit)
+      .catch((err) => exitWithError(err, errorOpts))
   })
   .options.sort((a, b) => a.long.localeCompare(b.long))
 
 cli.command('help [command]', { hidden: true }).action((name, options, command) => {
   if (name) {
-    const helpCommand = cli.commands.find((candidate) => candidate.name() === name)
+    const helpCommand = cli._findCommand(name)
     if (helpCommand) {
       helpCommand.help()
     } else {
-      console.error(
-        `'${name}' is not a valid command in ${cli.name()}. See '${cli.name()} --help' for a list of commands.`
-      )
-      process.exit(1)
+      const message = `error: unknown command '${name}'. See '${cli.name()} --help' for a list of commands.`
+      cli._displayError(1, 'commander.unknownCommand', message)
     }
   } else {
     cli.help()

package/lib/commander/options-from-convict.js

@@ -32,7 +32,7 @@ function collectOptions (props, context = undefined) {
       const option = { name: arg, form: `--${arg}`, description: value.doc, format: format }
       if (Array.isArray(format)) {
         option.form += ' <choice>'
-        option.choices = Object.defineProperty(format.slice(0), 'map', { value: () => format })
+        option.choices = Object.defineProperty(format.slice(), 'map', { value: () => format })
       } else if (format !== 'boolean') {
         option.form += ` <${arg.substr(arg.lastIndexOf('-') + 1, arg.length)}>`
       }

package/lib/commander/track-options.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { Command } = require('commander')
+
+Command.prototype.trackOptions = function () {
+  const optionArgs = (this.optionArgs = [])
+  for (const eventName of this.eventNames().filter((name) => name.startsWith('option:'))) {
+    this.on(eventName, function () {
+      optionArgs.push(`--${eventName.slice(7)}`)
+      if (arguments.length) optionArgs.push(arguments[0])
+    })
+  }
+  return this
+}

package/lib/commander.js

@@ -2,5 +2,6 @@
 
 const commander = require('commander')
 require('./commander/options-from-convict')
+require('./commander/track-options')
 
 module.exports = commander

package/lib/index.js

@@ -0,0 +1,14 @@
+'use strict'
+
+/**
+ * The command line interface (CLI) for Antora.
+ *
+ * Provides a built-in set of commands to run Antora. The default command is
+ * generate. The generate command builds the specified playbook, configures the
+ * logger, then requires and invokes the generator function. When the generator
+ * function completes or fails, the generate command finalizes the logger and
+ * exits with the specified exit code.
+ *
+ * @namespace cli
+ */
+module.exports = require('./cli')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/cli",
-  "version": "3.0.0-alpha.7",
+  "version": "3.0.0-beta.2",
   "description": "The command line interface for Antora.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -13,22 +13,23 @@
   "bugs": {
     "url": "https://gitlab.com/antora/antora/issues"
   },
-  "main": "lib/cli.js",
+  "main": "lib/index.js",
   "bin": {
     "antora": "bin/antora"
   },
   "dependencies": {
-    "@antora/logger": "3.0.0-alpha.7",
-    "@antora/playbook-builder": "3.0.0-alpha.7",
-    "commander": "~7.2"
+    "@antora/logger": "3.0.0-beta.2",
+    "@antora/playbook-builder": "3.0.0-beta.2",
+    "@antora/user-require-helper": "~2.0",
+    "commander": "~8.3"
   },
   "devDependencies": {
-    "@antora/site-publisher": "3.0.0-alpha.7",
-    "convict": "~6.1",
+    "@antora/site-publisher": "3.0.0-beta.2",
+    "convict": "~6.2",
     "kapok-js": "~0.10"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "bin/",
@@ -42,5 +43,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "fbd597b3680474f2083cda8a7facf1e2848c08e0"
+  "gitHead": "5cd3f9cc70622e465cb44daf1aa2035ed5a35f54"
 }