haul/docs/auto-update-plan.md

Auto-update — plan

Status: planned, not started. Blocked on decisions at the bottom of this file. No code written.

Ben wants this as a standalone, reusable Go module, not something buried in haul — so it can be dropped into dial, haul, and whatever comes next. This doc lives in haul's repo because that's where the conversation started; the module gets its own repo and its own README.

The behaviour to copy is the self-updater in ShippingTracker (HelloWorld/Updater.vb).

Research already done — don't redo this

Verified 2026-07-29/30 against the live gitea instance:

• The releases API is readable anonymously — both .../repos/bsncubed/ShippingTracker/releases/latest and .../repos/bsncubed/haul return 200 with no token. The updater needs no credentials.
• .../repos/bsncubed/haul/releases returns []. haul's repo is public; the 404 on releases/latest is just "no releases yet", not permissions.
• dial already publishes proper releases. Tag 0.2.0, draft: false, prerelease: false, with six assets: dial-darwin-amd64, dial-darwin-arm64, dial-linux-amd64, dial-linux-arm64, dial-windows-amd64.exe, and SHA256SUMS.
• Release JSON exposes tag_name, draft, prerelease, and assets[] with name and browser_download_url.
• Gitea serves go-import meta tags (<meta name="go-import" content="gitea.apointless.space/bsncubed/haul git https://…">), so go get gitea.apointless.space/bsncubed/<module> resolves.

What ShippingTracker's updater does

1. GET /api/v1/repos/{owner}/{repo}/releases/latest; take tag_name, match assets by exact filename.
2. Parse the tag into a version — tolerates a leading v, pads missing components with 0.
3. Silent vs. loud. A startup check swallows every failure (offline, DNS, timeout, non-200, malformed JSON) with no UI at all. A user-clicked check reports "you're up to date" and surfaces errors.
4. Prompts with current vs. available before doing anything.
5. Pre-flights write permission next to the executable, so a read-only install directory fails early rather than half-applying an update.
6. Streams the download to <exe>.new behind a progress window.
7. Verifies SHA256 against a checksum asset in sha256sum format (<hash> <filename>). Absent checksum asset → installs unverified.
8. Swaps by rename: running exe → .old, .new → exe, rolling back if the second rename fails. .old deleted on next launch.
9. On any failure, offers to open the releases page in a browser.

The rename dance exists because Windows won't delete a running binary but will rename one. Linux and macOS also allow renaming a running executable (the inode stays live), so one code path covers all three.

The module

Its own repo — something like gitea.apointless.space/bsncubed/selfupdate (name is an open decision). Separate module, separately versioned, imported by each project.

The single most important constraint: no UI

ShippingTracker's updater calls MessageBox.Show directly. A reusable module cannot do that, because the three consumers could not be more different:

Consumer	UI
ShippingTracker	WinForms message boxes
haul	Fyne GUI, and widgets may only be touched from the UI thread via fyne.Do
dial	Bubble Tea TUI, an Elm-style message loop

So the module is pure logic plus callbacks: it decides, downloads, verifies and swaps; the host application does every prompt, progress bar and error dialog. That also makes it trivially testable against httptest.

Sketch

type Config struct {
    BaseURL     string // https://gitea.apointless.space
    Owner, Repo string
    Current     Version
    AssetName   func(goos, goarch string) string // default: <bin>-<goos>-<goarch>[.exe]
    ChecksumAsset string // "SHA256SUMS" (dial) or "checksums.txt" (ShippingTracker)
    HTTPClient  *http.Client
    UserAgent   string
    AllowPrerelease bool
}

func Check(ctx, cfg) (*Release, error)          // fetch, parse tag, pick this platform's asset
func (r *Release) Newer(v Version) bool
func Download(ctx, r, dst string, onProgress func(done, total int64)) error
func Verify(path, checksumURL, assetName string) error
func Apply(newPath string) error                 // rename dance, rollback, chmod 0755
func CleanupOld() error                          // delete <exe>.old; never errors

onProgress is the seam: haul marshals it through fyne.Do, dial turns it into a Bubble Tea message, ShippingTracker-style apps call it directly.

Configurable because it genuinely varies

• Checksum asset name — dial uses SHA256SUMS, ShippingTracker uses checksums.txt. Proof this can't be a constant.
• Asset naming — a func(goos, goarch) hook, defaulting to dial's existing <binary>-<goos>-<goarch>[.exe] convention, which haul should adopt too.
• Forge — gitea's release JSON is GitHub-shaped, so the same client covers GitHub for free. Worth keeping the fetch behind a small interface.

Stays with each project

Version stamping, the release pipeline, asset naming, and all UI.

Consumers, in order

dial first — it is not blocked. Pure Go, cross-compiles trivially, and its make dist already produces all five platform binaries and SHA256SUMS, which release 0.2.0 already has attached. dial can ship auto-update as soon as the module exists, which makes it the honest test of whether the API is actually reusable.

haul second, and it needs work first:

1. haul has no version at all. cmd/haul has no version variable, which is why the Makefile omits -X main.version (a -X against a non-existent symbol is silently a no-op). Without it every check reports "up to date".
2. haul cannot build its own release assets. It is cgo, so make dist produces the native binary only — no macOS or Windows assets exist to download. Needs fyne-cross over Docker (installed) or real machines.
3. Linux binaries don't travel. haul links dynamically against libGL, libX11, libc and ten others; a binary built on Ubuntu 24.04 may not start on another distro. It would download, swap itself in, then fail to launch — the worst failure mode an updater has. dial, being static, has no such problem. Options: build against the oldest glibc worth supporting, ship Linux without auto-update, or accept it.

Security note

A checksum is not a signature. SHA256SUMS sits on the same server as the binary, so it catches corruption and truncation but not a compromised gitea — anyone who can replace one can replace the other. ShippingTracker accepts this. Closing the gap means a minisign/ed25519 signature with the public key compiled into each consumer, roughly 40 extra lines in the module.

Consuming the module

Because the host is self-hosted, dependent projects will likely want:

go env -w GOPRIVATE=gitea.apointless.space/*

so the module is fetched straight from gitea rather than through proxy.golang.org and the checksum database. Worth confirming in practice — the repo is public, so the proxy path may work unaided.

Phasing

Phase	Work
0	Create the module repo; Check/Newer plus version parsing, tested against httptest
1	Download/Verify/Apply/CleanupOld, tested in a temp dir
2	Adopt in dial — the real proof of reusability, and shippable immediately
3	haul phase A: version stamping (var version, -X, haul --version)
4	haul phase B: release pipeline via fyne-cross, first tagged release
5	haul phase C: wire the module in — silent check on the connect window, a manual "Check for updates" button, progress and error dialogs
6	READMEs: the module's own, plus a section in each consumer

Open decisions

1. Module name and path — selfupdate? gitup? bsncubed/selfupdate?
2. Auto-check on startup, or manual only? ShippingTracker does both. Silent startup checks mean the app contacts gitea on every launch.
3. Which platforms get auto-update? Suggestion: exclude haul's Linux build for the dynamic-linking reason above. dial is fine everywhere.
4. Checksums only, or real signatures?
5. Confirm dial goes first — it's unblocked and validates the API, whereas haul can't produce release assets yet.