`plugin add <url>` holds the id AND the source URL but offers no `[update]` stanza — the one moment "easy update" is free, and it is dropped #257

New issue

Closed

opened 2026-09-10 16:13:22 +02:00 by buildagent · 0 comments

buildagent commented

2026-09-10 16:13:22 +02:00

Member

The seam

code-index plugin add <URL> --sha256 <digest> is the moment the tool knows both halves of an [update] entry: the package id (it just parsed the manifest) and the source URL (the operator just typed it). It writes neither, and says nothing about them. The operator must afterwards discover that updates exist, learn the TOML shape, and hand-edit .code-index.toml.

Measured, shipped binaries at ee39fd1:

###### install the published package FROM ITS URL
add EXIT=0

###### what does .code-index.toml say now?
[index]
--- end of file ---

Then plugin update:

note   this project's `.code-index.toml` declares no `[update."<package id>"]` section,
       so nothing was checked. THAT IS A MEASUREMENT AND NOT A CLEAN BILL: an absent
       entry means no package updates itself into a project that never asked
update_notifications 0 of 0 configured package(s) have something to act on

That disclosure is correct and good — it refuses to imply the project is current. The gap is that nothing anywhere tells the operator what to write, at the one point where the tool could have written it.

Why this is the payload's job, not prose's

The repo's standing rule is that a disclosure belongs in the payload. plugin add already prints twenty-odd disclosure lines built from the verified bytes, including note lines about what approving does. Given a URL it could print the stanza verbatim:

update_config       this project configures no automatic update for `de.h-dv.xaml`.
                    To check this source for new versions, add to .code-index.toml:

                      [update."de.h-dv.xaml"]
                      source     = "<the URL you just gave>"
                      auto_apply = false   # check and notify only

                    `auto_apply = true` applies a new version unattended, but ONLY
                    where nothing about the authority changed — see `plugin update --help`.

Copy-pasteable, derived from values already in hand, and it costs the operator nothing to ignore. A --configure-update flag that writes the stanza (the way link edits [[links]] without hand-editing TOML, preserving comments and writing atomically) would be the natural next step, but the disclosure alone closes the discovery gap.

Note plugin add <FILE> should not print a source, because there is no URL to put in it — the stanza offer is specifically the URL arm. That asymmetry is the point: the URL arm is the one where the information is free.

Second, smaller finding in the same area: `plugin doctor` loses its remediation after the first check

crates/cli/src/plugin_doctor.rs has two arms for "no updates configured", and only the earlier one tells the operator what to do:

UpdateRecordState::Absent (:1112-1117) — Finding::ok whose text ends "Configure [update."<package id>"] in .code-index.toml and run code-index plugin update --check". Good.
found.packages.is_empty() (:1130-1135) — reached once a check has run and found nothing configured — Finding::ok reading only "a check ran and this project configures no [update."<package id>"] entry, so ZERO packages were checked. A measurement, not a clean bill". Accurate, and with no remediation at all.

Measured:

[  OK  ] package updates          a check ran and this project configures no `[update."<package id>"]` entry, so ZERO packages were checked. A measurement, not a clean bill

So the operator who runs plugin update first (the natural order — the doctor line told them to) and then plugin doctor is the one who gets less help. Finding::ok carries no fix field, so this is a small design question rather than a one-line change: either fold the configure hint into the message, or give the ok-with-advice case a constructor.

Scope note

The URL form (#236, 4b02fb5) and plugin update (#237, eddaa08) both post-date the v0.27.1 tag (f9ddfaf), so no published release contains either yet. Fixing this before the next release is what makes the owner's "easy install&update mechanism" true on first contact rather than after a source read.

Found by Lane C walking the operator path against the published v0.27.1 release and then against master.

## The seam `code-index plugin add <URL> --sha256 <digest>` is the moment the tool knows **both** halves of an `[update]` entry: the package id (it just parsed the manifest) and the source URL (the operator just typed it). It writes neither, and says nothing about them. The operator must afterwards discover that updates exist, learn the TOML shape, and hand-edit `.code-index.toml`. Measured, shipped binaries at `ee39fd1`: ``` ###### install the published package FROM ITS URL add EXIT=0 ###### what does .code-index.toml say now? [index] --- end of file --- ``` Then `plugin update`: ``` note this project's `.code-index.toml` declares no `[update."<package id>"]` section, so nothing was checked. THAT IS A MEASUREMENT AND NOT A CLEAN BILL: an absent entry means no package updates itself into a project that never asked update_notifications 0 of 0 configured package(s) have something to act on ``` That disclosure is **correct and good** — it refuses to imply the project is current. The gap is that nothing anywhere tells the operator what to write, at the one point where the tool could have written it. ## Why this is the payload's job, not prose's The repo's standing rule is that a disclosure belongs in the payload. `plugin add` already prints twenty-odd disclosure lines built from the verified bytes, including `note` lines about what approving does. Given a URL it could print the stanza verbatim: ``` update_config this project configures no automatic update for `de.h-dv.xaml`. To check this source for new versions, add to .code-index.toml: [update."de.h-dv.xaml"] source = "<the URL you just gave>" auto_apply = false # check and notify only `auto_apply = true` applies a new version unattended, but ONLY where nothing about the authority changed — see `plugin update --help`. ``` Copy-pasteable, derived from values already in hand, and it costs the operator nothing to ignore. A `--configure-update` flag that writes the stanza (the way `link` edits `[[links]]` without hand-editing TOML, preserving comments and writing atomically) would be the natural next step, but the disclosure alone closes the discovery gap. Note `plugin add <FILE>` should **not** print a source, because there is no URL to put in it — the stanza offer is specifically the URL arm. That asymmetry is the point: the URL arm is the one where the information is free. ## Second, smaller finding in the same area: `plugin doctor` loses its remediation after the first check `crates/cli/src/plugin_doctor.rs` has two arms for "no updates configured", and only the earlier one tells the operator what to do: * `UpdateRecordState::Absent` (`:1112-1117`) — `Finding::ok` whose text ends *"Configure `[update."<package id>"]` in `.code-index.toml` and run `code-index plugin update --check`"*. Good. * `found.packages.is_empty()` (`:1130-1135`) — reached once a check **has** run and found nothing configured — `Finding::ok` reading only *"a check ran and this project configures no `[update."<package id>"]` entry, so ZERO packages were checked. A measurement, not a clean bill"*. Accurate, and with **no remediation at all**. Measured: ``` [ OK ] package updates a check ran and this project configures no `[update."<package id>"]` entry, so ZERO packages were checked. A measurement, not a clean bill ``` So the operator who runs `plugin update` first (the natural order — the doctor line told them to) and *then* `plugin doctor` is the one who gets less help. `Finding::ok` carries no `fix` field, so this is a small design question rather than a one-line change: either fold the configure hint into the message, or give the ok-with-advice case a constructor. ## Scope note The URL form (#236, `4b02fb5`) and `plugin update` (#237, `eddaa08`) both post-date the `v0.27.1` tag (`f9ddfaf`), so no published release contains either yet. Fixing this before the next release is what makes the owner's *"easy install&update mechanism"* true on first contact rather than after a source read. Found by Lane C walking the operator path against the published v0.27.1 release and then against `master`.