How the registry commands work

This is the detail behind Installing and updating from the registry, Yanks, takedowns and advisories, Search and Developing for the registry: what each command does and shows. The registry is https://jadpo.dev/registry/v1/; JADPO_REGISTRY names a stand-in, over HTTPS or on this machine.

add and update take a release in this order, and stop at the first that fails (install.not_proved), leaving the lock and packages/ as they were: the release's details; the log's head, which has to extend the last one kept in .jadpo/registry_head, by log/consistency; log/proof at that head; the head kept; the archive, whose files have to have the digest the log holds; then the checks for a package from anywhere, compiling it and comparing its surface with its code; and lastly that the files are what the registry said: its name in code, its publisher (the scope of the name asked for), its version, its digest and the surface it shows. The facts on the screen are worked out from those files, not taken from the registry.

text

$ jadpo package add @acme/postcodes✓ Added Postcodes.v2 2.1.0    folder     packages/postcodes/v2    source     registry @acme/postcodes    publisher  @acme, verified    age        first released 2026-08-14, 81 days ago    log        entry 412 of 1024    surface    matches its codeFacts  kind      library, pure  storable  OutwardCode, UkPostcode, WrittenPostcode  failures  uk.tidy: InvalidPostcode✓ package added  Postcodes.v2 2.1.0 · 1 function · 3 types · 1 failure→ jadpo package show postcodes  shows what it offers

The lock's line is package Postcodes.v2 version 2.1.0 registry @acme/postcodes digest sha256:…. A yanked release is install.yanked, even named with --to; a pre-release is taken only when named.

update chooses among the installed major version's releases that aren't yanked or pre-releases: the newest at least three days old or marked urgent. A time that can't be read, or one still to come, is never old enough. It never goes down, and a new major is named and left, since it is a new package beside the old (jadpo package add). What it leaves is listed:

text

$ jadpo package update postcodesNewer, not taken  2.2.0  1 day old, taken from 2026-11-05  3.0.0  a new major, added beside this one with `jadpo package add`✓ Postcodes.v2 is up to date  2.1.0 · registry @acme/postcodes · 2 newer→ jadpo package update postcodes --to 2.2.0  takes it now, after showing its facts

When it takes one, it shows when that was released, the facts, a new publisher, the surface's changes and every change record entry since the installed version. An urgent release says why, from the advisory against what is installed:

text

$ jadpo package update postcodes✓ Updated Postcodes.v2 from 2.0.0 to 2.0.1    folder    packages/postcodes/v2    source    registry @acme/postcodes    released  2026-11-03, today    urgent    ADV-7: Reads the wrong outward code.    surface   matches its codeFacts  kind      library, pure  storable  UkPostcode, WrittenPostcode  failures  uk.tidy: InvalidPostcodeChange record, 2.0.0 to 2.0.1  ~ behaviour changed  uk.parse  a fix: it read the wrong outward code✓ package updated  Postcodes.v2 2.0.1→ jadpo check  checks the app against 2.0.1

search <words> sends the words, and --kind. --from and --to read a standard type as it is, or a type of the app in this folder, whose shape is what goes: Text { max_length: 12 }, never a name or source of the app's. Results keep the registry's order, the standard library's first:

text

$ jadpo package search uk postcodeStandard library  text.upper                Its account mentions postcode.Packages  @acme/postcodes uk.parse  Its account mentions uk, postcode.✓ 2 found  1 in the standard library · 1 in a package→ jadpo package add @acme/postcodes  installs the first package found

audit asks about the lock's registry lines and sends nothing when there are none, and the others are counted as not checked. A declaration is reached when the graph's calls, uses and raises lead to it from anything of the app's own, tests left out. An app with errors has holes in its graph, so every advisory against it counts as reached.

text

$ jadpo package auditerror: `Postcodes.uk.parse` has an advisory: ADV-7  reason: Reads the wrong outward code. It is against 2.0.0 to 2.1.2, and the app has 2.0.0 and reaches it.  next: Run `jadpo package update postcodes`, or give `--to` a release that fixes it (human)  rule: package.advisoryNot reached  ADV-9  Postcodes.OutwardCode, 2.0.0 to 2.1.2: Too short for some codes.✗ advisories the app reaches  1 reached · 1 not reached · 1 package→ jadpo package update postcodes  takes a release that fixes it

publish [--dry-run] runs in the package's own repository, with the package at its root. The tag is v and the version its committed surface says, and the repository is origin's address, an ssh one as the same repository's https:// address. It stops with publish.not_at_tag unless the checkout is that tag's commit, unchanged, and origin has the tag at the same commit, then runs the bar as verify does against the tag before, then asks the registry and waits up to 20 minutes for its verifier. A dry run passes in any state but failed or cancelled, and nothing it does is published. A package with no publisher stops at the bar, having asked nothing (publish.publisher_missing). A failed publisher row, or facts naming another publisher than the checkout does, is publish.publisher_mismatch rather than publish.failed.

text

$ jadpo package publish✓ Asked the registry to release Postcodes.v2 2.1.0    publisher   @acme    repository  https://github.com/acme/postcodes    tag         v2.1.0    state       pendingRegistry's bar✓ compiles  no errors✓ tests     3 tests● release pending  Postcodes.v2 2.1.0 · a releaser confirms it with a passkey on jadpo.dev

preview [<folder>] serves one read-only page on this machine, on a port the system picks, until it is stopped: the verdict, its facts, its changes since the last tag, the publishing bar, its surface, changelog and guide, by the same run of the bar as verify, which writes nothing. It runs the bar again only when the package's files have changed. What only the registry can add, the written account, whether its publisher is verified, the Jadpo releases it works with and the last contract run, is named and not imitated.

text

$ jadpo package previewjadpo package preview  Postcodes.v2 · nothing is published · ctrl-c stops it  page  http://127.0.0.1:50321/