Preflight - nself-org/plugins GitHub Wiki
The preflight answers one question for the free tier: do the bytes that
plugins.nself.org serves match the registry, and can each one be installed
and built from its own tarball? It exists because registry text and old probes
have passed on stale bytes. Install-based acceptance (Epic P7-PLUG, D4) waits
for a fresh report.
For every entry of the served free registry (/registry.json?tier=free) and of
registry.json at main:
-
GET /plugins/<slug>/tarballmust answer 302 (served source only). The per-item HTTP status is recorded, never acurl -fsummary. - The tarball download must answer 200.
- Its sha256 must equal the registry
checksum. - It must extract safely and contain a
plugin.jsonwhosenameandversionequal the registry entry. - A service plugin must carry
docker-compose.plugin.ymlandDockerfile. -
docker buildof the extracted tree alone must succeed (one build at a time; identical bytes are built once). - The served registry entry must equal the one at main.
Entries declared installable:false with no tarball are asserted, not skipped.
404, checksum, extract, manifest, fragment, build, drift. The
first failing stage names the class. A skipped stage is a skip, and a skip is a
failure (summary.pass is false whenever any entry is fail or skip).
bash scripts/preflight/run.sh --tier free --out "$TMPDIR/preflight.json" --md "$TMPDIR/preflight.md"
jq -e '(.entries|length) == .summary.expected' "$TMPDIR/preflight.json"Needs curl jq tar git docker. It never writes to production and needs no
licence key. Docker work is scoped to the run: its own buildx builder and
labelled images, no global prune. A cold run takes one to two hours. Exit status 0 means the report was written, not that it
passes: gate on --strict (exit 1 unless summary.pass) or summary.pass,
never on exit status alone. Use --log-dir DIR to keep failing build logs.
Details: scripts/preflight/README.md.
-
summary.expectedis the sum of both registries' own counts;entriesmust have exactly that many items. -
summary.countsandsummary.by_classshow where the failures sit. - Each entry has
source(servedormain),slug,version,result(pass,fail,skip),class, a fixedreason,http.route,http.downloadand the measuredsha256. - The markdown summary names a follow-up per failing entry: served drift goes to P7-PLUG-35 (worker deploy), a plugin goes to its batch Ticket (P7-PLUG-40 to P7-PLUG-47), an unowned slug needs a new debt id.
- An entry that drifts is always class
drift(with any other failure kept in the reason). A coverage problem (empty registry, fewer entries than the registry counts) fails the run with exit 3 andby_class.coverage. - Two runs over the same served bytes are identical once
headeris removed (diff <(jq -S 'del(.header)' a.json) <(jq -S 'del(.header)' b.json)), as long as upstream docker base-image tags resolve to the same content (reasons quote docker output).
The licensed tier is measured separately (P7-PLUG-39). The latest evidence is
kept in the hq plan evidence folder (PLUG-02-preflight.md).