pluginfetch

type Fetched struct {
	Dir     string
	Repo    string
	Ref     string
	Version string
	SHA     string
	// Digest covers the tree AS LANDED — after stripSrcSuffix. It is the lock's
	// pin, and `w17ctl verify` recomputes it over the installed tree, so it has
	// to describe what is on disk in a consumer's project.
	Digest string
	// PublishedDigest covers the tree AS PUBLISHED — before stripSrcSuffix, so
	// `.go.src` still carries its suffix and the plugin's own tests are still
	// present.
	//
	// THE SIGNATURE IS ABOUT THIS ONE, and the two are never equal: the strip
	// renames every `.src` and deletes every test, so a tree that has been
	// through it hashes to something the publisher never signed. `plugin sign`
	// digests the registry's bytes (it runs on the rendered tree, before any
	// consumer has touched it), which makes this the only digest a claim can be
	// checked against.
	//
	// Keeping both is not redundancy — they answer two different questions.
	// "Are these the bytes that were released?" is a signature question and only
	// the published form can answer it. "Is this working tree still the one that
	// was installed?" is a pin question and only the landed form can.
	//
	// For an AUTHOR tree fetched by commit (isAuthorTree), "as published" is the
	// tree as RENDERED on this machine, since the repository holds no rendered
	// form for that commit. Such a tree is unsigned, so no signature is checked
	// against it.
	//
	// For a release TAG that carries a signature in its message (tagSignature),
	// it is the tree as the tag holds it, taken before any render: that is what
	// the publisher signed, and the only form every client computes alike — a
	// render's bytes depend on the renderer's version.
	PublishedDigest string
	// Signature is the contents of SignatureFile, VERBATIM, when the published
	// tree carries one, or the signature block of the release tag's message
	// when the tag carries one — and empty otherwise.
	//
	// Not trimmed, not parsed. The file is a structured body the console wrote
	// and the console reads; a client that tidied it would be a third opinion
	// about a format only two ends need to agree on. Verifying an artefact is a
	// console job.
	//
	// Empty is the ordinary case today — every plugin published before signing
	// existed is unsigned — and the console reports that differently from a
	// signature that fails to verify.
	Signature string
}

type Source struct {
	// Repo is any git URL: the internal plugins repo, or a third party's.
	Repo string
	// Plugin is the catalogue name, which is also the top-level directory in
	// the repo and the tag prefix — one string, so the three cannot drift.
	Plugin string
	// Version is the tag's version part, `v`-prefixed (`v0.1.0-rc.1`).
	//
	// Empty when Commit is set. Exactly one of the two names what to fetch,
	// and validate() enforces that rather than picking a winner: a Source
	// carrying both would resolve to whichever the code happened to read
	// first, and the lock would then record a pin nobody asked for.
	Version string
	// Commit is a full 40-hex commit SHA, for fetching a plugin that has NOT
	// been released.
	//
	// The reason this exists: a plugin's author tree leads its published
	// releases by design, so the only way to try a fix before it is tagged was
	// to tag it. That turns every experiment into a release candidate in a
	// registry other people read. A commit is the honest way to say "this exact
	// tree, which nobody has published".
	//
	// FULL sha, never abbreviated: an abbreviation is not a stable name for a
	// tree (it can become ambiguous as the repository grows), and this value
	// goes into a LOCK, where it has to keep meaning the same bytes years
	// later. Abbreviation is a display concern — see shortSHA in cmd/plugin.
	Commit string
}