Source: ViewEdit

antorareg: Standalone Registry CLI

Source of truth

Spec version v0.3, recorded 2026-10-26. This is the source of truth for the antorareg CLI. Change it here, and add a changelog bullet, instead of editing a separate draft. Related: Trust and quality spec (stacks, baskets, tiers) and Command routing in antora-solid.

Design spec v0.3 for antorareg, the standalone CLI for registry.antora-supplemental.org. A first implementation lives at antora-supplemental/antorareg.

Principles and decisions

Core call

antorareg is a standalone tool. It is not a wrapper around the antora CLI and never shells out to it for build work. It does one job: manage what a playbook pulls in, checked against the registry.

  • Registry, not store: The name matches the registry branding. We register and index packages. We don’t host them.

  • No wrapper CLI: antorareg doesn’t proxy antora generate or re-export its flags. Users keep running antora (or npx antora) themselves.

  • Git first, npm optional: Package identity is host/owner/repo/package, never an npm name. Many Antora users avoid npm, and the tool must work for them.

  • The playbook is the user’s file: Edits keep comments, key order, quoting and blank lines. A diff after install shows only the lines that changed.

  • Reproducible by default: Every resolved package is pinned in a lockfile with a commit SHA or asset checksum.

  • Built for Antora 3: antorareg is purpose-built for the current Antora 3 line. It is not proposed upstream. On antora-solid, the antora CLI routes antora reg to it as a tool.

Decision Status

Name antorareg

Decided (Ryan)

Standalone tool, not an antora wrapper

Decided (Ryan)

Identity host/owner/repo/package

Decided

Git tags and release assets are first class; npm is optional

Decided

Single binary distribution, no npx needed

Decided

Implementation language D (LDC), native single binary

Decided (Ryan), see Implementation language

Playbook edited as text by a minimal line/CST editor that preserves comments and formatting

Decided, see Editing the playbook without damage

Registry API types generated from the OpenAPI/JSON schema

Decided

Lockfile antorareg.lock (YAML) next to the playbook; it alone records what the tool installed, with no playbook marker comments

Decided (Ryan), see Drift between the playbook and the lockfile

Extensions fetched from the lockfile into a gitignored cache; themes can be ejected (vendored) on request

Decided (Ryan), see Fetching versus vendoring

Not proposed upstream; on antora-solid the antora CLI routes antora reg to antorareg as a tool

Decided (Ryan), see the plugin spec

Package identity and sources

A package ID has four segments:

<host>/<owner>/<repo>/<package>
github.com/antora-supplemental/antora-dark-mode/antora-dark-mode
gitlab.com/acme/docs-tools/lunr-extension
  • For a single-package repo, <package> equals <repo>. The CLI accepts the three-segment short form and expands it.

  • A bare name such as dark-mode is a search, not an ID. It resolves only if the registry returns exactly one canonical entry (after variantOf/supersededBy folding). Otherwise the CLI lists candidates and exits with code 2.

  • The npm name is a registry attribute of a package and is never its identity.

Version sources, in resolution order

Source Tag or locator Notes

Release asset

GitHub/GitLab/Gitea release on tag <package>-v<semver> (monorepo) or v<semver> (single repo); asset named in registry metadata, e.g. ui-bundle.zip

Preferred for UI bundles. Checksum taken from the release API digest when the forge provides one, else computed and locked.

Git tag

<package>-v<semver> or v<semver>

Extensions referenced as git sources. Pinned to the tag’s commit SHA in the lockfile.

npm (optional)

The package’s npm attribute from the registry

Used only with --source npm or source: npm in config. Never required.

Antora-targeted versions

Releases may carry build metadata naming the Antora line they target, e.g. 4.2.0+antora.3 and 5.0.0+antora.4. SemVer ignores build metadata for precedence, so the CLI treats it as a filter: when the playbook’s Antora major is 3, only +antora.3 releases (or releases with no +antora tag that the registry marks compatible) are candidates. antorareg info shows both lines side by side.

Commands

Every command accepts --playbook <path> (default: antora-playbook.yml in the current directory, then walk up), --json, --verbose, --dry-run and --offline. Output and exit codes follow the OpenShellOrg CLI Output standard.

Command Behaviour

install <id>[@<range>] …​

Resolve, run compat checks, edit the playbook, write the lockfile, and fetch into the cache. --source git|asset|npm. --save-exact pins the range to the resolved version.

update [<id> …​]

Move to the newest version within the recorded range (or --latest across majors, with a compat re-check). No IDs means all. Vendored (ejected) packages are never overwritten: update reports the upstream changes available and offers a diff or 3-way merge help instead.

list

Show what the playbook uses, the locked version, the newest available, tier (Workshop/Listed), vendored status and any flags or security blocks from the registry. Reports drift between the playbook and the lockfile (see Drift between the playbook and the lockfile).

remove <id> …​

Remove the playbook entry and any supplemental_files it added, then prune the lockfile.

search <query>

Query the registry API. Default results follow registry visibility (graduated or grandfathered); --all includes Indexed and Workshop items.

info <id>

Metadata, versions per Antora line, provides/requires/conflicts, docs link, changelog link and latest scan result.

stack <basket-share-url>

Fetch a basket (stack) from its share URL, show the plan as a diff, then apply it as one transaction: all or nothing.

eject <id>

Copy a theme’s or extension’s source into the repo (for example ui/<name>/), mark it vendored in the lockfile with the upstream version it came from, and point the playbook at the local path. See Fetching versus vendoring.

verify

Recompute checksums of cached artifacts against the lockfile, check playbook/lockfile drift, check the .gitignore line, and audit committed assets (see Asset auditing). Exit 1 on drift. Asset findings only warn unless --strict is given.

init

Create antorareg.lock and add the cache ignore line to the repo-root .gitignore (see The .gitignore line).

migrate [<id> …​]

Turn committed copies of packages into lockfile entries (see antorareg migrate). --eject, --yes, --dry-run.

Playbook surfaces it edits

Kind Playbook key

UI bundle

ui.bundle.url (and ui.bundle.snapshot when the source is a moving ref)

Antora extension

antora.extensions[] entry, as a string or a require: map when it has config

Supplemental UI

ui.supplemental_files (a path or a list of path/contents entries)

Only one UI bundle can be active. Installing a second one is a conflict unless --replace is given. Layers (supplemental UI that sits on a bundle) are checked against the active bundle’s provides contracts.

The CLI adds no marker comments to the playbook. The lockfile alone records what it installed (see Drift between the playbook and the lockfile):

antora:
  extensions:
    - require: '@antora/lunr-extension'   # hand-written, left alone
    - require: ./.antorareg/cache/github.com/antora-supplemental/page-context/page-context/index.js

Git-sourced extensions are fetched into .antorareg/cache/<id>/ (gitignored, rebuilt from the lockfile in CI) so require: points at a local path and Antora never needs npm.

Fetching versus vendoring

  • Default, fetched: Extensions, UI bundles and themes are fetched from the lockfile into .antorareg/cache/, which is gitignored and never committed. CI rebuilds it from the lockfile.

  • Overrides go elsewhere: Theme overrides go in the playbook’s ui.supplemental_files folder (Antora’s standard override mechanism, default supplemental-ui/). On first theme install the CLI scaffolds that folder and prints its path. The cache never sits inside, or shares a path with, the overrides folder, so users never edit a file the next fetch would replace.

  • Eject, for modders: Many people find it more natural to edit what is in front of them than to write override files. antorareg eject <id> copies the package’s source into the repo (for example ui/<name>/), records it in the lockfile as vendored: true with upstream: set to the version it came from, and switches the playbook to the local path. From then on the copy is the user’s code.

  • Updates after eject: antorareg update doesn’t overwrite a vendored package. It reports that upstream has a newer version and offers a diff between upstream and the new version, or 3-way merge help against the local copy. Accepting a merge moves upstream forward.

Editing the playbook without damage

The playbook is edited as text. D’s dyaml drops comments, so it is used only to read and validate the playbook, never to write it. Writes go through a minimal line-based CST editor that understands just the few keys the tool touches: ui.bundle.url (and snapshot), antora.extensions, and ui.supplemental_files. Every other byte is copied through unchanged.

Rules:

  1. Parse. If the file has errors, stop and report; never rewrite a broken file.

  2. Change only the target nodes. Insert new list items with the indentation and quote style of their siblings.

  3. Write UTF-8 without a BOM, keep the file’s existing line endings, and write atomically (temp file then rename).

  4. Show the unified diff in --dry-run and in stack before applying.

If the editor meets a structure it can’t edit safely (flow-style lists, anchors or aliases on a target key, multi-document files), it stops and prints the exact change for the user to make by hand.

Alternatives considered: TypeScript with eemeli/yaml (best round-tripping, shared registry types, but large compiled binaries), Go goccy/go-yaml, Rust yaml-edit/saphyr, and dyaml round-tripping (loses comments).

Compatibility checks

Before any change, the CLI sends the planned set (current playbook plus the change) to the registry compat endpoint, for example POST /api/v1/compat. The registry answers with:

  • worksWith: known-good pairings. Each carries a confidence of guaranteed (declared by both sides or tested in CI) or likely (inferred from contracts or installs).

  • requires: missing dependencies, such as a layer that needs a bundle providing nav-tree@1.

  • conflicts: hard conflicts, such as two UI bundles or two search extensions with the same hook.

Behaviour: conflicts and unmet requirements block (exit 3) unless --force. Likely-only pairings print a notice. Offline, the CLI uses the cached compat data and labels the result unverified.

Lockfile

antorareg.lock sits next to the playbook. It is YAML so it diffs well and needs no extra parser.

lockfileVersion: 1
playbook: antora-playbook.yml
antora: 3
packages:
  github.com/antora-supplemental/antora-dark-mode/antora-dark-mode:
    version: 1.2.0
    range: ^1.2.0
    source: asset
    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
    sha256: 9f2c...
    surface: ui.bundle
  github.com/antora-supplemental/page-context/page-context:
    version: 1.3.0+antora.3
    source: git
    ref: page-context-v1.3.0
    commit: 4b1e0d7c...
    surface: antora.extensions

A vendored package carries vendored: true, its local path, and upstream (the version and commit it was ejected from).

antorareg install with no arguments restores exactly what the lockfile says (like npm ci). Commit the lockfile. It may be edited by hand or by the tool; the format is the same either way.

Drift between the playbook and the lockfile

There are no marker comments, so ownership comes from the lockfile alone. antorareg list and antorareg verify compare the playbook with the lockfile and flag:

  • Missing: a lockfile entry whose playbook entry is gone. Offer to remove it from the lockfile or restore it to the playbook.

  • Hand-edited: a playbook entry that no longer matches its lockfile entry (another URL, ref or path). Offer to record the change in the lockfile.

  • Stale paths: a lockfile path or cache path that no longer exists. Re-fetch or prune.

verify exits 1 on any drift so CI catches it. Entries in the playbook that the lockfile never listed are the user’s own, and are left alone.

Asset auditing

The lockfile records a files map of per-file sha256 values for every fetched package. verify uses it to report:

  • Tracked cache files: files under the cache that git tracks.

  • Committed copies: tracked files byte-identical to a package file.

  • Modified copies: tracked files that are edited copies of a package file, reported as modified copy of <pkg>@<ver>:<path>. Generic names (index.js, package.json, README.md and so on) only count when the package-relative path matches too.

  • Cache mismatches: cached files whose hash differs from the lockfile. They are refetched with a warning.

Files in ejected packages and in ui.supplemental_files are exempt and listed as info. Every finding carries advice: run antorareg eject <id>, or move the change into ui.supplemental_files.

verify --strict exits 1 on any finding. The GitHub Action runs strict by default; locally verify only warns.

The .gitignore line

On the first install, and in init, antorareg makes sure the repo-root .gitignore ignores the cache. It appends one line, the cache path relative to the repo root (.antorareg/cache/ when the playbook sits at the root), keeps the file’s existing line endings, and adds no marker comments. verify reports a missing line or a tracked cache.

antorareg migrate

For projects that copied package files into the repo by hand. migrate prints a plan first:

  • Exact copies become lockfile entries. The playbook points at the cache, the copy is deleted, and the user runs the printed git rm --cached command.

  • Modified copies become ui.supplemental_files overrides, or, with --eject, the package is ejected and the edits land in the ejected copy. Extension edits need --eject.

It applies only after an interactive yes or --yes. --dry-run changes nothing. It never stages or commits.

GitHub Action

antora-supplemental/antorareg@v0 is a composite action. It downloads the prebuilt binary for the runner (or builds from source with dlang-community/setup-dlang), caches .antorareg/cache with actions/cache keyed on the lockfile hash, then runs antorareg install --frozen and antorareg verify. Inputs: playbook (default antora-playbook.yml), version, verify (default true), strict (default true).

Configuration

Lookup order, last wins: built-in defaults, the user config ($XDG_CONFIG_HOME/antorareg/config.yml or %APPDATA%\antorareg\config.yml), the project file .antorareg.yml, environment variables (ANTORAREG_*), then flags.

registry: https://registry.antora-supplemental.org
source: git            # git | asset | npm
cacheDir: .antorareg/cache   # project fetch cache, gitignored
vendorDir: ui                # default parent for antorareg eject
globalCacheDir: ~      # default per platform
allowTiers: [listed]   # add workshop or indexed to widen
hosts:
  gitlab.example.com:
    tokenEnv: GITLAB_TOKEN

Forge tokens are read from environment variables named in config (or from gh/glab auth when present). They are never written to config or the lockfile.

Offline and cache behaviour

  • The cache is content-addressed by SHA-256 under the platform cache dir (~/.cache/antorareg, %LOCALAPPDATA%\antorareg\Cache, ~/Library/Caches/antorareg).

  • Registry metadata is cached with ETags and a 24-hour soft TTL. --offline never touches the network. It succeeds when the lockfile and cache cover the request, and otherwise fails naming what is missing.

  • Git sources use shallow fetches of the exact tag, then store an archive of the tree, not a full clone.

  • antorareg cache clean and cache path manage it.

Security

  • Pinned refs: Tags are resolved to commit SHAs at install. A tag that later moves to a different commit is an error on install from the lockfile, not a silent update.

  • Checksums: Every asset and vendored tree is SHA-256 checked on fetch and by verify. Registry metadata may also carry the expected digest; a mismatch with the forge blocks the install.

  • Registry trust signals: Security-blocked versions refuse to install. Flagged or Workshop items need --allow-tier. Results show the latest scan verdict.

  • No install scripts: The CLI never runs package lifecycle scripts. With the npm source it fetches tarballs directly and does not run npm install.

  • Signatures (later): Verify Sigstore or GitHub artifact attestations when present. Show attested in info.

  • Transport: HTTPS only. Custom hosts need to be listed in config.

Distribution

Goal: one download, no Node or npx needed.

  • Build: D compiled with LDC to a small static single binary, cross-compiled per target.

  • DUB: Also published to the DUB registry (publish-to-dub skill) so D users can dub run antorareg.

  • Targets: release binaries per the agent-rules release-targets skill, the common release target pattern from agent-rules (release-targets/patterns.sdl, current year 2026): windows-x64, windows-arm64, linux-x64, linux-arm64, macos-arm64. FreeBSD only if LDC supports it; mark it untested if it’s cross-compiled only.

  • Channels: GitHub Releases with checksums and attestations, DUB, winget, Homebrew tap, Scoop, plus a curl \| sh and irm \| iex installer that verifies the checksum.

  • Product essentials (ship-app skill): --version with a build ID, help, antorareg debug-dump (redacted), antorareg self-update (replace the binary only after the process exits; on Windows, use a rename-then-replace step), and CI release through polyglot-ci.

  • Versioning: SemVer tags per the tag-release skill.

Implementation language

Decided (Ryan): D. It compiles natively to small single binaries and cross-compiles with LDC, comparable to Go. TypeScript’s only advantages were sharing the registry’s types and a comment-preserving YAML library. Both are covered:

  • Playbook edits: a minimal text/CST editor for the few keys touched, see Editing the playbook without damage.

  • Registry types: generated from the registry’s OpenAPI/JSON schema at build time, so the CLI and the registry can’t drift.

  • Distribution: DUB plus release binaries, see Distribution.

Open questions

  1. Extensions with npm dependencies: An extension pulled from git may have its own dependencies. Bundle them at release (the registry asks for a single-file dist), or resolve them in the CLI?

  2. Compat endpoint: Is the registry API contract (/api/v1/compat, guaranteed vs likely) ready to freeze as v1?

  3. Stack conflicts: When a basket conflicts with an installed UI bundle, should stack replace it by default or stop?

  4. Playbook includes: How should it handle multiple playbooks (for example antora-playbook.local.yml)? Use --playbook only, or a workspace file?

Phased plan

  1. Phase 0, read-only: search, info, list against the registry API. Types generated from the OpenAPI schema. LDC binary pipeline, DUB package and release CI.

  2. Phase 1, edits: install, remove and update for UI bundles and extensions from release assets and git tags. Text/CST editing, lockfile, .antorareg/cache, checksums, drift detection.

  3. Phase 2, stacks and themes: stack <url> as a transaction with a diff preview. Compat endpoint integration. supplemental_files scaffolding, eject, and upstream-change reports for vendored packages.

  4. Phase 3, hardening: --offline, verify, attestations, an optional npm source, winget/Homebrew/Scoop.

  5. Phase 4, antora-solid: Register antorareg as a routed tool so antora-solid’s antora reg …​ runs it (see Command routing in antora-solid). The standalone binary is the same in both cases.

Changelog

  • v0.3 (2026-10-26): Added asset auditing with per-file hashes and verify --strict, the .gitignore line on first install and in init, antorareg migrate for committed copies, install --frozen, and the antora-supplemental/antorareg@v0 GitHub Action. Linked the first implementation.

  • v0.2 (2026-10-26): Recorded Ryan’s decisions: D implementation with a text/CST playbook editor and schema-generated registry types; extensions fetched into gitignored .antorareg/cache with antorareg eject for vendoring themes; no playbook marker comments, with lockfile drift detection in list and verify; no upstream proposal, routed as a tool in antora-solid.

  • v0.1 (2026-10-26): First draft.