feat: 迁移 versionctl 为独立模块并新增 make version-bump 命令

- 将 backend/cmd/versionctl 和 backend/pkg/projectversion 迁移至独立 versionctl/ Go 模块 - 新增 bump 子命令支持 major/minor/patch 和指定版本号，含版本倒退防护 - 新增 make version-bump 编排完整升迁流程（bump + sync + check + commit + tag） - 更新所有引用路径：根 Makefile、backend/Makefile、release.yml、.golangci.yml - 新增 versionctl/.golangci.yml（精简配置）和 Makefile（lint/test/coverage） - 根 Makefile lint/test 集成 versionctl 模块 - 同步 openspec specs：新增 version-bump spec，更新 release-pipeline spec
2026-05-05 04:18:10 +08:00
parent 3cd0458c2c
commit bc7a7c6e81
16 changed files with 515 additions and 47 deletions
--- a/versionctl/.golangci.yml
+++ b/versionctl/.golangci.yml
@@ -0,0 +1,52 @@
+run:
+  timeout: 5m
+  tests: true
+
+linters:
+  disable-all: true
+  enable:
+    - errorlint
+    - errcheck
+    - staticcheck
+    - revive
+    - gocritic
+    - gosec
+    - nilerr
+    - goimports
+    - gocyclo
+
+linters-settings:
+  errcheck:
+    check-blank: true
+    check-type-assertions: true
+  revive:
+    rules:
+      - name: exported
+      - name: var-naming
+      - name: indent-error-flow
+      - name: error-strings
+      - name: error-return
+      - name: blank-imports
+  goimports:
+    local-prefixes: nex/versionctl
+  gocyclo:
+    min-complexity: 10
+
+issues:
+  exclude-generated: true
+  exclude-rules:
+    - path: '_test\.go'
+      linters:
+        - errcheck
+      source: '(^\s*_\s*=|,\s*_)'
+    - path: '_test\.go'
+      linters:
+        - revive
+      text: '^exported:'
+    - path: '_test\.go'
+      linters:
+        - gosec
+      text: 'G(101|401|501)'
+    - path: 'main\.go'
+      linters:
+        - gocyclo
--- a/versionctl/Makefile
+++ b/versionctl/Makefile
@@ -0,0 +1,16 @@
+.PHONY: \
+	lint test test-coverage clean
+
+lint:
+	go tool golangci-lint run ./...
+
+test:
+	go test ./... -v
+
+test-coverage:
+	go test ./... -coverprofile=coverage.out
+	go tool cover -html=coverage.out -o coverage.html
+	@printf 'Coverage report generated: versionctl/coverage.html\n'
+
+clean:
+	rm -rf coverage.out coverage.html
--- a/versionctl/go.mod
+++ b/versionctl/go.mod
@@ -0,0 +1,14 @@
+module nex/versionctl
+
+go 1.26.2
+
+require github.com/stretchr/testify v1.11.1
+
+require (
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
--- a/versionctl/go.sum
+++ b/versionctl/go.sum
@@ -0,0 +1,8 @@
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
--- a/versionctl/main.go
+++ b/versionctl/main.go
@@ -0,0 +1,151 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"nex/versionctl/projectversion"
+)
+
+func main() {
+	if err := run(os.Args[1:]); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(args []string) error {
+	if len(args) == 0 {
+		return usageError()
+	}
+
+	root, err := projectversion.FindRepoRoot(mustGetwd())
+	if err != nil {
+		return err
+	}
+
+	switch args[0] {
+	case "print":
+		version, readErr := projectversion.ReadString(root)
+		if readErr != nil {
+			return readErr
+		}
+		fmt.Println(version)
+		return nil
+	case "sync":
+		return projectversion.Sync(root)
+	case "check":
+		return projectversion.Check(root)
+	case "verify-tag":
+		if len(args) != 2 {
+			return fmt.Errorf("verify-tag 需要一个 tag 参数")
+		}
+		return projectversion.VerifyTag(root, args[1])
+	case "bump":
+		if len(args) != 2 {
+			return fmt.Errorf("bump 需要一个参数: major|minor|patch 或具体版本号")
+		}
+		return runBump(root, args[1])
+	case "macos-plist":
+		if len(args) != 2 {
+			return fmt.Errorf("macos-plist 需要一个最低系统版本参数")
+		}
+		return printMacOSPlist(root, args[1])
+	case "asset-name":
+		return printAssetName(root, args[1:])
+	default:
+		return usageError()
+	}
+}
+
+func runBump(root, arg string) error {
+	newVersion, err := projectversion.Bump(root, arg)
+	if err != nil {
+		return err
+	}
+
+	tags, err := projectversion.ListGitTags(root)
+	if err != nil {
+		return err
+	}
+
+	if err := projectversion.CheckNoRegression(newVersion, tags); err != nil {
+		return err
+	}
+
+	if err := projectversion.Sync(root); err != nil {
+		return err
+	}
+
+	if err := projectversion.Check(root); err != nil {
+		return err
+	}
+
+	fmt.Println(newVersion.String())
+	return nil
+}
+
+func printMacOSPlist(root, minMacOSVersion string) error {
+	version, err := projectversion.ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	plist, err := projectversion.DesktopInfoPlist(version, minMacOSVersion)
+	if err != nil {
+		return err
+	}
+
+	fmt.Print(plist)
+	return nil
+}
+
+func printAssetName(root string, args []string) error {
+	if len(args) < 2 {
+		return fmt.Errorf("asset-name 至少需要 kind 和 platform 参数")
+	}
+
+	version, err := projectversion.ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	switch args[0] {
+	case "server":
+		if len(args) != 3 {
+			return fmt.Errorf("server 资产命名需要 platform 和 arch 参数")
+		}
+		name, nameErr := projectversion.ServerAssetName(version, args[1], args[2])
+		if nameErr != nil {
+			return nameErr
+		}
+		fmt.Println(name)
+		return nil
+	case "desktop":
+		if len(args) != 2 {
+			return fmt.Errorf("desktop 资产命名只需要 platform 参数")
+		}
+		name, nameErr := projectversion.DesktopAssetName(version, args[1])
+		if nameErr != nil {
+			return nameErr
+		}
+		fmt.Println(name)
+		return nil
+	default:
+		return fmt.Errorf("不支持的资产类型 %q", args[0])
+	}
+}
+
+func mustGetwd() string {
+	wd, err := os.Getwd()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	return wd
+}
+
+func usageError() error {
+	return fmt.Errorf("用法: version <print|sync|check|verify-tag|bump|macos-plist|asset-name>")
+}
--- a/versionctl/projectversion/version.go
+++ b/versionctl/projectversion/version.go
@@ -0,0 +1,443 @@
+package projectversion
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+const versionFileName = "VERSION"
+
+var (
+	semverRegex          = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`)
+	packageVersionRegex  = regexp.MustCompile(`(?m)^(\s*"version"\s*:\s*")([^"]+)(",?)$`)
+	frontendVersionFiles = []string{
+		"frontend/.env.production",
+		"frontend/.env.development",
+		"frontend/.env.desktop",
+	}
+)
+
+type Version struct {
+	Major int
+	Minor int
+	Patch int
+}
+
+func Parse(raw string) (Version, error) {
+	trimmed := strings.TrimSpace(raw)
+	parts := semverRegex.FindStringSubmatch(trimmed)
+	if parts == nil {
+		return Version{}, fmt.Errorf("版本号 %q 不符合 x.y.z 格式", raw)
+	}
+
+	major, err := strconv.Atoi(parts[1])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 major 失败: %w", err)
+	}
+
+	minor, err := strconv.Atoi(parts[2])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 minor 失败: %w", err)
+	}
+
+	patch, err := strconv.Atoi(parts[3])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 patch 失败: %w", err)
+	}
+
+	return Version{Major: major, Minor: minor, Patch: patch}, nil
+}
+
+func (v Version) String() string {
+	return fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch)
+}
+
+func (v Version) Less(other Version) bool {
+	if v.Major != other.Major {
+		return v.Major < other.Major
+	}
+
+	if v.Minor != other.Minor {
+		return v.Minor < other.Minor
+	}
+
+	return v.Patch < other.Patch
+}
+
+func FindRepoRoot(start string) (string, error) {
+	current := start
+	for {
+		workspacePath := filepath.Join(current, "go.work")
+		if _, err := os.Stat(workspacePath); err == nil {
+			return current, nil
+		}
+
+		parent := filepath.Dir(current)
+		if parent == current {
+			return "", errors.New("未找到仓库根目录 go.work")
+		}
+
+		current = parent
+	}
+}
+
+func Read(root string) (Version, error) {
+	content, err := os.ReadFile(filepath.Join(root, versionFileName))
+	if err != nil {
+		return Version{}, fmt.Errorf("读取 VERSION 失败: %w", err)
+	}
+
+	return Parse(string(content))
+}
+
+func ReadString(root string) (string, error) {
+	version, err := Read(root)
+	if err != nil {
+		return "", err
+	}
+
+	return version.String(), nil
+}
+
+func Sync(root string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	packageJSONPath := filepath.Join(root, "frontend", "package.json")
+	packageJSONContent, err := os.ReadFile(packageJSONPath)
+	if err != nil {
+		return fmt.Errorf("读取 frontend/package.json 失败: %w", err)
+	}
+
+	updatedPackageJSON, err := UpdatePackageJSONVersion(string(packageJSONContent), version)
+	if err != nil {
+		return err
+	}
+
+	if err := os.WriteFile(packageJSONPath, []byte(updatedPackageJSON), 0o600); err != nil {
+		return fmt.Errorf("写入 frontend/package.json 失败: %w", err)
+	}
+
+	for _, relPath := range frontendVersionFiles {
+		fullPath := filepath.Join(root, relPath)
+		content, err := os.ReadFile(fullPath)
+		if err != nil {
+			return fmt.Errorf("读取 %s 失败: %w", relPath, err)
+		}
+
+		updated := UpsertEnvVar(string(content), "VITE_APP_VERSION", version)
+		if err := os.WriteFile(fullPath, []byte(updated), 0o600); err != nil {
+			return fmt.Errorf("写入 %s 失败: %w", relPath, err)
+		}
+	}
+
+	return nil
+}
+
+func Check(root string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	var errs []error
+
+	packageJSONPath := filepath.Join(root, "frontend", "package.json")
+	packageJSONContent, err := os.ReadFile(packageJSONPath)
+	if err != nil {
+		errs = append(errs, fmt.Errorf("读取 frontend/package.json 失败: %w", err))
+	} else {
+		actualVersion, readErr := ReadPackageJSONVersion(string(packageJSONContent))
+		if readErr != nil {
+			errs = append(errs, readErr)
+		} else if actualVersion != version {
+			errs = append(errs, fmt.Errorf("frontend/package.json 版本为 %s，期望 %s", actualVersion, version))
+		}
+	}
+
+	for _, relPath := range frontendVersionFiles {
+		fullPath := filepath.Join(root, relPath)
+		content, readErr := os.ReadFile(fullPath)
+		if readErr != nil {
+			errs = append(errs, fmt.Errorf("读取 %s 失败: %w", relPath, readErr))
+			continue
+		}
+
+		actualValue, ok := ReadEnvVar(string(content), "VITE_APP_VERSION")
+		if !ok {
+			errs = append(errs, fmt.Errorf("%s 缺少 VITE_APP_VERSION", relPath))
+			continue
+		}
+
+		if actualValue != version {
+			errs = append(errs, fmt.Errorf("%s 的 VITE_APP_VERSION 为 %s，期望 %s", relPath, actualValue, version))
+		}
+	}
+
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+
+	return nil
+}
+
+func VerifyTag(root, tag string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	if !strings.HasPrefix(tag, "v") {
+		return fmt.Errorf("tag %q 必须以 v 开头", tag)
+	}
+
+	if tag[1:] != version {
+		return fmt.Errorf("tag %q 与 VERSION %q 不一致", tag, version)
+	}
+
+	return nil
+}
+
+func UpdatePackageJSONVersion(content, version string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	if !packageVersionRegex.MatchString(content) {
+		return "", errors.New("frontend/package.json 缺少 version 字段")
+	}
+
+	updated := packageVersionRegex.ReplaceAllString(content, `${1}`+version+`${3}`)
+	return updated, nil
+}
+
+func ReadPackageJSONVersion(content string) (string, error) {
+	parts := packageVersionRegex.FindStringSubmatch(content)
+	if parts == nil {
+		return "", errors.New("frontend/package.json 缺少 version 字段")
+	}
+
+	if _, err := Parse(parts[2]); err != nil {
+		return "", err
+	}
+
+	return parts[2], nil
+}
+
+func UpsertEnvVar(content, key, value string) string {
+	lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
+	if len(lines) == 1 && lines[0] == "" {
+		lines = lines[:0]
+	}
+
+	updated := false
+	for i, line := range lines {
+		if strings.HasPrefix(line, key+"=") {
+			lines[i] = key + "=" + value
+			updated = true
+		}
+	}
+
+	if !updated {
+		lines = append(lines, key+"="+value)
+	}
+
+	return strings.Join(lines, "\n") + "\n"
+}
+
+func ReadEnvVar(content, key string) (string, bool) {
+	for _, line := range strings.Split(content, "\n") {
+		if strings.HasPrefix(line, key+"=") {
+			return strings.TrimPrefix(line, key+"="), true
+		}
+	}
+
+	return "", false
+}
+
+func ServerAssetName(version, goos, arch string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	switch goos {
+	case "linux", "windows", "darwin":
+	default:
+		return "", fmt.Errorf("不支持的 server 平台 %q", goos)
+	}
+
+	if arch == "" {
+		return "", errors.New("server 资产命名缺少架构")
+	}
+
+	ext := ".tar.gz"
+	if goos == "windows" {
+		ext = ".zip"
+	}
+
+	return fmt.Sprintf("nex-server_%s_%s_%s%s", version, goos, arch, ext), nil
+}
+
+func DesktopAssetName(version, platform string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	switch platform {
+	case "linux":
+		return fmt.Sprintf("Nex_%s_linux_amd64.tar.gz", version), nil
+	case "windows":
+		return fmt.Sprintf("Nex_%s_windows_amd64.zip", version), nil
+	case "macos":
+		return fmt.Sprintf("Nex_%s_macOS_universal.zip", version), nil
+	default:
+		return "", fmt.Errorf("不支持的 desktop 平台 %q", platform)
+	}
+}
+
+func DesktopInfoPlist(version, minMacOSVersion string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	if strings.TrimSpace(minMacOSVersion) == "" {
+		return "", errors.New("min macOS version 不能为空")
+	}
+
+	content := strings.Join([]string{
+		`<?xml version="1.0" encoding="UTF-8"?>`,
+		`<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">`,
+		`<plist version="1.0">`,
+		`<dict>`,
+		`    <key>CFBundleDevelopmentRegion</key>`,
+		`    <string>zh-Hans</string>`,
+		`    <key>CFBundleExecutable</key>`,
+		`    <string>nex</string>`,
+		`    <key>CFBundleIconFile</key>`,
+		`    <string>icon</string>`,
+		`    <key>CFBundleIdentifier</key>`,
+		`    <string>com.lanyuanxiaoyao.nex</string>`,
+		`    <key>CFBundleInfoDictionaryVersion</key>`,
+		`    <string>6.0</string>`,
+		`    <key>LSApplicationCategoryType</key>`,
+		`    <string>public.app-category.developer-tools</string>`,
+		`    <key>CFBundleName</key>`,
+		`    <string>Nex</string>`,
+		`    <key>CFBundleDisplayName</key>`,
+		`    <string>Nex</string>`,
+		`    <key>CFBundlePackageType</key>`,
+		`    <string>APPL</string>`,
+		`    <key>CFBundleShortVersionString</key>`,
+		`    <string>` + version + `</string>`,
+		`    <key>CFBundleVersion</key>`,
+		`    <string>` + version + `</string>`,
+		`    <key>NSHumanReadableCopyright</key>`,
+		`    <string>Copyright © 2026 Nex</string>`,
+		`    <key>LSMinimumSystemVersion</key>`,
+		`    <string>` + minMacOSVersion + `</string>`,
+		`    <key>LSUIElement</key>`,
+		`    <true/>`,
+		`    <key>NSHighResolutionCapable</key>`,
+		`    <true/>`,
+		`</dict>`,
+		`</plist>`,
+	}, "\n")
+
+	return content + "\n", nil
+}
+
+var tagRegex = regexp.MustCompile(`^v(\d+\.\d+\.\d+)$`)
+
+func ListGitTags(root string) ([]string, error) {
+	cmd := exec.Command("git", "-C", root, "tag", "--list", "--merge", "HEAD")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("获取 git tag 列表失败: %w", err)
+	}
+
+	var tags []string
+	for _, line := range strings.Split(strings.TrimSpace(string(output)), "\n") {
+		line = strings.TrimSpace(line)
+		if line != "" {
+			tags = append(tags, line)
+		}
+	}
+
+	return tags, nil
+}
+
+func CheckNoRegression(newVersion Version, tags []string) error {
+	var maxVersion Version
+	found := false
+
+	for _, tag := range tags {
+		parts := tagRegex.FindStringSubmatch(tag)
+		if parts == nil {
+			continue
+		}
+
+		v, err := Parse(parts[1])
+		if err != nil {
+			continue
+		}
+
+		if !found || maxVersion.Less(v) {
+			maxVersion = v
+			found = true
+		}
+	}
+
+	if !found {
+		return nil
+	}
+
+	if newVersion == maxVersion {
+		return fmt.Errorf("版本号 %s 已存在（tag v%s）", newVersion, maxVersion)
+	}
+
+	if newVersion.Less(maxVersion) {
+		return fmt.Errorf("版本号 %s 小于已有 tag v%s，不允许倒退", newVersion, maxVersion)
+	}
+
+	return nil
+}
+
+func Bump(root, arg string) (Version, error) {
+	current, err := Read(root)
+	if err != nil {
+		return Version{}, err
+	}
+
+	var newVersion Version
+
+	switch arg {
+	case "major":
+		newVersion = Version{Major: current.Major + 1, Minor: 0, Patch: 0}
+	case "minor":
+		newVersion = Version{Major: current.Major, Minor: current.Minor + 1, Patch: 0}
+	case "patch":
+		newVersion = Version{Major: current.Major, Minor: current.Minor, Patch: current.Patch + 1}
+	default:
+		parsed, parseErr := Parse(arg)
+		if parseErr != nil {
+			return Version{}, fmt.Errorf("参数 %q 既非 major|minor|patch 也非合法版本号: %w", arg, parseErr)
+		}
+
+		newVersion = parsed
+	}
+
+	versionPath := filepath.Join(root, versionFileName)
+	if err := os.WriteFile(versionPath, []byte(newVersion.String()+"\n"), 0o600); err != nil {
+		return Version{}, fmt.Errorf("写入 VERSION 失败: %w", err)
+	}
+
+	return newVersion, nil
+}
--- a/versionctl/projectversion/version_test.go
+++ b/versionctl/projectversion/version_test.go
@@ -0,0 +1,215 @@
+package projectversion
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParse(t *testing.T) {
+	t.Run("valid", func(t *testing.T) {
+		version, err := Parse("1.2.3")
+		require.NoError(t, err)
+		assert.Equal(t, Version{Major: 1, Minor: 2, Patch: 3}, version)
+		assert.Equal(t, "1.2.3", version.String())
+	})
+
+	t.Run("invalid", func(t *testing.T) {
+		invalidValues := []string{"", "1.2", "1.2.3.4", "v1.2.3", "01.2.3", "1.02.3"}
+		for _, tc := range invalidValues {
+			_, err := Parse(tc)
+			assert.Error(t, err, "%q 应校验失败", tc)
+		}
+	})
+}
+
+func TestUpdatePackageJSONVersion(t *testing.T) {
+	content := "{\n  \"name\": \"frontend\",\n  \"version\": \"0.0.0\"\n}\n"
+	updated, err := UpdatePackageJSONVersion(content, "1.2.3")
+	require.NoError(t, err)
+	assert.Contains(t, updated, `"version": "1.2.3"`)
+
+	version, err := ReadPackageJSONVersion(updated)
+	require.NoError(t, err)
+	assert.Equal(t, "1.2.3", version)
+}
+
+func TestUpsertEnvVar(t *testing.T) {
+	updated := UpsertEnvVar("VITE_API_BASE=/api\n", "VITE_APP_VERSION", "1.2.3")
+	assert.Contains(t, updated, "VITE_API_BASE=/api\n")
+	assert.Contains(t, updated, "VITE_APP_VERSION=1.2.3\n")
+
+	updated = UpsertEnvVar(updated, "VITE_APP_VERSION", "2.0.0")
+	value, ok := ReadEnvVar(updated, "VITE_APP_VERSION")
+	assert.True(t, ok)
+	assert.Equal(t, "2.0.0", value)
+	assert.Equal(t, 1, strings.Count(updated, "VITE_APP_VERSION="))
+}
+
+func TestSyncAndCheck(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("1.2.3\n"), 0o600))
+	require.NoError(t, os.MkdirAll(filepath.Join(root, "frontend"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", "package.json"), []byte("{\n  \"name\": \"frontend\",\n  \"version\": \"0.0.0\"\n}\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.production"), []byte("VITE_API_BASE=/api\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.development"), []byte("VITE_API_BASE=\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.desktop"), []byte("VITE_API_BASE=\n"), 0o600))
+
+	require.NoError(t, Sync(root))
+	require.NoError(t, Check(root))
+
+	packageJSONContent, err := os.ReadFile(filepath.Join(root, "frontend", "package.json"))
+	require.NoError(t, err)
+	assert.Contains(t, string(packageJSONContent), `"version": "1.2.3"`)
+
+	for _, relPath := range frontendVersionFiles {
+		content, readErr := os.ReadFile(filepath.Join(root, relPath))
+		require.NoError(t, readErr)
+		assert.Contains(t, string(content), "VITE_APP_VERSION=1.2.3\n")
+	}
+}
+
+func TestVerifyTag(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("1.2.3\n"), 0o600))
+
+	require.NoError(t, VerifyTag(root, "v1.2.3"))
+	assert.Error(t, VerifyTag(root, "1.2.3"))
+	assert.Error(t, VerifyTag(root, "v1.2.4"))
+}
+
+func TestAssetNames(t *testing.T) {
+	linuxServer, err := ServerAssetName("1.2.3", "linux", "amd64")
+	require.NoError(t, err)
+	assert.Equal(t, "nex-server_1.2.3_linux_amd64.tar.gz", linuxServer)
+
+	macServer, err := ServerAssetName("1.2.3", "darwin", "arm64")
+	require.NoError(t, err)
+	assert.Equal(t, "nex-server_1.2.3_darwin_arm64.tar.gz", macServer)
+
+	macDesktop, err := DesktopAssetName("1.2.3", "macos")
+	require.NoError(t, err)
+	assert.Equal(t, "Nex_1.2.3_macOS_universal.zip", macDesktop)
+
+	_, err = DesktopAssetName("1.2.3", "ios")
+	assert.Error(t, err)
+}
+
+func TestDesktopInfoPlist(t *testing.T) {
+	plist, err := DesktopInfoPlist("1.2.3", "13.0")
+	require.NoError(t, err)
+	assert.Contains(t, plist, "<key>CFBundleShortVersionString</key>\n    <string>1.2.3</string>")
+	assert.Contains(t, plist, "<key>CFBundleVersion</key>\n    <string>1.2.3</string>")
+	assert.Contains(t, plist, "<key>LSMinimumSystemVersion</key>\n    <string>13.0</string>")
+
+	_, err = DesktopInfoPlist("1.2", "13.0")
+	assert.Error(t, err)
+	_, err = DesktopInfoPlist("1.2.3", "")
+	assert.Error(t, err)
+}
+
+func TestLess(t *testing.T) {
+	assert.True(t, Version{1, 0, 0}.Less(Version{2, 0, 0}))
+	assert.True(t, Version{1, 1, 0}.Less(Version{1, 2, 0}))
+	assert.True(t, Version{1, 0, 1}.Less(Version{1, 0, 2}))
+	assert.False(t, Version{2, 0, 0}.Less(Version{1, 0, 0}))
+	assert.False(t, Version{1, 0, 0}.Less(Version{1, 0, 0}))
+}
+
+func TestBump(t *testing.T) {
+	setupRoot := func(t *testing.T) string {
+		t.Helper()
+		root := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("0.1.0\n"), 0o600))
+		return root
+	}
+
+	t.Run("major", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "major")
+		require.NoError(t, err)
+		assert.Equal(t, Version{1, 0, 0}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "1.0.0", read)
+	})
+
+	t.Run("minor", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "minor")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 2, 0}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "0.2.0", read)
+	})
+
+	t.Run("patch", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "patch")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 1, 1}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "0.1.1", read)
+	})
+
+	t.Run("specific version", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "1.0.0")
+		require.NoError(t, err)
+		assert.Equal(t, Version{1, 0, 0}, v)
+	})
+
+	t.Run("same version as current", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "0.1.0")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 1, 0}, v)
+	})
+
+	t.Run("invalid argument", func(t *testing.T) {
+		root := setupRoot(t)
+		_, err := Bump(root, "invalid")
+		assert.Error(t, err)
+	})
+}
+
+func TestCheckNoRegression(t *testing.T) {
+	t.Run("greater than existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 2, 0}, []string{"v0.1.0"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("equal to existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 0}, []string{"v0.1.0"})
+		assert.Error(t, err)
+	})
+
+	t.Run("less than existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 5}, []string{"v0.2.0"})
+		assert.Error(t, err)
+	})
+
+	t.Run("no tags", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 0}, nil)
+		assert.NoError(t, err)
+	})
+
+	t.Run("skips non-semver tags", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 2, 0}, []string{"v0.1.0", "some-other-tag"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("picks max tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 5}, []string{"v0.1.0", "v0.2.0", "v0.0.5"})
+		assert.Error(t, err)
+	})
+}