CFG_VER/APP_VER in the env file: invalid configs replaced, updates follow APP_VER (dev/stable/pin)

internal/config/sample.go

@@ -15,12 +15,12 @@ type sampleEntry struct {
 	active  bool // rendered uncommented
 }
 
-// versionMarker prefixes the first line of an installer-written env file so
-// later installs can tell which version wrote it.
-const versionMarker = "# gpu-turnstile version: "
+// appVerComment documents APP_VER wherever it is rendered.
+const appVerComment = `Version to run: "dev" disables updates, "stable" tracks the latest release, or pin an exact release like v0.1.7`
 
 // sampleEntries lists every setting in sample order. logFile activates the
 // LOG_FILE line (Windows install); empty keeps it commented like the rest.
+// CFG_VER and APP_VER are not entries — they head the file, always active.
 func sampleEntries(logFile string) []sampleEntry {
 	return []sampleEntry{
 		{"LISTEN_OLLAMA", ":11434", "Ollama-facing listener address", false},
@@ -55,15 +55,19 @@ func sampleEntries(logFile string) []sampleEntry {
 
 // SampleEnv renders a sample .env file covering every setting, each with a
 // comment line. Everything is commented out — so all defaults apply —
-// except LOG_FILE when logFile is non-empty: a Windows service has no
-// console, so the installer pre-wires file logging there. The first line
-// carries the writing version so later installs can upgrade the file.
+// except the CFG_VER/APP_VER header and LOG_FILE when logFile is non-empty
+// (a Windows service has no console). CFG_VER records the version that
+// wrote the file so later installs can upgrade it.
 func SampleEnv(version, logFile string) string {
 	var b strings.Builder
-	b.WriteString(versionMarker + version + "\n")
+	fmt.Fprintf(&b, "CFG_VER=%s\n", version)
+	b.WriteString("# Config format reference, written by the installer — do not edit.\n")
+	b.WriteString("# The installer uses it to append newly added settings on updates.\n\n")
+	b.WriteString("# gpu-turnstile configuration\n")
 	b.WriteString("# KEY=VALUE lines; \"#\" starts a comment. Every setting below is at its\n")
 	b.WriteString("# default and commented out — remove the \"#\" to change it.\n")
 	b.WriteString("# At least one of OLLAMA_URL / COMFY_URL must be set for the proxy to start.\n\n")
+	writeEntry(&b, sampleEntry{"APP_VER", "stable", appVerComment, true})
 	for _, e := range sampleEntries(logFile) {
 		writeEntry(&b, e)
 	}
@@ -79,22 +83,21 @@ func writeEntry(b *strings.Builder, e sampleEntry) {
 	}
 }
 
-// SyncSample upgrades an installer-written env file: when its version
-// marker says it was written by an older gpu-turnstile, every setting the
-// file does not mention — commented or not — is appended at the end, and
-// the marker is updated to version. Files without the marker (hand-written
-// configs) and up-to-date files are returned unchanged; changed reports
-// whether the returned content differs. A "dev" version never upgrades.
+// SyncSample upgrades an installer-written env file: when its CFG_VER says
+// it was written by an older gpu-turnstile, every setting the file does not
+// mention — commented or not — is appended at the end, and CFG_VER is
+// updated to version. Files without CFG_VER (hand-written or foreign),
+// up-to-date files and "dev" builds are returned unchanged; changed reports
+// whether the returned content differs.
 func SyncSample(data, version, logFile string) (string, bool) {
 	if version == "" || version == "dev" {
 		return data, false
 	}
-	first, _, _ := strings.Cut(data, "\n")
-	marker, ok := strings.CutPrefix(first, versionMarker)
-	if !ok {
-		return data, false // not written by the installer
+	values, err := ParseEnvFile(strings.NewReader(data))
+	if err != nil || values["CFG_VER"] == "" {
+		return data, false // not installer-written; the caller decides
 	}
-	if compareVersions(strings.TrimSpace(marker), version) >= 0 {
+	if compareVersions(values["CFG_VER"], version) >= 0 {
 		return data, false // same or newer
 	}
 
@@ -106,18 +109,30 @@ func SyncSample(data, version, logFile string) (string, bool) {
 		}
 	}
 
+	lines := strings.Split(data, "\n")
+	for i, l := range lines {
+		if strings.HasPrefix(strings.TrimSpace(l), "CFG_VER=") {
+			lines[i] = "CFG_VER=" + version
+			break
+		}
+	}
+	out := strings.Join(lines, "\n")
+	if !strings.HasSuffix(out, "\n") {
+		out += "\n"
+	}
+
 	var b strings.Builder
-	b.WriteString(versionMarker + version + "\n")
-	rest := strings.TrimPrefix(data, first)
-	b.WriteString(strings.TrimRight(rest, "\n"))
-	b.WriteString("\n")
+	if !present["APP_VER"] {
+		fmt.Fprintf(&b, "\n# Added by gpu-turnstile %s:\n", version)
+		writeEntry(&b, sampleEntry{"APP_VER", "stable", appVerComment, true})
+	}
 	for _, e := range sampleEntries(logFile) {
 		if !present[e.name] {
 			fmt.Fprintf(&b, "\n# Added by gpu-turnstile %s:\n", version)
 			writeEntry(&b, e)
 		}
 	}
-	out := b.String()
+	out += b.String()
 	return out, out != data
 }