From 388e7e0c6b708ab05fb08853449a535620e7ccef Mon Sep 17 00:00:00 2001
From: Manas Srivastava <mastermanas805@gmail.com>
Date: Tue, 12 May 2026 16:18:10 +0530
Subject: [PATCH] common: add buildinfo package for compile-time
 GitSHA/BuildTime/Version
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New `instant.dev/common/buildinfo` exposes three package vars
(`GitSHA`, `BuildTime`, `Version`) defaulting to sentinel strings.
Real values are wired in at link time via `go build -ldflags -X` —
the Dockerfile in each service passes `--build-arg GIT_SHA=...`
into the ldflag so /healthz and slog log lines stamp the exact
commit the running pod was built from.

This is track 1 of 8 in the observability rollout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 buildinfo/buildinfo.go      | 35 +++++++++++++++++++++++++++
 buildinfo/buildinfo_test.go | 48 +++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 buildinfo/buildinfo.go
 create mode 100644 buildinfo/buildinfo_test.go

diff --git a/buildinfo/buildinfo.go b/buildinfo/buildinfo.go
new file mode 100644
index 0000000..d8ffeba
--- /dev/null
+++ b/buildinfo/buildinfo.go
@@ -0,0 +1,35 @@
+// Package buildinfo exposes compile-time build metadata for every Go
+// binary in instanode.dev (api / worker / provisioner / cli).
+//
+// The three vars are wired in at link time via the Go linker's
+// `-X` flag:
+//
+//	go build -ldflags "-X instant.dev/common/buildinfo.GitSHA=abc1234 \
+//	                   -X instant.dev/common/buildinfo.BuildTime=2026-05-12T16:00:00Z \
+//	                   -X instant.dev/common/buildinfo.Version=v3.6.0" ./...
+//
+// Defaults are sentinel strings (`dev` / `unknown`) so an un-flagged
+// `go build` still produces a runnable binary — useful for local
+// `make run` and `go test ./...`. CI and the Dockerfiles always pass
+// real values via `--build-arg`.
+//
+// Consumers (slog handlers, /healthz, /api/v1/buildinfo, the worker's
+// startup log, NR custom attributes) read these vars directly. The
+// package has zero deps so it is safe to import from any other
+// package without creating cycles.
+package buildinfo
+
+// GitSHA is the short Git SHA of the commit the binary was built from.
+// Set at link time via -ldflags. Defaults to "dev" for un-flagged
+// local builds.
+var GitSHA = "dev"
+
+// BuildTime is the RFC-3339 UTC timestamp the binary was built at.
+// Set at link time via -ldflags. Defaults to "unknown" for un-flagged
+// local builds.
+var BuildTime = "unknown"
+
+// Version is the semver / release tag the binary was built from.
+// Set at link time via -ldflags. Defaults to "dev" for un-flagged
+// local builds.
+var Version = "dev"
diff --git a/buildinfo/buildinfo_test.go b/buildinfo/buildinfo_test.go
new file mode 100644
index 0000000..f6ee732
--- /dev/null
+++ b/buildinfo/buildinfo_test.go
@@ -0,0 +1,48 @@
+package buildinfo
+
+import "testing"
+
+// The three vars are package-level globals overwritten by `-ldflags -X`
+// at link time. These tests verify:
+//
+//  1. The names are reachable from importers (compile-time check).
+//  2. Default values match the documented sentinels — "dev" / "unknown".
+//     If a default changes accidentally, log enrichment and /healthz
+//     would silently report the new sentinel as truth, masking missing
+//     -ldflags in CI.
+//
+// The real -ldflags injection check is the `make smoke-buildinfo`
+// target — it builds a separate binary with -X overrides and verifies
+// the runtime value matches. That cannot be done from within the same
+// package's `go test` because the Go test binary itself is the linked
+// artifact under test (and we don't want to mutate package globals
+// from tests — flaky if any other test cares about them).
+
+func TestDefaults(t *testing.T) {
+	t.Run("GitSHA default", func(t *testing.T) {
+		if GitSHA != "dev" {
+			t.Errorf("GitSHA default = %q, want %q", GitSHA, "dev")
+		}
+	})
+	t.Run("BuildTime default", func(t *testing.T) {
+		if BuildTime != "unknown" {
+			t.Errorf("BuildTime default = %q, want %q", BuildTime, "unknown")
+		}
+	})
+	t.Run("Version default", func(t *testing.T) {
+		if Version != "dev" {
+			t.Errorf("Version default = %q, want %q", Version, "dev")
+		}
+	})
+}
+
+// TestReachable is a trivial compile-time check that the three exported
+// names are addressable from outside the package. If a refactor renames
+// or unexports any of them, ~306 slog log callsites and three /healthz
+// handlers stop compiling — but this catches it immediately at the
+// package boundary.
+func TestReachable(t *testing.T) {
+	_ = GitSHA
+	_ = BuildTime
+	_ = Version
+}