Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

30.4 KB
Raw Blame
package installtests

import (
	"fmt"
	"os"
	"os/exec"
	"path/filepath"
	"strconv"
	"strings"
	"testing"

	"gopkg.in/yaml.v3"
)

func currentReleaseVersion(t *testing.T) string {
	t.Helper()
	content, err := os.ReadFile(repoFile("VERSION"))
	if err != nil {
		t.Fatalf("read VERSION: %v", err)
	}
	version := strings.TrimSpace(string(content))
	if version == "" {
		t.Fatal("VERSION is empty")
	}
	return version
}

func requiredReleaseBranchForVersion(t *testing.T, version string) string {
	t.Helper()
	cmd := exec.Command("python3", repoFile("scripts", "release_control", "control_plane.py"), "--branch-for-version", version)
	output, err := cmd.Output()
	if err != nil {
		t.Fatalf("resolve release branch for %s: %v", version, err)
	}
	branch := strings.TrimSpace(string(output))
	if branch == "" {
		t.Fatalf("release branch for %s is empty", version)
	}
	return branch
}

func isPrereleaseVersion(version string) bool {
	return strings.Contains(version, "-")
}

// unpublishedStableVersions lists stable versions that never activated as a
// public GitHub release, whether or not a same-version tag or packet was
// staged. They are not valid rollback targets and must not be treated as the
// previous stable.
var unpublishedStableVersions = map[string]bool{
	// Tagged 2026-08-31; the private Pro build failed its memory gate and the
	// release commit verdict failed, so the packet shipped through v6.4.3 instead.
	"6.4.2": true,
	// v6.4.3 and v6.4.4 were only ever published as prereleases
	// (v6.4.3-rc.1, v6.4.4-beta.N). The v6.4.5 stable patch promotes the
	// exercised v6.4.5-rc.N candidate, so the last published stable remains
	// v6.4.1 and is the rollback target.
	"6.4.3": true,
	"6.4.4": true,
}

func previousStablePatchVersion(version string) (string, bool) {
	if isPrereleaseVersion(version) {
		return "", false
	}
	parts := strings.Split(version, ".")
	if len(parts) != 3 {
		return "", false
	}
	patch, err := strconv.Atoi(parts[2])
	if err != nil {
		return "", false
	}
	for patch > 0 {
		patch--
		candidate := fmt.Sprintf("%s.%s.%d", parts[0], parts[1], patch)
		if !unpublishedStableVersions[candidate] {
			return candidate, true
		}
	}
	return "", false
}

// stablePatchPromotedPrerelease reports the same-version release candidate a
// stable patch promotes, if one exists. A stable patch with a same-version RC
// is RC-derived: the promotion resolver selects promotion_mode
// "stable-rc-promotion" and refuses the emergency no-RC hotfix path, so the
// install-metadata contract must assert that shape instead of the emergency
// one. Detection reads the published candidate notes so it stays offline and
// matches the release line's retained metadata.
func stablePatchPromotedPrerelease(docsReleasesDir, version string) (string, bool) {
	if isPrereleaseVersion(version) {
		return "", false
	}
	matches, err := filepath.Glob(filepath.Join(docsReleasesDir, "RELEASE_NOTES_v"+version+"-rc.*.md"))
	if err != nil {
		return "", false
	}
	best := ""
	bestNumber := -1
	for _, match := range matches {
		filename := filepath.Base(match)
		tag := strings.TrimSuffix(strings.TrimPrefix(filename, "RELEASE_NOTES_v"), ".md")
		marker := strings.LastIndex(tag, "-rc.")
		if marker < 0 {
			continue
		}
		number, err := strconv.Atoi(tag[marker+len("-rc."):])
		if err != nil {
			continue
		}
		if number > bestNumber {
			bestNumber = number
			best = "v" + tag
		}
	}
	if best == "" {
		return "", false
	}
	return best, true
}

func currentStablePatchPromotedPrerelease(t *testing.T, version string) (string, bool) {
	t.Helper()
	return stablePatchPromotedPrerelease(repoFile("docs", "releases"), version)
}

func previousStableForPrereleaseVersion(version string) (string, bool) {
	if !isPrereleaseVersion(version) {
		return "", false
	}
	base, _, ok := strings.Cut(version, "-")
	if !ok {
		return "", false
	}
	baseParts, ok := parseStableVersion(base)
	if !ok {
		return "", false
	}

	releaseNotes, err := filepath.Glob(repoFile("docs", "releases", "RELEASE_NOTES_v*.md"))
	if err != nil {
		return "", false
	}

	best := [3]int{-1, -1, -1}
	found := false
	for _, releaseNote := range releaseNotes {
		filename := filepath.Base(releaseNote)
		candidate := strings.TrimSuffix(strings.TrimPrefix(filename, "RELEASE_NOTES_v"), ".md")
		parts, valid := parseStableVersion(candidate)
		if !valid || compareStableVersions(parts, baseParts) >= 0 || unpublishedStableVersions[candidate] {
			continue
		}
		if !found || compareStableVersions(parts, best) > 0 {
			best = parts
			found = true
		}
	}
	if !found {
		return "", false
	}
	return fmt.Sprintf("%d.%d.%d", best[0], best[1], best[2]), true
}

func parseStableVersion(version string) ([3]int, bool) {
	parts := strings.Split(version, ".")
	if len(parts) != 3 {
		return [3]int{}, false
	}
	parsed := [3]int{}
	for index, part := range parts {
		value, err := strconv.Atoi(part)
		if err != nil || value < 0 {
			return [3]int{}, false
		}
		parsed[index] = value
	}
	return parsed, true
}

func compareStableVersions(left, right [3]int) int {
	for index := range left {
		if left[index] < right[index] {
			return -1
		}
		if left[index] > right[index] {
			return 1
		}
	}
	return 0
}

func TestPreviousStableForPrereleaseVersionCrossesMinorBoundaries(t *testing.T) {
	tests := []struct {
		version string
		want    string
	}{
		{version: "6.0.5-rc.4", want: "6.0.4"},
		{version: "6.2.0-rc.4", want: "6.1.2"},
		{version: "6.2.0-rc.5", want: "6.1.2"},
		{version: "6.2.0-rc.6", want: "6.1.2"},
		{version: "6.2.0-rc.7", want: "6.1.2"},
		{version: "6.2.0-rc.8", want: "6.1.2"},
		{version: "6.2.0-rc.9", want: "6.1.2"},
		{version: "6.2.0-rc.10", want: "6.1.2"},
		{version: "6.2.0-rc.11", want: "6.1.2"},
		{version: "6.2.2-rc.1", want: "6.2.1"},
		{version: "6.2.2-rc.2", want: "6.2.1"},
		{version: "6.2.2-rc.3", want: "6.2.1"},
		{version: "6.3.0-rc.1", want: "6.2.1"},
		{version: "6.3.0-rc.2", want: "6.2.1"},
		{version: "6.4.0-rc.1", want: "6.3.2"},
		{version: "6.4.0-rc.2", want: "6.3.2"},
		{version: "6.4.0-rc.3", want: "6.3.2"},
		{version: "6.4.0-rc.4", want: "6.3.2"},
		{version: "6.4.0-rc.5", want: "6.3.2"},
		{version: "6.4.0-rc.6", want: "6.3.2"},
		{version: "6.4.0-rc.7", want: "6.3.2"},
		{version: "6.4.0-rc.8", want: "6.3.2"},
		{version: "6.4.0-rc.9", want: "6.3.2"},
		{version: "6.4.0-rc.10", want: "6.3.2"},
		{version: "6.4.0-rc.11", want: "6.3.2"},
		{version: "6.4.0-rc.12", want: "6.3.2"},
		{version: "6.4.0-rc.13", want: "6.3.2"},
	}

	for _, test := range tests {
		t.Run(test.version, func(t *testing.T) {
			got, ok := previousStableForPrereleaseVersion(test.version)
			if !ok {
				t.Fatalf("previousStableForPrereleaseVersion(%q) did not find a stable release", test.version)
			}
			if got != test.want {
				t.Fatalf("previousStableForPrereleaseVersion(%q) = %q, want %q", test.version, got, test.want)
			}
		})
	}
}

func TestPreviousStablePatchVersionSkipsUnpublishedStables(t *testing.T) {
	tests := []struct {
		version string
		want    string
		ok      bool
	}{
		{version: "6.4.1", want: "6.4.0", ok: true},
		{version: "6.4.2", want: "6.4.1", ok: true},
		// v6.4.2 was tagged but never published; v6.4.3 and v6.4.4 only ever
		// shipped as prereleases, so v6.4.5 rolls back to the published v6.4.1.
		{version: "6.4.5", want: "6.4.1", ok: true},
		{version: "6.4.0", ok: false},
		{version: "6.4.5-rc.2", ok: false},
	}
	for _, test := range tests {
		t.Run(test.version, func(t *testing.T) {
			got, ok := previousStablePatchVersion(test.version)
			if ok != test.ok || got != test.want {
				t.Fatalf("previousStablePatchVersion(%q) = %q, %v; want %q, %v", test.version, got, ok, test.want, test.ok)
			}
		})
	}
}

func TestStablePatchPromotedPrereleaseDetectsSameVersionCandidate(t *testing.T) {
	dir := t.TempDir()
	for _, name := range []string{
		"RELEASE_NOTES_v6.4.5-rc.1.md",
		"RELEASE_NOTES_v6.4.5-rc.2.md",
		"RELEASE_NOTES_v6.4.4-beta.4.md",
		"RELEASE_NOTES_v6.4.5-beta.1.md",
	} {
		if err := os.WriteFile(filepath.Join(dir, name), []byte("x"), 0o600); err != nil {
			t.Fatalf("write %s: %v", name, err)
		}
	}
	if got, ok := stablePatchPromotedPrerelease(dir, "6.4.5"); !ok || got != "v6.4.5-rc.2" {
		t.Fatalf("stablePatchPromotedPrerelease(6.4.5) = %q, %v; want v6.4.5-rc.2, true", got, ok)
	}
	if got, ok := stablePatchPromotedPrerelease(dir, "6.4.6"); ok {
		t.Fatalf("stablePatchPromotedPrerelease(6.4.6) = %q, true; want no same-version candidate", got)
	}
	if got, ok := stablePatchPromotedPrerelease(dir, "6.4.5-rc.2"); ok {
		t.Fatalf("stablePatchPromotedPrerelease(6.4.5-rc.2) = %q, true; want prerelease ignored", got)
	}
}

// previousPrereleaseVersion names the predecessor of a numbered pre-release in its own
// stage, as the release metadata tool does: rc.2 follows rc.1 and beta.2 follows beta.1.
// The first of a stage has none, even when an earlier stage shipped.
func previousPrereleaseVersion(version string) (string, bool) {
	for _, stage := range []string{"alpha", "beta", "rc"} {
		base, suffix, ok := strings.Cut(version, "-"+stage+".")
		if !ok {
			continue
		}
		number, err := strconv.Atoi(suffix)
		if err != nil || number <= 1 {
			return "", false
		}
		return fmt.Sprintf("%s-%s.%d", base, stage, number-1), true
	}
	return "", false
}

// This predecessor is the metadata tool's default comparison base. A cumulative
// changelog can explicitly compare with the previous stable instead.
func TestPreviousPrereleaseVersionFollowsItsOwnStage(t *testing.T) {
	for _, tc := range []struct {
		version, want string
		ok            bool
	}{
		{"6.6.0-rc.2", "6.6.0-rc.1", true},
		{"6.6.0-rc.12", "6.6.0-rc.11", true},
		{"6.6.0-beta.2", "6.6.0-beta.1", true},
		{"6.6.0-beta.7", "6.6.0-beta.6", true},
		{"6.6.0-alpha.3", "6.6.0-alpha.2", true},
		{"6.6.0-beta.1", "", false},
		{"6.6.0-rc.1", "", false},
		{"6.6.0-alpha.1", "", false},
		{"6.6.0-beta.x", "", false},
		{"6.6.0", "", false},
	} {
		got, ok := previousPrereleaseVersion(tc.version)
		if got != tc.want || ok != tc.ok {
			t.Errorf("previousPrereleaseVersion(%q) = %q, %v; want %q, %v", tc.version, got, ok, tc.want, tc.ok)
		}
	}
}

func TestInstallDockerScriptUsesConfiguredImageRepoDefault(t *testing.T) {
	workDir := t.TempDir()
	version := currentReleaseVersion(t)
	runInstallDockerScript(t, workDir, "DOCKER_IMAGE_REPO=example/pulse-enterprise")

	composePath := filepath.Join(workDir, "docker-compose.yml")
	composeContent, err := os.ReadFile(composePath)
	if err != nil {
		t.Fatalf("read docker-compose.yml: %v", err)
	}
	composeText := string(composeContent)
	if !strings.Contains(composeText, "image: ${PULSE_IMAGE:-example/pulse-enterprise:"+version+"}") {
		t.Fatalf("docker-compose.yml missing configured image default:\n%s", composeText)
	}
	if strings.Contains(composeText, ":latest") {
		t.Fatalf("docker-compose.yml must not default to a floating latest tag:\n%s", composeText)
	}

	envPath := filepath.Join(workDir, ".env")
	envContent, err := os.ReadFile(envPath)
	if err != nil {
		t.Fatalf("read .env: %v", err)
	}
	envText := string(envContent)
	if !strings.Contains(envText, "PULSE_IMAGE=example/pulse-enterprise:"+version) {
		t.Fatalf(".env missing configured image default:\n%s", envText)
	}
}

func TestInstallDockerScriptPrefersExplicitPulseImage(t *testing.T) {
	workDir := t.TempDir()
	version := currentReleaseVersion(t)
	runInstallDockerScript(
		t,
		workDir,
		"DOCKER_IMAGE_REPO=example/pulse-enterprise",
		"PULSE_IMAGE=ghcr.io/example/pulse-enterprise:v9.9.9",
	)

	composePath := filepath.Join(workDir, "docker-compose.yml")
	composeContent, err := os.ReadFile(composePath)
	if err != nil {
		t.Fatalf("read docker-compose.yml: %v", err)
	}
	composeText := string(composeContent)
	if !strings.Contains(composeText, "image: ${PULSE_IMAGE:-example/pulse-enterprise:"+version+"}") {
		t.Fatalf("docker-compose.yml lost configured default image:\n%s", composeText)
	}

	envPath := filepath.Join(workDir, ".env")
	envContent, err := os.ReadFile(envPath)
	if err != nil {
		t.Fatalf("read .env: %v", err)
	}
	envText := string(envContent)
	if !strings.Contains(envText, "PULSE_IMAGE=ghcr.io/example/pulse-enterprise:v9.9.9") {
		t.Fatalf(".env did not preserve explicit image override:\n%s", envText)
	}
}

// Execute the commands from both real Compose producers. Only the fixed
// image-local script path is relocated; the shipped probe runs unchanged with
// an inert wget double. These fixtures need neither Docker nor a live endpoint.
func TestDockerComposeHealthcheckPreservesImageProbe(t *testing.T) {
	generatedDir := t.TempDir()
	runInstallDockerScript(t, generatedDir)
	for name, composePath := range map[string]string{
		"bundled":   repoFile("docker-compose.yml"),
		"generated": filepath.Join(generatedDir, "docker-compose.yml"),
	} {
		t.Run(name, func(t *testing.T) {
			content, err := os.ReadFile(composePath)
			if err != nil {
				t.Fatal(err)
			}
			var compose struct {
				Services map[string]struct {
					Healthcheck struct {
						Test []string `yaml:"test"`
					} `yaml:"healthcheck"`
				} `yaml:"services"`
			}
			if err := yaml.Unmarshal(content, &compose); err != nil {
				t.Fatalf("parse Compose healthcheck: %v", err)
			}
			command := compose.Services["pulse"].Healthcheck.Test
			if len(command) != 2 || command[0] != "CMD-SHELL" {
				t.Fatalf("expected a shell image-probe selector, got %q", command)
			}
			if strings.Count(command[1], "/docker-healthcheck.sh") != 2 {
				t.Fatal("image-probe path boundary changed; update the explicit fixture")
			}
			for _, tc := range []struct {
				name, helper, https string
				httpExit, httpsExit int
				wantExit            int
				wantProbes          string
			}{
				{"http healthy", "shipped", "false", 0, 1, 0, "http\n"},
				{"http unhealthy", "shipped", "false", 1, 0, 1, "http\n"},
				{"https healthy", "shipped", "true", 1, 0, 0, "https\n"},
				{"https numeric healthy", "shipped", "1", 1, 0, 0, "https\n"},
				{"https unhealthy with healthy http", "shipped", "true", 0, 1, 1, "https\n"},
				{"https numeric unhealthy with healthy http", "shipped", "1", 0, 1, 1, "https\n"},
				{"unset uses http", "shipped", "", 0, 1, 0, "http\n"},
				{"legacy healthy", "absent", "", 0, 1, 0, "http\n"},
				{"legacy unhealthy", "absent", "", 1, 0, 1, "http\n"},
				{"nonexecutable legacy helper", "nonexecutable", "", 0, 1, 0, "http\n"},
				{"custom image failure", "custom", "", 0, 0, 17, ""},
			} {
				t.Run(tc.name, func(t *testing.T) {
					dir := t.TempDir()
					helperPath := filepath.Join(dir, "docker-healthcheck.sh")
					if tc.helper != "absent" {
						helper, err := os.ReadFile(repoFile("docker-healthcheck.sh"))
						if err != nil {
							t.Fatal(err)
						}
						mode := os.FileMode(0o700)
						if tc.helper == "nonexecutable" {
							mode = 0o600
						}
						if tc.helper == "custom" {
							helper = []byte("#!/bin/sh\necho 'image probe refused' >&2\nexit 17\n")
						}
						if err := os.WriteFile(helperPath, helper, mode); err != nil {
							t.Fatal(err)
						}
					}
					writeTestStub(t, filepath.Join(dir, "wget"), `#!/bin/sh
case "$*" in
    *https://localhost:7655/api/health*) protocol=https; result="$HTTPS_RESULT";;
    *http://localhost:7655/api/health*) protocol=http; result="$HTTP_RESULT";;
    *) echo 'unexpected probe target' >&2; exit 93;;
esac
printf '%s\n' "$protocol" >> "$PROBE_LOG"
exit "$result"
`)
					probeLog := filepath.Join(dir, "probes")
					cmd := exec.Command("sh", "-c", strings.ReplaceAll(command[1], "/docker-healthcheck.sh", `"`+helperPath+`"`))
					cmd.Env = []string{
						"PATH=" + dir,
						"HTTP_RESULT=" + strconv.Itoa(tc.httpExit),
						"HTTPS_RESULT=" + strconv.Itoa(tc.httpsExit),
						"PROBE_LOG=" + probeLog,
					}
					if tc.https != "" {
						cmd.Env = append(cmd.Env, "HTTPS_ENABLED="+tc.https)
					}
					output, err := cmd.CombinedOutput()
					exitCode := 0
					if err != nil {
						if exitErr, ok := err.(*exec.ExitError); ok {
							exitCode = exitErr.ExitCode()
						} else {
							t.Fatalf("run healthcheck: %v", err)
						}
					}
					probes, readErr := os.ReadFile(probeLog)
					if readErr != nil && !os.IsNotExist(readErr) {
						t.Fatal(readErr)
					}
					if exitCode != tc.wantExit || string(probes) != tc.wantProbes {
						t.Fatalf("exit=%d probes=%q; want exit=%d probes=%q\n%s", exitCode, probes, tc.wantExit, tc.wantProbes, output)
					}
					if tc.helper == "custom" && !strings.Contains(string(output), "image probe refused") {
						t.Fatalf("image probe diagnostic was lost: %s", output)
					}
				})
			}
		})
	}
}

func TestRepoDockerComposeDefaultPinsCurrentVersion(t *testing.T) {
	version := currentReleaseVersion(t)
	content, err := os.ReadFile(repoFile("docker-compose.yml"))
	if err != nil {
		t.Fatalf("read docker-compose.yml: %v", err)
	}

	text := string(content)
	if !strings.Contains(text, "image: ${PULSE_IMAGE:-rcourtman/pulse:"+version+"}") {
		t.Fatalf("repo docker-compose.yml must pin the current release version:\n%s", text)
	}
	if !isPrereleaseVersion(version) && strings.Contains(text, "-rc.") {
		t.Fatalf("stable repo docker-compose.yml must not keep a prerelease image default:\n%s", text)
	}
	if !isPrereleaseVersion(version) && version == "6.0.0" && !strings.Contains(text, "rcourtman/pulse:6.0.0") {
		t.Fatalf("v6 GA repo docker-compose.yml must default to the stable v6 image:\n%s", text)
	}
	if !isPrereleaseVersion(version) && version != "6.0.0" && strings.Contains(text, "rcourtman/pulse:6.0.0") {
		t.Fatalf("stable patch repo docker-compose.yml must move off the initial GA image tag:\n%s", text)
	}
	if previous, ok := previousStablePatchVersion(version); ok && strings.Contains(text, "rcourtman/pulse:"+previous) {
		t.Fatalf("repo docker-compose.yml must not retain the previous stable patch image tag %s:\n%s", previous, text)
	}
	if previous, ok := previousPrereleaseVersion(version); ok && strings.Contains(text, "rcourtman/pulse:"+previous) {
		t.Fatalf("repo docker-compose.yml must not retain the previous prerelease image tag %s:\n%s", previous, text)
	}
	if strings.Contains(text, ":latest") {
		t.Fatalf("repo docker-compose.yml must not default to a floating latest tag:\n%s", text)
	}
}

func TestInstallDockerScriptFallbackPinsCurrentVersion(t *testing.T) {
	version := currentReleaseVersion(t)
	content, err := os.ReadFile(repoFile("scripts", "install-docker.sh"))
	if err != nil {
		t.Fatalf("read install-docker.sh: %v", err)
	}

	text := string(content)
	if !strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="`+version+`"`) {
		t.Fatalf("install-docker.sh fallback must pin the current release version:\n%s", text)
	}
	if !isPrereleaseVersion(version) && strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="`) && strings.Contains(text, "-rc.") {
		t.Fatalf("stable install-docker.sh fallback must not keep a prerelease default:\n%s", text)
	}
	if !isPrereleaseVersion(version) && version == "6.0.0" && !strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="6.0.0"`) {
		t.Fatalf("v6 GA install-docker.sh fallback must default to the stable v6 image tag:\n%s", text)
	}
	if !isPrereleaseVersion(version) && version != "6.0.0" && strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="6.0.0"`) {
		t.Fatalf("stable patch install-docker.sh fallback must move off the initial GA image tag:\n%s", text)
	}
	if previous, ok := previousStablePatchVersion(version); ok && strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="`+previous+`"`) {
		t.Fatalf("install-docker.sh fallback must not retain the previous stable patch version %s:\n%s", previous, text)
	}
	if previous, ok := previousPrereleaseVersion(version); ok && strings.Contains(text, `CANONICAL_DEFAULT_PULSE_VERSION="`+previous+`"`) {
		t.Fatalf("install-docker.sh fallback must not retain the previous prerelease version %s:\n%s", previous, text)
	}
}

func TestInstallDockerProofTracksStableMinorContract(t *testing.T) {
	version := currentReleaseVersion(t)
	if isPrereleaseVersion(version) {
		t.Skip("current release is a prerelease")
	}
	parts, valid := parseStableVersion(version)
	if !valid || parts[1] == 0 || parts[2] != 0 {
		t.Skip("current release is not a stable minor release")
	}
	if _, ok := previousStableForPrereleaseVersion(version + "-rc.1"); !ok {
		t.Fatal("stable minor release has no earlier stable rollback packet")
	}

	assertFileContainsAll(t, repoFile("docker-compose.yml"),
		"image: ${PULSE_IMAGE:-rcourtman/pulse:"+version+"}",
	)
	assertFileContainsAll(t, repoFile("scripts", "install-docker.sh"),
		`CANONICAL_DEFAULT_PULSE_VERSION="`+version+`"`,
	)
}

func runInstallDockerScript(t *testing.T, workDir string, envVars ...string) {
	t.Helper()
	out, err := runInstallDockerScriptResult(t, workDir, envVars...)
	if err != nil {
		t.Fatalf("run install-docker.sh: %v\n%s", err, out)
	}
}

func runInstallDockerScriptResult(t *testing.T, workDir string, envVars ...string) (string, error) {
	t.Helper()

	scriptPath := repoFile("scripts", "install-docker.sh")
	content, err := os.ReadFile(scriptPath)
	if err != nil {
		t.Fatalf("read install-docker.sh: %v", err)
	}

	script := string(content)
	// Only the two fixed host-admission checks are replaced. The generator,
	// path admission, writes and messages execute unchanged in a private fixture.
	if strings.Count(script, rootCheckBlock) != 1 || strings.Count(script, containerCheckBlock) != 1 {
		t.Fatal("installer host-admission boundaries changed; update the explicit test fixture")
	}
	script = strings.Replace(script, rootCheckBlock, ":", 1)
	script = strings.Replace(script, containerCheckBlock, ":", 1)

	tmpScript := filepath.Join(workDir, "install-docker.sh")
	if err := os.WriteFile(tmpScript, []byte(script), 0o755); err != nil {
		t.Fatalf("write temp install-docker.sh: %v", err)
	}

	binDir := filepath.Join(workDir, "bin")
	if err := os.MkdirAll(binDir, 0o755); err != nil {
		t.Fatalf("mkdir bin: %v", err)
	}
	writeTestStub(t, filepath.Join(binDir, "docker"), `#!/bin/sh
printf '%s\n' "$*" >> docker-calls
if [ "$*" != 'compose version' ]; then exit 91; fi
if [ "${TEST_RACE_COMPOSE:-}" = true ]; then
    printf '%s\n' 'racing owner configuration' > docker-compose.yml
fi
exit 0
`)
	writeTestStub(t, filepath.Join(binDir, "timedatectl"), "#!/bin/sh\necho Europe/London\n")
	writeTestStub(t, filepath.Join(binDir, "hostname"), "#!/bin/sh\nif [ \"$1\" = \"-I\" ]; then echo 192.0.2.10; else echo pulse-host; fi\n")

	cmd := exec.Command("bash", tmpScript)
	cmd.Dir = workDir
	cmd.Env = append(os.Environ(), append([]string{
		"PATH=" + binDir + string(os.PathListSeparator) + os.Getenv("PATH"),
	}, envVars...)...)
	out, err := cmd.CombinedOutput()
	return string(out), err
}

func writeTestStub(t *testing.T, path, content string) {
	t.Helper()
	if err := os.WriteFile(path, []byte(content), 0o755); err != nil {
		t.Fatalf("write stub %s: %v", path, err)
	}
}

const rootCheckBlock = `# Check if running as root (early check for better error messages)
if [ "$EUID" -ne 0 ]; then
    echo "❌ ERROR: This script must be run as root"
    echo ""
    echo "Please run: sudo $0"
    exit 1
fi
`

const containerCheckBlock = `# Detect if running in a container
if [ -f /.dockerenv ] || [ -f /run/.containerenv ]; then
    echo "❌ ERROR: This script must run on the Docker host, not inside a container"
    echo ""
    echo "Please run this script on your Docker host machine."
    exit 1
fi
`

func assertDockerSetupBytes(t *testing.T, path, want string, mode os.FileMode) {
	t.Helper()
	got, err := os.ReadFile(path)
	if err != nil || string(got) != want {
		t.Fatalf("configuration bytes changed at %s (read error: %v)", filepath.Base(path), err)
	}
	info, err := os.Stat(path)
	if err != nil || info.Mode().Perm() != mode {
		t.Fatalf("configuration mode changed at %s (stat error: %v)", filepath.Base(path), err)
	}
}

func TestInstallDockerScriptKeepsExistingDeployment(t *testing.T) {
	workDir := t.TempDir()
	runInstallDockerScript(t, workDir)
	compose := filepath.Join(workDir, "docker-compose.yml")
	env := filepath.Join(workDir, ".env")
	backup := compose + ".backup"
	// Model a real operator's bind mounts, image pin, port and private settings.
	custom := "services:\n  pulse:\n    image: example/pulse:fixed\n    ports: ['127.0.0.1:8765:7655']\n    volumes: ['./existing-state:/data']\n"
	private := "PULSE_IMAGE=example/pulse:fixed\nPULSE_PORT=8765\nSYNTHETIC_SECRET=fixture-only\n"
	for path, value := range map[string]string{compose: custom, env: private, backup: "older recovery copy\n"} {
		if err := os.WriteFile(path, []byte(value), 0o600); err != nil {
			t.Fatal(err)
		}
		if err := os.Chmod(path, 0o600); err != nil {
			t.Fatal(err)
		}
	}
	before, err := os.Stat(compose)
	if err != nil {
		t.Fatal(err)
	}
	if err := os.Remove(filepath.Join(workDir, "docker-calls")); err != nil {
		t.Fatal(err)
	}
	out, resultErr := runInstallDockerScriptResult(t, workDir)
	assertDockerSetupBytes(t, compose, custom, 0o600)
	assertDockerSetupBytes(t, env, private, 0o600)
	assertDockerSetupBytes(t, backup, "older recovery copy\n", 0o600)
	after, err := os.Stat(compose)
	if err != nil || !os.SameFile(before, after) {
		t.Fatal("existing Compose inode was replaced")
	}
	if resultErr == nil {
		t.Fatal("repeated setup accepted an existing deployment")
	}
	for _, message := range []string{"only prepares a new deployment", "existing Compose configuration", "left unchanged"} {
		if !strings.Contains(out, message) {
			t.Errorf("missing actionable preservation message %q", message)
		}
	}
	if strings.Contains(out, "SYNTHETIC_SECRET") || strings.Contains(out, "fixture-only") || strings.Contains(out, "Installation Complete") {
		t.Fatal("refusal leaked configuration or claimed installation")
	}
	if _, err := os.Stat(filepath.Join(workDir, "docker-calls")); !os.IsNotExist(err) {
		t.Fatal("refused setup called Docker")
	}
}

func TestInstallDockerScriptRefusesAllExistingComposeNames(t *testing.T) {
	for _, name := range []string{"compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"} {
		t.Run(name, func(t *testing.T) {
			workDir := t.TempDir()
			path := filepath.Join(workDir, name)
			if err := os.WriteFile(path, []byte("existing operator configuration\n"), 0o640); err != nil {
				t.Fatal(err)
			}
			if _, err := runInstallDockerScriptResult(t, workDir); err == nil {
				t.Fatal("setup accepted an existing Compose file")
			}
			assertDockerSetupBytes(t, path, "existing operator configuration\n", 0o640)
			for _, output := range []string{".env", "docker-calls", "docker-compose.yml.backup"} {
				if _, err := os.Lstat(filepath.Join(workDir, output)); !os.IsNotExist(err) {
					t.Fatalf("refused setup created %s", output)
				}
			}
			if name != "docker-compose.yml" {
				if _, err := os.Lstat(filepath.Join(workDir, "docker-compose.yml")); !os.IsNotExist(err) {
					t.Fatal("setup created a competing Compose file")
				}
			}
		})
	}
}

func TestInstallDockerScriptRefusesUnsafeOutputPaths(t *testing.T) {
	for _, output := range []string{"docker-compose.yml", ".env"} {
		for _, shape := range []string{"symlink", "dangling-symlink", "directory", "fifo"} {
			t.Run(output+"/"+shape, func(t *testing.T) {
				workDir := t.TempDir()
				target := filepath.Join(workDir, "untouched-target")
				path := filepath.Join(workDir, output)
				if shape != "dangling-symlink" {
					if err := os.WriteFile(target, []byte("unrelated private bytes\n"), 0o600); err != nil {
						t.Fatal(err)
					}
				}
				switch shape {
				case "symlink", "dangling-symlink":
					if err := os.Symlink(target, path); err != nil {
						t.Skipf("symlink fixture unavailable: %v", err)
					}
				case "directory":
					if err := os.Mkdir(path, 0o700); err != nil {
						t.Fatal(err)
					}
				case "fifo":
					if _, err := exec.LookPath("mkfifo"); err != nil {
						t.Skip("mkfifo fixture unavailable")
					}
					if err := exec.Command("mkfifo", path).Run(); err != nil {
						t.Fatal(err)
					}
				}
				before, err := os.Lstat(path)
				if err != nil {
					t.Fatal(err)
				}
				if _, err := runInstallDockerScriptResult(t, workDir); err == nil {
					t.Fatal("setup accepted an unsafe output path")
				}
				after, err := os.Lstat(path)
				if err != nil || !os.SameFile(before, after) || after.Mode() != before.Mode() {
					t.Fatal("unsafe output path changed")
				}
				if shape == "dangling-symlink" {
					if _, err := os.Lstat(target); !os.IsNotExist(err) {
						t.Fatal("setup wrote through a dangling symlink")
					}
				} else {
					assertDockerSetupBytes(t, target, "unrelated private bytes\n", 0o600)
				}
				for _, absent := range []string{"docker-calls", "docker-compose.yml.backup"} {
					if _, err := os.Lstat(filepath.Join(workDir, absent)); !os.IsNotExist(err) {
						t.Fatalf("refused setup created %s", absent)
					}
				}
				other := ".env"
				if output == ".env" {
					other = "docker-compose.yml"
				}
				if _, err := os.Lstat(filepath.Join(workDir, other)); !os.IsNotExist(err) {
					t.Fatal("unsafe path admission partially generated configuration")
				}
			})
		}
	}
}

func TestInstallDockerScriptPreservesRegularEnvironment(t *testing.T) {
	workDir := t.TempDir()
	env := filepath.Join(workDir, ".env")
	if err := os.WriteFile(env, []byte("PULSE_IMAGE=example/pulse:operator-pin\n"), 0o600); err != nil {
		t.Fatal(err)
	}
	runInstallDockerScript(t, workDir)
	assertDockerSetupBytes(t, env, "PULSE_IMAGE=example/pulse:operator-pin\n", 0o600)
	info, err := os.Stat(filepath.Join(workDir, "docker-compose.yml"))
	if err != nil || info.Mode().Perm() != 0o600 {
		t.Fatal("new Compose output is not private")
	}
}

func TestInstallDockerScriptDoesNotClobberRacingCompose(t *testing.T) {
	workDir := t.TempDir()
	out, err := runInstallDockerScriptResult(t, workDir, "TEST_RACE_COMPOSE=true")
	if err == nil || strings.Contains(out, "Configuration prepared") {
		t.Fatal("setup claimed success over a competing output")
	}
	assertDockerSetupBytes(t, filepath.Join(workDir, "docker-compose.yml"), "racing owner configuration\n", 0o600)
	if _, err := os.Lstat(filepath.Join(workDir, "docker-compose.yml.backup")); !os.IsNotExist(err) {
		t.Fatal("racing setup replaced a backup")
	}
	if _, err := os.Lstat(filepath.Join(workDir, ".env")); !os.IsNotExist(err) {
		t.Fatal("racing setup continued after the Compose collision")
	}
}

func TestInstallDockerScriptReportsPreparationNotInstallation(t *testing.T) {
	workDir := t.TempDir()
	out, err := runInstallDockerScriptResult(t, workDir)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(out, "Configuration prepared; Pulse has not been started") || strings.Contains(out, "Installation Complete") {
		t.Fatal("generator claimed an unexecuted installation")
	}
	for _, output := range []string{"docker-compose.yml", ".env"} {
		info, err := os.Stat(filepath.Join(workDir, output))
		if err != nil || info.Mode().Perm() != 0o600 {
			t.Fatalf("new %s output is not private", output)
		}
	}
	calls, err := os.ReadFile(filepath.Join(workDir, "docker-calls"))
	if err != nil || string(calls) != "compose version\n" {
		t.Fatal("generator called a Docker operation other than compose version")
	}
}