wingbits/AGENTS.md

AGENTS.md

Project-level instructions for working in this repository. Read this before touching the filesystem.

What this is

Go helper packages for talking to a Wingbits ADS-B station (e.g. the MGW310) and decoding the readsb / tar1090 JSON files it serves.

Module: gitea.libretechconsulting.com/rmcguire/wingbits (Go 1.26).

Layout

pkg/types/readsb     # decode types for aircraft/receiver/stats/outline + aircraft filters
pkg/types/wingbits   # decode types for diagnostics/metrics/status (+ Prometheus text parser)
pkg/client           # HTTP Client: query + stream every endpoint, returns the types above
cmd/wingbits         # flag-driven CLI for one-off queries (test/utility tool)

Rules of the split:

• pkg/types/* is decode-only. No HTTP, no I/O beyond encoding/json and the Prometheus text parser. These packages must not import pkg/client.
• pkg/client owns all transport/request logic and depends on both type packages.
• Keep the two type packages independent of each other.

Station topology (important for endpoint routing)

A station exposes two HTTP roots; both are plaintext HTTP on the test unit:

Root	Default port	Serves
Wingbits	:8088	/network/diagnostics, /metrics, /tailscale/status, and readsb files under /readsb/
tar1090	:8504	readsb files under /data/, plus /data/outline.json

outline.json is only served by the tar1090 root. When a tar1090 endpoint is configured it overrides the Wingbits root for all readsb files.

Testing

go test ./...

Tests decode captured fixtures in each package's testdata/ directory and drive the client against an httptest server. pkg/client reuses the fixtures from pkg/types/*/testdata (a single source of truth — do not duplicate them).

The live reference unit is an MGW310 at 192.168.0.127 (also miner.mcguire.local), plaintext HTTP on all ports. Re-capture fixtures from it with curl when fields change; never hand-edit testdata/ payloads.

Coding standards

• Go only. Keep functions within ~25 lines; decompose helpers as needed.
• Every package has a package comment (Go convention) in one of its files.
• Comment only the non-obvious. Field docs on the decode structs are intentional — they capture readsb/Wingbits semantics that aren't evident from the name.
• The known JSON quirks to preserve when editing decode types:
  • alt_baro may be the string "ground" instead of a number → readsb.AltBaro.
  • readsb timestamps are fractional-second Unix floats → readsb.UnixTime.
  • outline.json points are [lat, lon, altFeet] tuples → readsb.RangePoint.

Changelog

CHANGELOG.md follows Keep a Changelog and SemVer. Record every user-facing change under ## [Unreleased] as part of the change itself — don't defer it to release time. When tagging a release, rename [Unreleased] to the new version with the date and add a fresh empty [Unreleased] section plus its compare link at the bottom.