@antora/cli 3.0.0-alpha.6 → 3.0.0-beta.1

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

@@ -2,107 +2,158 @@
 
 '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 { configureLogger, getLogger, 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) {
-  const result = cli.parse(argv.length < 3 ? [...argv, 'help'] : argv)
-  /* istanbul ignore else */
-  if (cli._promise) await cli._promise
-  return result
+  const args = argv.slice(2)
+  return cli.parseAsync(args.length ? args : ['help'], { from: 'user' })
 }
 
-function exitWithError (err, showStack, msg = undefined) {
+function exitWithError (err, opts, msg = undefined) {
   if (!msg) msg = err.message || err
-  if (showStack) {
-    let stack
+  const name = msg.startsWith('asciidoctor: FAILED: ') ? (msg = msg.slice(21)) && 'asciidoctor' : cli.name()
+  const logger = getLogger(null)
+    ? getLogger(name)
+    : configureLogger({ format: 'pretty', level: opts.silent ? 'silent' : 'fatal', failureLevel: 'fatal' }).get(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 requireLibraries (requirePaths) {
-  if (requirePaths) requirePaths.forEach((requirePath) => requireLibrary(requirePath))
+function exit () {
+  return finalizeLogger().then((failOnExit) => process.exit(failOnExit ? 1 : process.exitCode))
 }
 
-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 getTTYColumns () {
+  return process.env.COLUMNS || process.stdout.columns || 80
+}
+
+function outputError (str, write) {
+  write(str.replace(/^error: /, cli.name() + ': '))
 }
 
 cli
+  .allowExcessArguments(false)
+  .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.')
-  .option('-r, --require <library>', 'Require library (aka node module) or script before executing command.')
-  .on('option:require', (requirePath) => (cli.requirePaths = [...(cli.requirePaths || []), requirePath]))
+  .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
+      )
+  })
+  .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' })
-  .option('--generator <library>', 'The site generator library.', '@antora/site-generator-default')
-  .action(async (playbookFile, command) => {
+  .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 playbook
     try {
-      requireLibraries(cli.requirePaths)
+      playbook = buildPlaybook(args, process.env, buildPlaybook.defaultSchema, (config) => {
+        try {
+          configureLogger(config.getModel('runtime.log'), playbookDir)
+        } catch {}
+      })
     } catch (err) {
-      exitWithError(err, cli.stacktrace)
+      return exitWithError(err, errorOpts)
     }
-    const generator = command.generator
+    const generator = playbook.antora.generator
     let generateSite
     try {
-      generateSite = requireLibrary(generator, ospath.resolve(playbookFile, '..'))
+      generateSite =
+        (generateSite = userRequire(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
-    cli._promise = 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, command) => {
+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()
@@ -111,10 +162,4 @@ cli.command('help [command]', { hidden: true }).action((name, command) => {
 
 cli.command('version', { hidden: true }).action(() => cli.emit('option:version'))
 
-cli.on('--help', () => {
-  console.log(
-    `\nRun '${cli.name()} <command> --help' to see options and examples for a command (e.g., ${cli.name()} generate --help).`
-  )
-})
-
 module.exports = run

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

@@ -5,8 +5,15 @@ const { Command } = require('commander')
 Command.prototype.optionsFromConvict = function (convictConfig, opts = {}) {
   let exclude = opts.exclude
   if (exclude && !Array.isArray(exclude)) exclude = [exclude]
-  getOptions(convictConfig).forEach((option) => {
-    if (!(exclude && exclude.includes(option.name))) this.option(option.form, option.description, option.default)
+  getOptions(convictConfig).forEach(({ name, form, description, default: default_, choices }) => {
+    if (exclude && exclude.includes(name)) return
+    this.addOption(
+      choices
+        ? this.createOption(form, description)
+          .default(default_, default_)
+          .choices(choices)
+        : this.createOption(form, description).default(default_, default_)
+    )
   })
   return this
 }
@@ -24,15 +31,15 @@ function collectOptions (props, context = undefined) {
       const { arg, format, default: default_ } = value
       const option = { name: arg, form: `--${arg}`, description: value.doc, format: format }
       if (Array.isArray(format)) {
-        option.form += ' <option>'
-        option.description += ` (options: ${format.join(', ').replace(/, ([^,]+)$/, ', or $1')})`
+        option.form += ' <choice>'
+        option.choices = Object.defineProperty(format.slice(), 'map', { value: () => format })
       } else if (format !== 'boolean') {
         option.form += ` <${arg.substr(arg.lastIndexOf('-') + 1, arg.length)}>`
       }
       if (default_ === null) {
         //option.mandatory = true
         option.description += ' (required)'
-      } else if (default_ && (typeof default_ !== 'object' || default_.toString() !== '[object Object]')) {
+      } else if (default_ && default_.constructor !== Object) {
         option.default = default_
       }
       accum.push(option)

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

@@ -1,7 +1,7 @@
 'use strict'
 
 const commander = require('commander')
-require('./commander/condense-help')
 require('./commander/options-from-convict')
+require('./commander/track-options')
 
 module.exports = commander

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/cli",
-  "version": "3.0.0-alpha.6",
+  "version": "3.0.0-beta.1",
   "description": "The command line interface for Antora.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -18,17 +18,18 @@
     "antora": "bin/antora"
   },
   "dependencies": {
-    "@antora/logger": "3.0.0-alpha.6",
-    "@antora/playbook-builder": "3.0.0-alpha.6",
-    "commander": "~6.2"
+    "@antora/logger": "3.0.0-beta.1",
+    "@antora/playbook-builder": "3.0.0-beta.1",
+    "@antora/user-require-helper": "~2.0",
+    "commander": "~8.3"
   },
   "devDependencies": {
-    "@antora/site-publisher": "3.0.0-alpha.6",
-    "convict": "~6.1",
+    "@antora/site-publisher": "3.0.0-beta.1",
+    "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": "38ec002e88eede3ce5c401a6e226d1a0356945c5"
+  "gitHead": "7c5ef1ea93dd489af533c80a936c736013c41769"
 }

package/lib/commander/condense-help.js

@@ -1,17 +0,0 @@
-'use strict'
-
-const { Command } = require('commander')
-const { helpInformation } = Command.prototype
-const { stringify } = JSON
-
-// TODO include common options when outputting help for a (sub)command
-Command.prototype.helpInformation = function () {
-  const nonTTYColumns = 'columns' in process.stdout ? undefined : (process.stdout.columns = process.env.COLUMNS || 80)
-  // NOTE override stringify to coerce to string normally
-  JSON.stringify = (val) => `${val}`
-  const helpInfo = helpInformation.call(this)
-  //const helpInfo = helpInformation.call(this).split('\n').filter((line) => !line.includes('--no-')).join('\n')
-  JSON.stringify = stringify
-  if (nonTTYColumns) delete process.stdout.columns
-  return helpInfo
-}