feat(version): warn when vendored charts drift from the talm binary

talm renders from the project's vendored charts/talm/, never the binary's
built-in charts, so upgrading the binary leaves the library frozen at the
version that last ran init — drift that was previously invisible. On every
config-loading command a release build now compares the two and, by
default, prints a non-fatal warning to stderr; stdout and the exit code
are unchanged. A project (strictCharts: true in Chart.yaml) or an operator
(--strict-charts) can promote the warning to a hard error raised before
the command body runs.

The build version is interpreted through releaseVersion, which accepts
both release forms — goreleaser injects it without a leading "v"
(0.30.0), the Makefile's `git describe --tags` keeps it (v0.30.0) — and
treats only "dev"/empty as a non-release. Gating on the "v" prefix alone
would disable the check on every downloaded release and stamp the dev
sentinel 0.1.0 into the vendored charts at init time; releaseVersion is
used in both places. The decision logic is factored into a pure
evaluateChartDrift for direct test coverage of the warn/strict/silent
branches. The --strict-charts usage string carries no backticks, so pflag
does not misrender the bool flag as taking a value.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>

Author: lexfrei

main.go

@@ -44,12 +44,28 @@ const (
 // command's Use field and via -X main.cmdNameTalm in build tooling.
 const cmdNameTalm = "talm"
 
-// Version is the talm release tag baked at build time via ldflags
-// (`-X main.Version=v0.27.0`); the literal value here is the local
-// development fallback.
+// Version is the talm build version baked in at link time via ldflags
+// (`-X main.Version=...`). The two release build paths inject different
+// forms: goreleaser strips the leading "v" (e.g. `0.27.0`, from
+// `{{.Version}}`) while the Makefile's `git describe --tags` keeps it
+// (e.g. `v0.27.0`). releaseVersion normalizes both. The literal "dev"
+// here is the local source-build fallback.
 //
 //nolint:gochecknoglobals // ldflags-injected build version, idiomatic for go release tooling.
-var Version = "dev"
+var Version = devVersion
+
+// devVersion is the build-version sentinel for a local source build (no
+// ldflags injection). releaseVersion treats it as "not a release", so
+// release-only behavior such as the chart-drift check stays off.
+const devVersion = "dev"
+
+// strictChartsFlag is bound to the --strict-charts persistent flag. When set
+// (or when Chart.yaml carries strictCharts: true), a content difference
+// between the project's vendored charts/talm/ and the binary's built-in copy
+// becomes a hard error instead of a warning.
+//
+//nolint:gochecknoglobals // cobra persistent flag binds to package-level state, consistent with the rest of this file.
+var strictChartsFlag bool
 
 // skipConfigCommands lists commands that should not load Chart.yaml config.
 // - init: creates the config, so it doesn't exist yet
@@ -121,6 +137,11 @@ func registerRootFlags(cmd *cobra.Command) {
 	cmd.PersistentFlags().StringVar(&commands.GlobalArgs.Cluster, "cluster", "", "Cluster to connect to if a proxy endpoint is used.")
 	cmd.PersistentFlags().BoolVar(&commands.GlobalArgs.SkipVerify, "skip-verify", false, "skip TLS certificate verification (keeps client authentication)")
 	cmd.PersistentFlags().Bool("version", false, "Print the version number of the application")
+	// No backticks in this usage string: pflag's UnquoteUsage treats the
+	// first backtick-quoted word as the flag's value-placeholder name, which
+	// on a bool flag misrenders --help as `--strict-charts talm init --update`
+	// (as if it took an argument).
+	cmd.PersistentFlags().BoolVar(&strictChartsFlag, "strict-charts", false, "fail if the project's vendored charts/talm/ differs from the talm binary's built-in copy (run talm init --update to re-sync)")
 
 	// Shell completion for root persistent flags. --nodes /
 	// --endpoints draw from the in-scope talosconfig contexts.
@@ -185,6 +206,10 @@ func init() {
 			if err != nil {
 				return errors.Wrap(err, "error loading configuration")
 			}
+
+			if err := surfaceChartDrift(); err != nil {
+				return err
+			}
 		}
 
 		// Ensure talosconfig path is set to project root if not explicitly set via flag
@@ -219,6 +244,72 @@ func init() {
 	}
 }
 
+// releaseVersion interprets the ldflags-injected build version. It returns
+// the version with any leading "v" stripped and true for a tagged release
+// build, or ("", false) for a dev/source build. Both release build paths
+// must be accepted: goreleaser injects "0.30.0" (no "v") and the Makefile's
+// `git describe --tags` injects "v0.30.0". Gating on the "v" prefix alone
+// would silently disable release-only behavior on the goreleaser artifacts
+// users actually download.
+func releaseVersion(raw string) (string, bool) {
+	if raw == "" || raw == devVersion {
+		return "", false
+	}
+
+	return strings.TrimPrefix(raw, "v"), true
+}
+
+// evaluateChartDrift decides the drift outcome for a build. It returns
+// (warning, error): a non-empty warning to print to stderr, or a non-nil
+// error to abort the command (strict mode), or both empty for the silent
+// cases. Taking the version, project root, and strict flag as arguments
+// keeps the warn-vs-fail decision pure (modulo the filesystem read inside
+// CheckChartDrift) so it is unit-testable without the package globals.
+//
+// Cases: dev/source build → silent (embedded charts are a moving target the
+// developer controls); drift-check I/O error → non-fatal warning (best
+// effort, never blocks the command); drift + strict → hard error with a
+// remediation hint; drift + non-strict → warning; no drift → silent.
+func evaluateChartDrift(rawVersion, rootDir string, strict bool) (string, error) {
+	version, ok := releaseVersion(rawVersion)
+	if !ok {
+		return "", nil
+	}
+
+	drift, msg, err := commands.CheckChartDrift(rootDir, version)
+
+	switch {
+	case err != nil:
+		return fmt.Sprintf("could not check chart drift: %v", err), nil
+	case drift && strict:
+		//nolint:wrapcheck // originating error built with errors.New; WithHint adds operator-facing guidance and is the project idiom.
+		return "", errors.WithHint(
+			errors.New(msg),
+			"run `talm init --update --preset <preset>`, or unset strictCharts / drop --strict-charts to downgrade this to a warning",
+		)
+	case drift:
+		return msg, nil
+	default:
+		return "", nil
+	}
+}
+
+// surfaceChartDrift wires evaluateChartDrift to the package globals and
+// emits the warning to stderr. The strict input is the OR of the committed
+// Chart.yaml field and the per-run flag.
+func surfaceChartDrift() error {
+	warning, err := evaluateChartDrift(Version, commands.Config.RootDir, commands.Config.StrictCharts || strictChartsFlag)
+	if err != nil {
+		return err
+	}
+
+	if warning != "" {
+		fmt.Fprintf(os.Stderr, "WARN: %s\n", warning)
+	}
+
+	return nil
+}
+
 func initConfig() {
 	if len(os.Args) < 2 {
 		return
@@ -236,8 +327,12 @@ func initConfig() {
 	}
 
 	if strings.HasPrefix(cmd.Use, initSubcommandName) {
-		if strings.HasPrefix(Version, "v") {
-			commands.Config.InitOptions.Version = strings.TrimPrefix(Version, `v`)
+		// Stamp the real release version into the vendored charts; fall back
+		// to the dev sentinel for source builds. Gating on the "v" prefix
+		// here would stamp "0.1.0" on every goreleaser release (which injects
+		// the version without "v").
+		if version, ok := releaseVersion(Version); ok {
+			commands.Config.InitOptions.Version = version
 		} else {
 			commands.Config.InitOptions.Version = "0.1.0"
 		}

main_test.go

@@ -8,7 +8,9 @@ import (
 
 	"github.com/cockroachdb/errors"
 	"github.com/cozystack/talm/pkg/commands"
+	"github.com/cozystack/talm/pkg/generated"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
 // buildCommandHierarchy creates a cobra command hierarchy from a path like
@@ -217,6 +219,144 @@ func TestRegisterRootFlags_NodesHasNoShorthand(t *testing.T) {
 	}
 }
 
+// TestRegisterRootFlags_StrictChartsRendersWithoutValuePlaceholder pins that
+// --strict-charts renders in --help as a plain bool flag, not as one taking
+// an argument. pflag's UnquoteUsage treats the first backtick-quoted word in
+// a flag's usage string as the flag's value-placeholder name; a backtick in
+// the --strict-charts usage made --help show `--strict-charts talm init
+// --update`, as if the bool flag took a string argument.
+func TestRegisterRootFlags_StrictChartsRendersWithoutValuePlaceholder(t *testing.T) {
+	snapshotConfigState(t)
+
+	cmd := &cobra.Command{Use: "talm-test"}
+	registerRootFlags(cmd)
+
+	flag := cmd.PersistentFlags().Lookup("strict-charts")
+	if flag == nil {
+		t.Fatal("expected --strict-charts to be registered, got nil")
+	}
+
+	name, _ := pflag.UnquoteUsage(flag)
+	if name != "" {
+		t.Errorf("--strict-charts (a bool flag) renders with value placeholder %q; remove backticks from its usage string", name)
+	}
+}
+
+// writeDriftedTalmProject creates a project whose vendored charts/talm/
+// cannot match the binary's embedded library (the helpers template carries
+// a local edit), so CheckChartDrift reports drift.
+func writeDriftedTalmProject(t *testing.T) string {
+	t.Helper()
+
+	root := t.TempDir()
+	dir := filepath.Join(root, "charts", "talm", "templates")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "charts", "talm", "Chart.yaml"),
+		[]byte("apiVersion: v2\nname: talm\nversion: 0.30.0\ntype: library\n"), 0o644); err != nil {
+		t.Fatalf("write Chart.yaml: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "_helpers.tpl"),
+		[]byte("{{- /* drifted local edit, not the embedded copy */ -}}\n"), 0o644); err != nil {
+		t.Fatalf("write helpers: %v", err)
+	}
+
+	return root
+}
+
+// writeMatchingTalmProject materializes a vendored charts/talm/ that is
+// byte-identical to the embedded library (stamping version into Chart.yaml),
+// so CheckChartDrift reports no drift.
+func writeMatchingTalmProject(t *testing.T, version string) string {
+	t.Helper()
+
+	files, err := generated.TalmLibraryFiles()
+	if err != nil {
+		t.Fatalf("TalmLibraryFiles: %v", err)
+	}
+
+	root := t.TempDir()
+	for rel, content := range files {
+		if filepath.Base(rel) == "Chart.yaml" {
+			content = strings.ReplaceAll(content, "name: %s", "name: talm")
+			content = strings.ReplaceAll(content, "version: %s", "version: "+version)
+		}
+
+		dest := filepath.Join(root, "charts", "talm", filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+			t.Fatalf("mkdir: %v", err)
+		}
+		if err := os.WriteFile(dest, []byte(content), 0o644); err != nil {
+			t.Fatalf("write: %v", err)
+		}
+	}
+
+	return root
+}
+
+func hintsContain(err error, substr string) bool {
+	for _, hint := range errors.GetAllHints(err) {
+		if strings.Contains(hint, substr) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// TestEvaluateChartDrift pins the warn-vs-fail decision that drives the
+// user-facing behavior: strict mode aborts with a remediation hint,
+// non-strict drift warns without blocking, a dev build is silent even with
+// drift present, and a content-identical library never trips on a
+// version-only difference.
+func TestEvaluateChartDrift(t *testing.T) {
+	t.Run("strict drift returns a hard error hinting at init --update", func(t *testing.T) {
+		root := writeDriftedTalmProject(t)
+
+		warning, err := evaluateChartDrift("0.30.0", root, true)
+		if err == nil {
+			t.Fatal("expected a strict-mode error for a drifted project")
+		}
+		if warning != "" {
+			t.Errorf("strict error path must not also emit a warning, got %q", warning)
+		}
+		if !hintsContain(err, "talm init --update --preset") {
+			t.Errorf("strict-mode error must hint at `talm init --update --preset`, hints: %v", errors.GetAllHints(err))
+		}
+	})
+
+	t.Run("non-strict drift warns without blocking", func(t *testing.T) {
+		root := writeDriftedTalmProject(t)
+
+		warning, err := evaluateChartDrift("0.30.0", root, false)
+		if err != nil {
+			t.Fatalf("non-strict drift must not block the command: %v", err)
+		}
+		if !strings.Contains(warning, "charts/talm") {
+			t.Errorf("expected a drift warning mentioning charts/talm, got %q", warning)
+		}
+	})
+
+	t.Run("dev build is silent even with drift present and strict set", func(t *testing.T) {
+		root := writeDriftedTalmProject(t)
+
+		warning, err := evaluateChartDrift("dev", root, true)
+		if err != nil || warning != "" {
+			t.Errorf("dev build must be a no-op, got warning=%q err=%v", warning, err)
+		}
+	})
+
+	t.Run("matching library is silent under strict mode despite a newer binary version", func(t *testing.T) {
+		root := writeMatchingTalmProject(t, "0.30.0")
+
+		warning, err := evaluateChartDrift("0.31.0", root, true)
+		if err != nil || warning != "" {
+			t.Errorf("a content-identical library must not drift on a version-only difference, got warning=%q err=%v", warning, err)
+		}
+	})
+}
+
 func TestSkipConfigCommands(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -283,3 +423,37 @@ func TestSkipConfigCommands(t *testing.T) {
 		})
 	}
 }
+
+// TestReleaseVersion pins that both release build paths are recognized.
+// goreleaser injects the version WITHOUT the "v" prefix (`-X
+// main.Version={{.Version}}` → "0.30.0") while the Makefile's `git describe
+// --tags` keeps it ("v0.30.0"). A previous gate accepted only the
+// "v"-prefixed form, which silently disabled the chart-drift check and the
+// init version stamp on every downloaded release. Both forms must parse to
+// the same version and report isRelease=true; dev/empty builds must not.
+func TestReleaseVersion(t *testing.T) {
+	tests := []struct {
+		name        string
+		raw         string
+		wantVersion string
+		wantRelease bool
+	}{
+		{"goreleaser form (no v)", "0.30.0", "0.30.0", true},
+		{"makefile form (with v)", "v0.30.0", "0.30.0", true},
+		{"dev source build", "dev", "", false},
+		{"empty version", "", "", false},
+		{"prerelease no v", "0.30.0-rc.1", "0.30.0-rc.1", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			version, isRelease := releaseVersion(tt.raw)
+			if isRelease != tt.wantRelease {
+				t.Errorf("releaseVersion(%q) isRelease = %v, want %v", tt.raw, isRelease, tt.wantRelease)
+			}
+			if version != tt.wantVersion {
+				t.Errorf("releaseVersion(%q) version = %q, want %q", tt.raw, version, tt.wantVersion)
+			}
+		})
+	}
+}