antorareg: Standalone Registry CLI
|
Source of truth
Spec version v0.3, recorded 2026-10-26. This is the source of truth for the |
Design spec v0.3 for antorareg, the standalone CLI for registry.antora-supplemental.org. A first implementation lives at antora-supplemental/antoraregunchecked.
Principles and decisions
|
Core call
|
-
Registry, not store: The name matches the registry branding. We register and index packages. We don’t host them.
-
No wrapper CLI:
antoraregdoesn’t proxyantora generateor re-export its flags. Users keep runningantora(ornpx 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
installshows 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:
antoraregis purpose-built for the current Antora 3 line. It is not proposed upstream. On antora-solid, theantoraCLI routesantora regto it as a tool.
| Decision | Status |
|---|---|
Name |
Decided (Ryan) |
Standalone tool, not an |
Decided (Ryan) |
Identity |
Decided |
Git tags and release assets are first class; npm is optional |
Decided |
Single binary distribution, no |
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 |
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 |
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-modeis a search, not an ID. It resolves only if the registry returns exactly one canonical entry (aftervariantOf/supersededByfolding). 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 |
Preferred for UI bundles. Checksum taken from the release API digest when the forge provides one, else computed and locked. |
Git tag |
|
Extensions referenced as git sources. Pinned to the tag’s commit SHA in the lockfile. |
npm (optional) |
The package’s |
Used only with |
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 |
|---|---|
|
Resolve, run compat checks, edit the playbook, write the lockfile, and fetch into the cache. |
|
Move to the newest version within the recorded range (or |
|
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 the playbook entry and any |
|
Query the registry API. Default results follow registry visibility (graduated or grandfathered); |
|
Metadata, versions per Antora line, provides/requires/conflicts, docs link, changelog link and latest scan result. |
|
Fetch a basket (stack) from its share URL, show the plan as a diff, then apply it as one transaction: all or nothing. |
|
Copy a theme’s or extension’s source into the repo (for example |
|
Recompute checksums of cached artifacts against the lockfile, check playbook/lockfile drift, check the |
|
Create |
|
Turn committed copies of packages into lockfile entries (see |
Playbook surfaces it edits
| Kind | Playbook key |
|---|---|
UI bundle |
|
Antora extension |
|
Supplemental UI |
|
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_filesfolder (Antora’s standard override mechanism, defaultsupplemental-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 exampleui/<name>/), records it in the lockfile asvendored: truewithupstream: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 updatedoesn’t overwrite a vendored package. It reports that upstream has a newer version and offers a diff betweenupstreamand the new version, or 3-way merge help against the local copy. Accepting a merge movesupstreamforward.
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:
-
Parse. If the file has errors, stop and report; never rewrite a broken file.
-
Change only the target nodes. Insert new list items with the indentation and quote style of their siblings.
-
Write UTF-8 without a BOM, keep the file’s existing line endings, and write atomically (temp file then rename).
-
Show the unified diff in
--dry-runand instackbefore 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 providingnav-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
pathor 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.mdand 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 --cachedcommand. -
Modified copies become
ui.supplemental_filesoverrides, 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.
--offlinenever 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 cleanandcache pathmanage 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
installfrom 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
attestedininfo. -
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-dubskill) so D users candub run antorareg. -
Targets: release binaries per the agent-rules
release-targetsskill, thecommonrelease 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 \| shandirm \| iexinstaller that verifies the checksum. -
Product essentials (ship-app skill):
--versionwith 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 throughpolyglot-ci. -
Versioning: SemVer tags per the
tag-releaseskill.
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
-
Extensions with npm dependencies: An extension pulled from git may have its own
dependencies. Bundle them at release (the registry asks for a single-filedist), or resolve them in the CLI? -
Compat endpoint: Is the registry API contract (
/api/v1/compat, guaranteed vs likely) ready to freeze as v1? -
Stack conflicts: When a basket conflicts with an installed UI bundle, should
stackreplace it by default or stop? -
Playbook includes: How should it handle multiple playbooks (for example
antora-playbook.local.yml)? Use--playbookonly, or a workspace file?
Phased plan
-
Phase 0, read-only:
search,info,listagainst the registry API. Types generated from the OpenAPI schema. LDC binary pipeline, DUB package and release CI. -
Phase 1, edits:
install,removeandupdatefor UI bundles and extensions from release assets and git tags. Text/CST editing, lockfile,.antorareg/cache, checksums, drift detection. -
Phase 2, stacks and themes:
stack <url>as a transaction with a diff preview. Compat endpoint integration.supplemental_filesscaffolding,eject, and upstream-change reports for vendored packages. -
Phase 3, hardening:
--offline,verify, attestations, an optional npm source, winget/Homebrew/Scoop. -
Phase 4, antora-solid: Register
antoraregas a routed tool so antora-solid’santora 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.gitignoreline on first install and ininit,antorareg migratefor committed copies,install --frozen, and theantora-supplemental/antorareg@v0GitHub 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/cachewithantorareg ejectfor vendoring themes; no playbook marker comments, with lockfile drift detection inlistandverify; no upstream proposal, routed as a tool in antora-solid. -
v0.1 (2026-10-26): First draft.