Merge branch 'feat/embed-assets'

Author: dombyte

.goreleaser.yaml

@@ -5,10 +5,10 @@ before:
   hooks:
     # CI already enforces a tidy go.mod; verify only, never rewrite the tree mid-release.
     - go mod verify
-    # Frontend and API docs are built once here and shipped in both the archives and
-    # the images (the binary serves ./frontend/dist and ./docs/dist from disk).
-    - make frontend VITE_GIT_COMMIT_HASH={{ .Version }}-{{ .ShortCommit }}
-    - make docs
+    # Frontend and API docs are built once here, with the release version the binaries
+    # get, before the Go builds embed them (go:embed); archives and images ship only the
+    # binary.
+    - make assets VERSION={{ .Version }}
 
 builds:
   - id: solis-multi-arch
@@ -51,8 +51,6 @@ archives:
       - LICENSE
       - README.md
       - example/config.yaml
-      - frontend/dist
-      - docs/dist
 
 changelog:
   sort: asc
@@ -137,9 +135,6 @@ dockers_v2:
       - linux/arm64
       - linux/arm/v7
     dockerfile: Dockerfile.goreleaser
-    extra_files:
-      - frontend/dist
-      - docs/dist
     labels: &oci
       org.opencontainers.image.title: Solis Monitor
       org.opencontainers.image.description: >-

AGENTS.md

@@ -26,9 +26,9 @@ serves a React dashboard (REST + WebSocket) from the same Go binary.
 
 - **Input:** one inverter over Modbus TCP or RTU; the poller is the only Modbus user.
 - **Outputs:** SQLite (daily/monthly/yearly/total values, status history), REST API,
-  WebSocket live values, the SPA and Swagger UI served from disk (`frontend/dist`,
-  `docs/dist`).
-- **Runtime:** a single binary; without a subcommand it runs the server, `solis backfill`
+  WebSocket live values, the SPA and Swagger UI embedded in the binary (`go:embed` of
+  the prebuilt `frontend/dist`, `docs/dist`).
+- **Runtime:** a single self-contained binary; without a subcommand it runs the server, `solis backfill`
   runs a maintenance job. Shipped as binaries (linux, darwin) and a multi-arch `scratch`
   image on ghcr.io.
 
@@ -45,8 +45,9 @@ go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 ./...       # known vulnerabilit
 go tool mockery                                             # regenerate mocks (.mockery.yaml; version pinned in go.mod)
 go test -race ./...                         # all tests, as in CI
 go test ./internal/solis -run TestBlockPlanGolden
-make build                                  # ./solis with version info (ldflags)
 make assets                                 # frontend/dist + docs/dist (make frontend / docs)
+make build                                  # ./solis with version info (ldflags), embeds the dists
+make all                                    # assets, then build
 make docker                                 # dev image (docker-compose.dev.yaml) with version info
 go run ./cmd                                # server (reads ./config.yaml; -config <path>)
 go run ./cmd backfill --years 0             # maintenance job (app must be stopped), exits 0/1
@@ -63,9 +64,11 @@ cd frontend && npm run typecheck && npm run lint && npm run knip
 ## 3. Project Structure
 
 ```
-cmd/                     main.go (subcommand dispatch, signal ctx, exit code), serve.go, backfill.go
+cmd/                     main.go (subcommand dispatch, signal ctx, exit code, ldflags build info),
+                         serve.go, backfill.go
 internal/
   app/                   composition root: Create* factories, health adapters, logger wiring
+  buildinfo/             build information (version, commit, …) passed down from cmd
   config/                YAML/env config, structural Validate(); domain rules injected by app
   period/                Period (day/month/year keys from one captured instant), rollover window
   eventbus/              event bus (ValuesUpdated, PeriodClosed), non-blocking, per-subscriber policy
@@ -88,8 +91,8 @@ internal/
   util/                  math, data types, Clock, Slot[T], DependencyError/RequireAll;
                          util/clocktest is the fake Clock for tests
   <pkg>/mocks/           mockery-generated mocks (never hand-edit)
-frontend/                React 19 + Vite + Tailwind 4 + zustand SPA
-docs/                    Swagger UI + openapi.yaml
+frontend/                React 19 + Vite + Tailwind 4 + zustand SPA; embed.go embeds dist/
+docs/                    Swagger UI + openapi.yaml; embed.go embeds dist/
 example/                 docker-compose (TCP, RTU) and config.yaml templates for users
 ```
 
@@ -149,8 +152,9 @@ modbus      → stdlib + simonvetter + util (Clock) + an injected zerolog.Logger
               (external layer: no config/health)
 service     → storage (ReadStore only), health, history, period, solis + own interfaces
               (CacheReader, HealthSnapshotter)
-httphandler → service, health, period, solis, util
-app         → everything (composition root)
+httphandler → service, health, period, solis, buildinfo, util
+buildinfo   → stdlib only
+app         → everything (composition root), incl. the frontend and docs embed packages
 ```
 
 - "storage (store types)" means the interfaces, DTOs (`PollWrite`, `DailyRow`, …) and
@@ -246,14 +250,31 @@ LastBeat() time.Time              // atomic timestamp, updated by the component'
   parse, call `Service.Data`/`Keys`/`Health`, map errors, write JSON.
 - Middleware (`Recover(log)`, `Logger(log)`, `SecurityHeaders`) is
   `func(http.Handler) http.Handler` with an injected logger where it logs.
-- Routes (`router.SetupRoutes(Deps)`): `/health`, `/api/keys`, `/api/data/{key}`, `/ws`,
-  `/docs/`, and the SPA. No CORS middleware.
+- Routes (`router.SetupRoutes(Deps)`): `/health`, `/api/keys`, `/api/data/{key}`,
+  `/api/version`, `/ws`, `/docs/`, and the SPA. No CORS middleware.
+- Static files come from `fs.FS` values in `router.Deps` (`Frontend`, `Docs`); `app` passes
+  the embedded `frontend.Dist()` / `docs.Dist()`, tests pass an `fstest.MapFS`. A tree
+  without `index.html` is not mounted (binary built before `make assets`; `app` warns).
 - One error shape, documented in `docs/src/openapi.yaml`, written with
   `WriteError(w, status, msg)`: `{ "error": "Bad Request", "message": "…", "code": 400 }`.
 - `service.NewReadService(service.Deps{Store, Cache, Health, Registry, Decoder, Log})`:
   every dependency is required; the service never receives a Modbus client, poller or
   aggregator.
 
+### Version (one version for binary, UI and docs)
+
+- The binary's build information (ldflags → `buildinfo.Info`, `HandlerDeps.Build`) is
+  served by `GET /api/version`. The frontend and the Swagger UI are built with the same
+  version (`VITE_APP_VERSION=$(VERSION)` in `make frontend`/`make docs`; goreleaser and
+  the Dockerfile pass the release/build version), so binary, UI and docs show one version.
+  No `version.json`.
+- The frontend polls `/api/version` and compares it with its compiled version: a
+  different one means the server was upgraded (update banner → reload). `dev` on either
+  side never reports an update.
+- `go:embed all:dist*` also matches the committed `dist.md`, so Go builds, tests and lint
+  work without npm; release builds always run `make assets` first (goreleaser before
+  hooks, Dockerfile node stages).
+
 ### Health endpoint (fail-closed)
 
 - `GET /health` reads the supervisor snapshot only; it never blocks on a component.
@@ -462,6 +483,8 @@ Deliberate choices, with the reason, for behaviour that is not obvious from the
   through a `util.Slot` so the poller always reads the current client after a restart.
 - **Derived values:** `battery_power_signed` is produced by `Decoder.Derive` after a full
   poll (it needs two registers).
+- **Embedded web assets:** the archives and the image ship only the binary; the dist
+  folders are build inputs, not runtime files.
 - **Read plan:** 3 Modbus reads (grid power at 33130 so it falls inside an existing block),
   pinned by the block-plan golden test.
 - **Shutdown:** single-phase with a hard deadline; no second-signal force mode.

Dockerfile

@@ -1,20 +1,19 @@
 FROM node:26-alpine AS frontend
 WORKDIR /frontend
-# Accept git commit hash as build argument with default value
-ARG VITE_GIT_COMMIT_HASH
 COPY frontend/package.json frontend/package-lock.json ./
 RUN npm ci
 COPY frontend/ .
-RUN npm run build
+# Same version as the binary (make docker passes it); the UI compares it with /api/version.
+ARG VERSION=dev
+RUN VITE_APP_VERSION=${VERSION} npm run build
 
 FROM node:26-alpine AS docs
 WORKDIR /docs
 COPY docs/package.json docs/package-lock.json ./
 RUN npm ci
 COPY docs/ .
-RUN npm run build
-
-
+ARG VERSION=dev
+RUN VITE_APP_VERSION=${VERSION} npm run build
 
 FROM golang:1.27.1-alpine AS builder
 WORKDIR /app
@@ -29,6 +28,9 @@ ARG COMMIT=unknown
 ARG BUILD_DATE=unknown
 
 COPY . .
+# The web assets are embedded into the binary (go:embed), so they must exist before go build.
+COPY --from=frontend /frontend/dist ./frontend/dist
+COPY --from=docs /docs/dist ./docs/dist
 RUN CGO_ENABLED=0 go build \
     -ldflags="-w -s -X main.Version=${VERSION} -X main.Commit=${COMMIT} -X main.BuildDate=${BUILD_DATE} -X main.GoVersion=$(go env GOVERSION)" \
     -a \
@@ -42,7 +44,5 @@ COPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/httpcheck
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
 COPY --from=builder /app/solis /app
-COPY --from=frontend /frontend/dist /app/frontend/dist
-COPY --from=docs /docs/dist /app/docs/dist
 EXPOSE 8080
 ENTRYPOINT ["/app/solis"]

Dockerfile.goreleaser

@@ -1,4 +1,4 @@
-# Built by goreleaser: the binary, frontend/dist and docs/dist are prebuilt
+# Built by goreleaser: the binary is prebuilt with frontend/dist and docs/dist embedded
 # (see before.hooks in .goreleaser.yaml) and copied into the build context.
 # ca-certificates and zoneinfo are arch-independent: this stage runs natively on the
 # build host, so no step here needs QEMU (release.yml still sets it up, as goreleaser requires).
@@ -12,8 +12,6 @@ COPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/httpcheck
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
 COPY $TARGETPLATFORM/solis /app
-COPY frontend/dist /app/frontend/dist
-COPY docs/dist /app/docs/dist
 
 EXPOSE 8080
 ENTRYPOINT ["/app/solis"]

Makefile

@@ -6,27 +6,28 @@ COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 DATE := $(shell date -u +'%Y-%m-%dT%H:%M:%SZ')
 GOVERSION := $(shell go version | awk '{print $$3}')
 
-# Version shown in the web UI (frontend/public/data/version.json); goreleaser overrides it.
-VITE_GIT_COMMIT_HASH ?= $(VERSION)
-
 # Build flags for small binary
 LDFLAGS := -s -w
 BUILD_FLAGS := -ldflags "-X main.Version=$(VERSION) -X main.Commit=$(COMMIT) -X main.BuildDate=$(DATE) -X main.GoVersion=$(GOVERSION) $(LDFLAGS)"
 
+# The web assets are built with the same version (VITE_APP_VERSION) as the binary; the
+# frontend compares it with GET /api/version. goreleaser passes VERSION=<release version>.
+
+# Embeds whatever frontend/dist and docs/dist hold: run `make assets` first (or `make all`).
 .PHONY: build
 build:
 	CGO_ENABLED=0 go build $(BUILD_FLAGS) -o $(BINARY_NAME) ./cmd
 
-# Web assets the binary serves from disk (./frontend/dist, ./docs/dist).
+# Web assets embedded into the binary (frontend/dist, docs/dist); build them before `build`.
 .PHONY: frontend
 frontend:
 	npm --prefix frontend ci
-	VITE_GIT_COMMIT_HASH=$(VITE_GIT_COMMIT_HASH) npm --prefix frontend run build
+	VITE_APP_VERSION=$(VERSION) npm --prefix frontend run build
 
 .PHONY: docs
 docs:
 	npm --prefix docs ci
-	npm --prefix docs run build
+	VITE_APP_VERSION=$(VERSION) npm --prefix docs run build
 
 .PHONY: assets
 assets: frontend docs
@@ -35,7 +36,6 @@ assets: frontend docs
 .PHONY: docker
 docker:
 	VERSION=$(VERSION) COMMIT=$(COMMIT) BUILD_DATE=$(DATE) \
-		VITE_GIT_COMMIT_HASH=$(VITE_GIT_COMMIT_HASH) \
 		docker compose -f docker-compose.dev.yaml build
 
 .PHONY: clean

README.md

@@ -110,6 +110,7 @@ Addresses, types and scales are defined in `internal/solis/table.go`.
 ```
 GET /health                                            # 200 ok|degraded, 503 failed
 GET /api/keys                                          # all registers + metadata
+GET /api/version                                       # build info (binary, UI and docs)
 GET /api/data/{key}                                    # current value
 GET /api/data/{daily_key}?start=2024-01-01&end=2024-01-31
 GET /api/data/{monthly_key}?start=2024-01&end=2024-12
@@ -164,7 +165,8 @@ refuses periods whose daily rows retention already deleted.
 ## Development
 
 ```bash
-make build           # binary with version info
+make all             # web assets + binary (the UI and API docs are embedded)
+make build           # binary with version info; embeds the assets of the last `make assets`
 make check           # format, lint, race tests, deadcode, govulncheck (check-only)
 make docker          # dev image with version info (docker-compose.dev.yaml)
 docker compose -f docker-compose.dev.yaml up

cmd/main.go

@@ -18,6 +18,7 @@ import (
 	_ "time/tzdata" // fallback zoneinfo so TZ=Europe/Berlin never silently becomes UTC
 
 	"github.com/dombyte/solis/internal/app"
+	"github.com/dombyte/solis/internal/buildinfo"
 	"github.com/dombyte/solis/internal/config"
 	"github.com/dombyte/solis/internal/logging"
 )
@@ -35,10 +36,11 @@ var (
 	GoVersion = "unknown"
 )
 
-// buildInfo renders the build information for the startup log and `solis version`.
-func buildInfo() string {
-	return fmt.Sprintf("solis %s (commit %s, built %s, %s)", Version, Commit, BuildDate,
-		GoVersion)
+// buildInfo collects the linker-set build information.
+func buildInfo() buildinfo.Info {
+	return buildinfo.Info{
+		Version: Version, Commit: Commit, BuildDate: BuildDate, GoVersion: GoVersion,
+	}
 }
 
 func main() {
@@ -78,7 +80,7 @@ func runCommand(args []string, configPath string, stdout, stderr io.Writer) int
 		printUsage(stdout)
 		return 0
 	case "version":
-		_, _ = fmt.Fprintln(stdout, buildInfo())
+		_, _ = fmt.Fprintln(stdout, buildInfo().String())
 		return 0
 	default:
 		// #nosec G705 -- writes to the process's own stderr, not an HTTP response

cmd/main_test.go

@@ -36,11 +36,11 @@ func TestDispatch_HelpAndUnknown(t *testing.T) {
 	assert.Contains(t, out.String(), "solis [-config PATH] backfill --years N")
 	out.Reset()
 	assert.Equal(t, 0, dispatch([]string{"version"}, &out, &errOut))
-	assert.Equal(t, buildInfo()+"\n", out.String())
+	assert.Equal(t, buildInfo().String()+"\n", out.String())
 	assert.Contains(t, out.String(), "solis dev (commit unknown")
 	out.Reset()
 	assert.Equal(t, 0, dispatch([]string{"--version"}, &out, &errOut))
-	assert.Equal(t, buildInfo()+"\n", out.String())
+	assert.Equal(t, buildInfo().String()+"\n", out.String())
 	assert.Equal(t, 0, dispatch([]string{"-h"}, &out, &errOut), "help is not an error")
 	assert.Contains(t, errOut.String(), "-config PATH")
 	assert.Equal(t, 1, dispatch([]string{"-nope"}, &out, &errOut))

cmd/serve.go

@@ -18,5 +18,5 @@ func runServer(ctx context.Context, configPath string) error {
 	for _, w := range cfg.Warnings {
 		root.Warn().Str("component", "config").Msg(w)
 	}
-	return app.Run(ctx, cfg, root)
+	return app.Run(ctx, cfg, buildInfo(), root)
 }

docker-compose.dev.yaml

@@ -5,7 +5,6 @@ services:
       context: .
       dockerfile: Dockerfile
       args: # set by `make docker`; plain `docker compose build` falls back to dev/unknown
-        VITE_GIT_COMMIT_HASH: ${VITE_GIT_COMMIT_HASH:-dev}
         VERSION: ${VERSION:-dev}
         COMMIT: ${COMMIT:-unknown}
         BUILD_DATE: ${BUILD_DATE:-unknown}