@antora/cli 3.0.0-alpha.9 → 3.0.0-beta.4

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
@@ -24,10 +24,10 @@ antora -v
 ```
 
 Next, install a site generator.
-The default site generator will be sufficient for most users.
+The site generator provided by Antora will be sufficient for most users.
 
 ```sh
-npm install -g @antora/site-generator-default
+npm install -g @antora/site-generator
 ```
 
 The `antora` command (specifically the implicit `generate` subcommand) will look for this package by default.

package/lib/cli.js

@@ -1,64 +1,74 @@
-#!/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 DEFAULT_GENERATOR = '@antora/site-generator-default'
 const { version: VERSION } = require('../package.json')
 
 async function run (argv = process.argv) {
-  const args = argv.slice(2)
-  return cli.parseAsync(args.length ? args : ['help'], { from: 'user' })
+  return cli.parseAsync((argv = argv.slice(2)).length ? argv : ['help'], { from: 'user' })
 }
 
-function exitWithError (err, showStack, msg = undefined) {
-  if (!msg) msg = err.message || err
-  if (showStack) {
-    let stack
-    if ((stack = err.backtrace)) {
-      msg = [`error: ${msg}`, ...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')
-      }
-    } else {
-      msg = `error: ${msg} (no stack)`
-    }
-    console.error(msg)
+function exitWithError (err, opts, msg = undefined) {
+  const { getLogger, configureLogger } = requireLogger()
+  let errMessage = String(
+    err instanceof Error ? err.message : Object.assign((err = new Error(String(err))), { stack: undefined }).message
+  )
+  const name = errMessage.startsWith('asciidoctor: FAILED: ')
+    ? (errMessage = errMessage.slice(21)) && 'asciidoctor'
+    : cli.name()
+  if (!msg) msg = errMessage
+  if (!getLogger(null)) {
+    configureLogger({ format: 'pretty', level: opts.silent ? 'silent' : 'fatal', failureLevel: 'fatal' })
+  }
+  if (opts.stacktrace) {
+    getLogger(name).fatal(err, msg)
   } else {
-    console.error(`error: ${msg}\nAdd the --stacktrace option to see the cause.`)
+    getLogger(name).fatal({ hint: 'Add the --stacktrace option to see the cause of the error.' }, msg)
   }
-  process.exit(1)
+  return exit()
+}
+
+function exit () {
+  return requireLogger()
+    .finalizeLogger()
+    .then((failOnExit) => process.exit(process.exitCode || (failOnExit ? 1 : 0)))
 }
 
 function getTTYColumns () {
   return process.env.COLUMNS || process.stdout.columns || 80
 }
 
+function outputError (str, write) {
+  write(str.replace(/^error: /, cli.name() + ': '))
+}
+
+function requireLogger (fromPath = undefined, moduleName = '@antora/logger') {
+  try {
+    return (
+      requireLogger.cache ||
+      (requireLogger.cache = fromPath ? userRequire(moduleName, { paths: [fromPath] }) : require(moduleName))
+    ) // require('@antora/logger')
+  } 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(
     {
       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 +76,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 +86,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 generator, generatorPath, playbook
+    try {
+      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) {
+      return exitWithError(err, errorOpts)
+    }
     let generateSite
     try {
-      generateSite = userRequire(generator, userRequireContext)
+      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, (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/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.9",
+  "version": "3.0.0-beta.4",
   "description": "The command line interface for Antora.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -13,23 +13,25 @@
   "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.9",
-    "@antora/playbook-builder": "3.0.0-alpha.9",
+    "@antora/logger": "3.0.0-beta.4",
+    "@antora/playbook-builder": "3.0.0-beta.4",
     "@antora/user-require-helper": "~2.0",
-    "commander": "~7.2"
+    "commander": "~8.3"
   },
   "devDependencies": {
-    "@antora/site-publisher": "3.0.0-alpha.9",
-    "convict": "~6.1",
-    "kapok-js": "~0.10"
+    "@antora/site-publisher": "3.0.0-beta.4",
+    "@asciidoctor/core": "~2.2",
+    "convict": "~6.2",
+    "kapok-js": "~0.10",
+    "node-git-server": "~0.6"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "bin/",
@@ -43,5 +45,6 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "a504d6889819b548e8a5416a7194cbb6f9a93e93"
+  "gitHead": "8a142499e9f1a9e0631777796e06dd6c010d3a90",
+  "readmeFilename": "README.md"
 }