@antora/cli 3.0.0-alpha.9 → 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,15 +2,13 @@
 
 '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 DEFAULT_GENERATOR = '@antora/site-generator-default'
 const { version: VERSION } = require('../package.json')
 
 async function run (argv = process.argv) {
@@ -18,47 +16,60 @@ 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) {
   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)) {
-      if (err instanceof SyntaxError) {
-        let loc
-        ;[loc, stack] = stack.split(/\n+(?=SyntaxError: )/)
-        msg = stack.replace('\n', `\n    at ${loc}\n`)
-      } else if (stack.startsWith(`${err.name}: ${msg}\n`)) {
-        msg = stack
-      } else {
-        msg = [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 finalizeLogger().then((failOnExit) => process.exit(failOnExit ? 1 : process.exitCode))
 }
 
 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 })
+  .configureOutput({ getOutHelpWidth: getTTYColumns, getErrHelpWidth: getTTYColumns, outputError })
   .storeOptionsAsProperties()
   .name('antora')
   .version(
     {
       toString () {
-        const buffer = [`@antora/cli: ${VERSION}`]
+        const generator = cli._findCommand('generate').getOptionValue('generator')
+        const buffer = ['@antora/cli: ' + VERSION]
         let generatorVersion
-        const generatorPackageJson = DEFAULT_GENERATOR + '/package.json'
+        const generatorPackageJson = generator + '/package.json'
         try {
           generatorVersion = require(generatorPackageJson).version
         } catch {
@@ -66,7 +77,7 @@ cli
             generatorVersion = require(require.resolve(generatorPackageJson, { paths: [''] })).version
           } catch {}
         }
-        buffer.push(DEFAULT_GENERATOR + ': ' + (generatorVersion || 'not installed'))
+        buffer.push(generator + ': ' + (generatorVersion || 'not installed'))
         return buffer.join('\n')
       },
     },
@@ -76,69 +87,73 @@ cli
   .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 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(DEFAULT_GENERATOR, DEFAULT_GENERATOR)
-  )
+  .description('Generate a documentation site as specified by <playbook>.')
+  .optionsFromConvict(convict(buildPlaybook.defaultSchema), { exclude: 'playbook' })
+  .trackOptions()
   .action(async (playbookFile, options, command) => {
-    const dot = ospath.resolve(playbookFile, '..')
-    const userRequireContext = { dot, paths: [dot, __dirname] }
+    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) {
-        exitWithError(err, cli.stacktrace)
+        return exitWithError(err, errorOpts)
       }
     }
-    const generator = options.generator
+    const args = command.optionArgs.concat('--playbook', playbookFile)
+    let playbook
+    try {
+      playbook = buildPlaybook(args, process.env, buildPlaybook.defaultSchema, (config) => {
+        try {
+          configureLogger(config.getModel('runtime.log'), playbookDir)
+        } catch {}
+      })
+    } catch (err) {
+      return exitWithError(err, errorOpts)
+    }
+    const generator = playbook.antora.generator
     let generateSite
     try {
-      generateSite = userRequire(generator, userRequireContext)
+      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
-    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/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/package.json

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