Binary distribution for compiled zot extensions

[mi-skam]

zot ext install <git-url> shallow-clones a repo and requires extension.json
at the clone root. Nothing runs after the clone. For compiled extensions that
means one of:

today	cost
"exec": "./binary" (most examples/extensions/*)	user must clone, go build, then install; ext install <git-url> is dead on arrival
"exec": "go", "args": ["run", "."] (examples/extensions/todo)	user needs the Go toolchain; recompiles on every zot start
commit binaries to git	one repo per OS/arch or a shell launcher; repo bloat; no Windows without a .cmd

Wish

Author side: tag a release, CI attaches per-platform archives. Copy-paste
workflow files for GitHub, GitLab, Gitea/Forgejo.

User side: zot ext install https://host/owner/ext works without a toolchain.

Proposal

1. Manifest: binary block

{
  "name": "mcp",
  "version": "1.2.0",
  "exec": "./mcp-bridge",
  "binary": {
    "release": "https://git.miskam.xyz/mxm/zot-mcp/releases/download/v{version}/",
    "asset": "mcp-bridge_{version}_{os}_{arch}.tar.gz",
    "checksums": "checksums.txt"
  }
}

• {version} from the manifest, {os} = runtime.GOOS, {arch} =
  runtime.GOARCH, {ext} = .exe on windows else empty. Same naming
  goreleaser produces by default, so zot's own .goreleaser.yaml is the
  template.
• checksums optional but recommended; relative to release. Format: the
  sha256sum output goreleaser emits.
• Archive is extracted into the manifest dir. Plain (unarchived) assets are
  copied to exec.

2. Behaviour

zot ext install <git-url>:

1. clone (as today)
2. if binary present and exec not present on disk (or not executable):
   download release + asset, verify against checksums if given, extract
   into the manifest dir
3. validate exec exists; otherwise roll back with a clear error including
   the URL tried

New: zot ext update <name> — git pull in the install dir, then re-run
step 2 if version changed. Cheap once step 2 exists.

3. Copy-paste CI files

Ship under examples/extensions/_ci/:

• .github/workflows/release.yml — goreleaser/goreleaser-action on v*
  tags; publishes to GitHub Releases.
• .gitlab-ci.yml — goreleaser release with GITLAB_TOKEN; publishes to
  GitLab Releases (goreleaser supports it natively).
• .gitea/workflows/release.yml / .forgejo/workflows/release.yml — same
  action; goreleaser has a gitea release target.
• .goreleaser.yaml — one builds entry, binary: {{ .ProjectName }},
  CGO_ENABLED=0, linux/darwin/windows × amd64/arm64, checksums. Identical
  to zot's own minus ldflags.

Author copies four files, sets binary in extension.json, tags. Done.

[airtonix]

related #162 (comment)

difference between your suggestion and mine, is that I'm also proposing a SBOM of sorts that lives in the users zot state dir, so the extensions themselves can be gitignored.

[patriceckhart]

@mi-skam @airtonix I am strongly in favor of it!

[mi-skam]

I agree that recording the resolved artifact could be useful, but I would call that a lockfile, not an SBOM. An SBOM normally describes the dependencies and components contained in a package. A record such as {source, version, commit, asset, sha256} instead identifies the exact installed artifact, closer to package-lock.json or flake.lock.

I would also keep generated installation state separate from settings.json: settings describe user policy, while a dedicated extensions.lock.json could record installer-resolved state and later support reproducible reconciliation. Under that model the installed extension directories can indeed be disposable/ignored and reconstructed from the lockfile, but that is broader package-manager behavior and need not block binary distribution.

My main concern with making GitHub Releases the installation protocol is tight coupling to the GitHub API. GitLab, Gitea, Forgejo, and other hosts would then each require provider-specific implementations. The manifest URL-template approach only requires HTTPS, so it works with any forge, object store, or ordinary file server. Keeping an explicit version in extension.json also avoids needing an API to resolve latest.

The CI material should be understood as examples rather than as a Go-specific requirement. The actual contract is simply that CI publishes a platform matrix using a documented asset and checksum convention. Authors can use GoReleaser, Cargo, Bun, PyInstaller, GraalVM, Nix, or anything else; zot only selects {os}/{arch}, verifies the artifact, and installs it. CI does not itself guarantee portability, but it gives authors a repeatable place to build and test every supported target.

A useful progression might be:

1. Add forge-neutral binary URL templates plus verified, staged, safe extraction.
2. Provide copy-paste CI examples for common forges and build systems.
3. Later add a dedicated extension lockfile and reconciliation.
4. Optionally add convenience adapters for owner/repo@version, without making the GitHub API the base protocol.

This keeps the initial mechanism small and universal while leaving room for the reproducible package-management model proposed in #162.