Command Routing in antora-solid
|
Source of truth
Spec version v0.2, recorded 2026-10-26. This is the source of truth for command routing in antora-solid’s |
Design spec v0.2. Antora 3 has no way for an extension to add a CLI subcommand. antora-solid’s own antora CLI routes subcommands to tools and extensions natively. This is antora-solid’s design, not a proposal for upstream Antora. antorareg stays purpose-built for current Antora 3 and is one of the routed tools.
Context
Antora 4 (antora-solid) as recorded in the antora-solidstart notes:
-
A Node orchestrator (the build-time compiler) reads git sources and the playbook and emits a content manifest.
-
A SolidStart reader shell serves the manifest.
-
asciidoctor-d converts AsciiDoc over a CLI or IPC.
The orchestrator owns the antora CLI, so command registration belongs there. Extensions on the Antora 4 line are a parallel SemVer line (+antora.4 build metadata, or a /next entry point) gated by the playbook runtime.
Antora 3 today: antora has generate only. Extensions register through register(context) and listen to generator events. There’s no hook into the commander program, so tools like antorareg are standalone binaries. antora-solid doesn’t change that for Antora 3; it routes to those same binaries.
Principles and decisions
|
Core call
The |
-
Declare, then load: Each package’s manifest lists its commands. The entry module is imported only on invocation.
-
Namespaced by default: Plugin commands live under a namespace (
antora reg …). Built-in commands always win. -
Small context, no build: A command gets the parsed playbook, a logger, paths and a cache, not a generator run. It may ask for a build explicitly.
-
Same trust as extensions: A command is code the user chose to install. There’s no sandbox claim we can’t keep, but there are clear consent and visibility rules.
| Decision | Status |
|---|---|
Static declaration in |
Proposed |
Discovery from the playbook plus project-local installed packages |
Proposed |
Namespace required, e.g. |
Proposed |
No full build in the command context; |
Proposed |
|
Decided (Ryan) |
antora-solid’s own design; not proposed upstream |
Decided (Ryan) |
How other CLIs do it
| Tool | Discovery | Registration | Takeaway |
|---|---|---|---|
git |
Any |
None. The binary is the command. |
Zero coupling and language-agnostic, but no shared context, no completion metadata, and |
cargo |
|
None. Cargo runs it with |
The same as git, plus a convention for passing the subcommand name. Works well because |
npm / yarn |
npm: none beyond |
Yarn: a plugin module exports |
Project-scoped, lockfile-pinned plugin lists are reproducible. The downside is that Yarn loads all plugins eagerly. |
oclif |
|
A manifest ( |
The best fit: a static manifest drives help and completion without loading code. Namespaced topics. Hooks ( |
We take oclif’s manifest and lazy loading, Yarn’s project-scoped list, and git/cargo’s fallback for a non-JS command (an exec entry).
Discovery
Sources, in order:
-
Built-ins (
generate,serve,help,version…). Reserved. -
Playbook:
antora.extensions[]entries whose package declaresantora.commands. Commands are available only when a playbook is found. This is the default, and it matches how extensions are enabled today. -
Project-installed packages: packages in the project’s
node_modulesor theantoraregvendor dir (.antorareg/) that declare commands and are listed inantora.commands.enablein the playbook. This covers tools you want before they’re in the playbook, such asantora reg installon a fresh project. -
User-global (optional, off by default):
~/.config/antora/commands.ymllisting packages by path. Needed soantora reg initworks with no playbook.
Antora builds a command index from the manifests and caches it keyed by the lockfile or package.json hashes, so startup cost doesn’t grow with plugin count.
Registration API
Static declaration
{
"name": "@antora-supplemental/antorareg",
"antora": {
"runtime": ">=4.0.0",
"commands": {
"namespace": "reg",
"entry": "./dist/commands.js",
"list": [
{ "name": "install", "summary": "Add a registry package to the playbook",
"args": [{ "name": "id", "variadic": true }],
"options": [{ "flags": "--source <kind>", "choices": ["git", "asset", "npm"] },
{ "flags": "--dry-run" }] },
{ "name": "list", "summary": "Show registry packages in this playbook" }
]
}
}
}
Runtime module
// dist/commands.js
export default function registerCommands (registry) {
registry.command('install', async (args, options, context) => { /* ... */ })
registry.command('list', async (_args, options, context) => { /* ... */ })
}
Antora checks at load time that the runtime registration matches the static manifest. A mismatch is a load error naming the package, which stops drift between help text and behaviour.
An exec form supports commands written in other languages, git style:
{ "name": "lint", "exec": "./bin/asciidoc-lint", "summary": "Lint sources" }
Antora runs it with the arguments and passes context through ANTORA_PLAYBOOK, ANTORA_CACHE_DIR, ANTORA_LOG_FORMAT, plus a JSON context file at ANTORA_CONTEXT_FILE.
Namespacing and collisions
-
Every plugin needs a
namespace([a-z][a-z0-9-]*). Commands are invoked asantora <namespace> <command>. -
Built-in names and a reserved list (
generate,serve,help,version,init,config,cache,plugin,ext) can’t be namespaces. -
If two packages claim the same namespace, both are disabled for that namespace and Antora prints both package IDs and how to fix it:
antora.commands.alias: { reg2: <package> }in the playbook. -
A plugin may ask for a top-level alias (for example
antora installforreg install). Aliases apply only when the user opts in throughantora.commands.aliasin the playbook. They’re never automatic. -
The registry checks namespaces at publish time and warns about clashes with Listed packages.
Help and completion
-
antora helplists plugin namespaces in a separate "Extension commands" section with the source package and version. -
antora help reg installandantora reg install --helprender from the static manifest. No plugin code runs. -
antora completion bash|zsh|fish|pwshemits a script that callsantora __complete <words>. That answers from the cached command index. Plugins can add acompletefunction for dynamic values (for example package IDs from the registry), called only for that plugin’s words, with a 500 ms timeout.
Lifecycle and context
-
Parse argv and resolve the command from the index.
-
Load the playbook (
--playbook, or discover it). Commands that declare"playbook": "optional"run without one. -
Import the entry module, call
registerCommands, and validate against the manifest. -
Call the handler with
(args, options, context). -
Exit with the handler’s return code. Errors are formatted by Antora’s logger.
The context object:
| Member | Purpose |
|---|---|
|
The parsed, frozen playbook, plus |
|
Antora’s pino logger, scoped to the plugin, honouring |
|
|
|
|
|
An explicit, opt-in generator run (or a partial one, such as |
|
TTY-aware confirmation; returns the default under |
|
An |
Plugins also get two hooks: commandsRegistered (to see the full index, for meta-tools) and beforeCommand/afterCommand (for telemetry-free timing and cleanup). Normal build extensions don’t see command runs.
Security and trust model
-
Code you chose: Plugin commands carry the same trust as extensions in the playbook. Antora doesn’t claim to sandbox them.
-
No surprise sources: Commands come only from the playbook, an explicit enable list, or the opt-in user config. There’s no scanning of
PATHor globalnode_modules, so a stray package can’t addantora deploy. -
First-run consent: The first time a namespace appears (or its package changes version), an interactive run asks for confirmation and lists the package, version and source. The answer is stored per project.
--yesandCI=trueskip the prompt, and in CI the lockfile is the consent. -
Visibility:
antora plugin listshows every namespace, package, version, source and checksum. -
Registry signals: When the package is in the registry, Antora (or the
regplugin) can show tier and scan status. A security-blocked version prints a warning and refuses to run unless--allow-blocked. -
Lazy loading as defence: Because help and completion never import code, listing commands is always safe.
antorareg as a routed tool
antorareg is a D binary built for Antora 3. antora-solid doesn’t embed or port it; its antora CLI routes the reg namespace to the binary through an exec entry:
| Antora 3 | antora-solid | |
|---|---|---|
Invocation |
|
|
Distribution |
Standalone binary (no Node) |
The same binary, registered as a routed tool in the playbook, project or user-global config |
Playbook edits |
Its own text/CST editor |
The same; antora-solid passes the playbook path through |
Logger and output |
Its own, following the CLI Output standard |
The same, with |
Bootstrapping |
Works with no playbook ( |
Registered through the user-global config so |
The static manifest for the reg namespace (command names, summaries, options) ships with antorareg, so help and completion work without running it.
Minimal example extension
// package.json
{
"name": "antora-hello",
"type": "module",
"antora": {
"runtime": ">=4.0.0",
"commands": {
"namespace": "hello",
"entry": "./commands.js",
"list": [{ "name": "components", "summary": "List components named in the playbook" }]
}
}
}
// commands.js
export default function registerCommands (registry) {
registry.command('components', async (_args, options, { playbook, logger }) => {
const urls = playbook.content.sources.map((s) => s.url)
if (options.json) process.stdout.write(JSON.stringify(urls) + '\n')
else urls.forEach((u) => logger.info(u))
return 0
})
}
# antora-playbook.yml
antora:
extensions:
- require: antora-hello
$ antora help
...
Extension commands:
hello components List components named in the playbook (antora-hello 0.1.0)
$ antora hello components
Open questions
-
Manifest location: Use
package.jsonantora.commands, or a separateantora-commands.jsongenerated at build time (oclif style) for non-npm git packages? -
Playbook writes: Should Antora own write-back (
playbook.document()with a diff) or leave it to plugins? -
Consent store: Where should consent answers live, per project (
.antora/consent.json) or per user?
Phased plan
-
Phase 0: Prototype in the antora-solidstart orchestrator: a static manifest, lazy load, namespaces, and help.
-
Phase 1:
execrouting, context (playbook,logger,paths,prompt), consent,antora plugin list, and the first routed tool,antora regtoantorareg. -
Phase 2: Completion (
__complete),context.build(), and registry trust signals.