Three mechanisms where there should be one. The catalogue was filled by hand, and each host separately
polled twenty-one repositories with git to work out whether a release existed — a second source of
truth for a fact one place already knew. Shipping photos 2026.09.03.02 correctly and watching alpha
not notice for ten minutes is what started this.
The timer. scripts/marketplace-cron.sh, every minute, on the machine that publishes. Safe now only
because the previous commit made the sync read tags instead of working trees; over the old one this
would have published somebody's afternoon on a schedule. Nothing is written unless the release commit
differs from the one already published, so a tick with nothing to do is one query, one fetch per repo
and no writes — about 2.7s. One timestamped summary line per tick regardless, because a fresh timestamp
is the only thing that separates "nothing to publish" from "the timer died"; a named line only for a
plugin that moved.
The badge. `updateable` now compares the tag at HEAD with the tag the catalogue says is newest —
difference, not ordering, since parsing 2026.08.27.01 works right up until somebody tags v2 and then
fails silently. refreshRemote() and its two-minute window are gone with the polling they existed to
paper over. The git rule stays as the fallback for a plugin the store cannot speak for: an unregistered
checkout, or an unreachable store. That case now reads whatever refs the last pull left, which is the
accepted cost of not making every machine poll every repository forever.
fetchCatalogue()'s cache went from five minutes to one. It only drew tiles before; now the wait for a
release to appear would have been the sync's minute plus its five.
Also: the Update button names its destination whenever a release is known, not only on `new-release`.
An untagged checkout reports `untagged` and used to lose the tag with it, so the button said "Update"
and the owner had to guess where it landed — the marketplace knows, even for a checkout that has never
fetched it.
Verified: forced a stale row, the timer republished it inside 60s and logged one line. Badge decisions
checked against the live catalogue for seven plugins, including the two shapes that matter — at a tag
the store agrees with, and untagged with a release known only to the store. 9 release tests pass, 100%
of release.ts covered, four of them new and all against real repositories.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Split out of docs/marketplace.md so the design document stays about how it works.
Ranked by what blocks something rather than by size: submissions first (until a
stranger's manifest can be read without executing it, the catalogue is ours only
and everything below is cosmetic), then plugin upgrades not migrating, then
staleness, then scale.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The site is up on HTTPS with a Let's Encrypt certificate, proxied to :9100, and
serving the three plugins out of `officer_marketplace`. An Officer install with no
configuration now reads its catalogue from it.
── What is running ──
PM2 entry added to THIS machine's ecosystem only. Deliberately not in
officer-setup's CORE_PROCESSES: the marketplace is one website officer.dev hosts,
not something every install should run — a copy on every machine would serve a
stale catalogue on a port nobody asked to open.
nginx (NPM host id 7) → 172.20.0.1:9100, with a ufw rule for the docker bridge.
That rule is not optional and its absence does not look like a firewall problem:
without it nginx HANGS until proxy_connect_timeout rather than being refused,
which is how the apptest hosts wasted an hour a few days ago.
── READMEs ──
`music`, `offscale` and `example` now have proper READMEs, written against their
own code and pushed to their own repos. They render on the plugin's page in the
store and are what a self-hoster reads before installing. The example's is a
tutorial as much as a shop window — it is the document a plugin author reads
first, and every convention in it was verified in `discover.ts` rather than
restated from memory.
`music`'s remote was HTTPS with no credentials on this box, so it could not be
pushed; switched to SSH like the other two. The catalogue still advertises HTTPS —
`marketplace-sync` converts — which is the property that matters, since an
`ssh://` clone URL only works on the machine that published it.
── Writing them was the cheapest audit available ──
Reading each plugin against its own documentation turned up ~20 real defects, all
recorded in TODO.md and none fixed here. The pattern worth naming: offscale is
still branded "headscale" in user-visible panel names and in a persisted terminal
session id, and its PLUGIN.md states outright that the ACL assistant is
deliberately unwired — while `sidecar/assist.ts`, `claude-proxy.ts` and
`PolicyAssistant.tsx` all ship. Documentation that confidently describes the
opposite of the code is worse than none.
Also fixed the docs on the frozen lockfile: both CLAUDE.md and bunfig.toml named
`bun install --no-frozen-lockfile` as the escape hatch, and bun 1.3.14 has no such
flag — it is ignored and the install fails anyway.
tsgo clean, 873 pass / 7 fail unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5