fix(ci): enforce the shared Wails version everywhere

Problem: Local production builds and contributor setup could still bypass the shared Wails pin, so the old CLI/library skew remained possible even while the workflow-only guard passed. Root cause: The guard inspected only two workflow files, prod_test checked command presence instead of the installed CLI version, and the desktop guide recommended @latest. Fix: Add a make-based pinned installer, make prod_test repair and verify version mismatches, reject repository-wide hard-coded Wails installs, move the maintenance guidance out of the cache-stable prompt, and cover each drift path with regression tests. Verification: - make lint - bash scripts/release-workflows.test.sh - make wails-install installs v2.13.0 in an isolated GOBIN - wails build -platform darwin/arm64 -clean -skipbindings -nopackage Co-authored-by: SivanCola <[email protected]>
2026-11-07 10:45:59 -10:00 · 2026-08-10 03:06:01 +08:00
1 parent eee45d2a35
commit 641f7993fd
@@ -493,7 +493,9 @@ jobs:
        run: go run ./tools/repolint

      - name: wails version pin
-        run: bash scripts/check-wails-pin.sh
+        run: |
+          bash scripts/check-wails-pin.sh
+          bash scripts/check-wails-pin.test.sh

      # `make lint-install` reads the same file, so a local run and this job
      # cannot drift onto different linter versions.
@@ -8,6 +8,8 @@ everything you need to get started.
 - **Go 1.25+** — the project targets the latest stable Go release
 - **Git** — for version control
 - **Node.js** (optional) — only if you work on the desktop app (`desktop/`)
+- **Wails CLI** (desktop only) — run `make wails-install` so the CLI matches
+  `desktop/go.mod`

 ## Getting started

@@ -8,8 +8,9 @@ LDFLAGS := -s -w \
 GOEXE := $(shell go env GOEXE)
 # One pin for the Makefile and the CI lint job; see .github/workflows/ci.yml.
 GOLANGCI_VERSION := $(shell cat .golangci-version)
+WAILS_VERSION := $(shell tr -d '[:space:]' < .wails-version)

-.PHONY: build vet fmt lint lint-go lint-install lint-cross lint-update test desktop-test desktop-test-short desktop-test-times sdk-test sdk-test-race hooks cross clean
+.PHONY: build vet fmt lint lint-go lint-install lint-cross lint-update wails-install test desktop-test desktop-test-short desktop-test-times sdk-test sdk-test-race hooks cross clean

 build:
 	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/reasonix$(GOEXE) ./cmd/reasonix
@@ -27,6 +28,7 @@ fmt:
 lint: lint-go
 	go run ./tools/repolint
 	bash scripts/check-wails-pin.sh
+	bash scripts/check-wails-pin.test.sh

 lint-go:
 	@command -v golangci-lint >/dev/null || { echo "golangci-lint not installed; run: make lint-install"; exit 1; }
@@ -42,6 +44,9 @@ lint-install:
 lint-update:
 	go run ./tools/repolint -update

+wails-install:
+	go install github.com/wailsapp/wails/v2/cmd/wails@$(WAILS_VERSION)
+
 # Linting one GOOS leaves every //go:build windows and darwin file unchecked.
 lint-cross:
 	@for t in "linux ." "darwin ." "windows ." "linux desktop" "windows desktop"; do \
@@ -70,12 +70,6 @@ make lint                           # golangci-lint at CI's pin + repolint
 go test ./internal/tool/builtin/ ./internal/boot/  # catches tool/boot test breaks
 ```

-`make lint` also asserts the Wails pin: the CLI version lives in
-`.wails-version`, read by the Makefile and all three workflows, because
-`wails dev` rewrites `desktop/go.mod` down to whatever CLI is installed and
-Dependabot bumps the library without seeing the CLI. Drift in either direction
-fails the check.
-
 `make lint` runs both gates CI runs, at the version in `.golangci-version`;
 `make lint-install` installs it. Do not skip it: a `modernize` finding never
 shows up in `go vet`, and the CI round trip that catches it instead costs ten
@@ -35,7 +35,8 @@ vet / test ./...` skip this directory, while the import path stays under

 - Go (matches the parent module).
 - Node + **pnpm** (`npm i -g pnpm`).
- Wails CLI: `go install github.com/wailsapp/wails/v2/cmd/wails@latest`
+- Wails CLI matching the library: run `make wails-install` from the repository
+  root. The target reads the shared `.wails-version` pin.
 - Platform webview libs: macOS ships WebKit; Windows needs the Edge **WebView2**
  runtime; Linux needs `libgtk-3-dev` plus WebKitGTK. The default build links
  against **WebKitGTK 4.0**; distros that only ship **4.1** (Fedora 40+, Ubuntu
@@ -63,6 +63,10 @@ go_bin_dir() {
 	printf '%s' "$gobin"
 }

+installed_wails_version() {
+	wails version 2>/dev/null | awk 'match($0, /v[0-9]+\.[0-9]+\.[0-9]+/) { print substr($0, RSTART, RLENGTH); exit }'
+}
+
 sanitize_semver_id() {
 	local value="$1"
 	value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^0-9A-Za-z]+/-/g; s/^-+//; s/-+$//; s/-+/-/g')"
@@ -127,9 +131,11 @@ default_version() {
 }

 install_or_check_tools() {
-	local os install_tools
+	local os install_tools wails_pin wails_version
 	os="${1%/*}"
 	install_tools="${PROD_TEST_INSTALL_TOOLS:-1}"
+	wails_pin="$(tr -d '[:space:]' < "$ROOT/.wails-version")"
+	[[ -n "$wails_pin" ]] || fail ".wails-version is empty"

 	need_cmd git
 	need_cmd go
@@ -151,14 +157,21 @@ install_or_check_tools() {
 		fi
 	fi

-	if ! command -v wails >/dev/null 2>&1; then
+	wails_version=""
+	if command -v wails >/dev/null 2>&1; then
+		wails_version="$(installed_wails_version)"
+	fi
+	if [[ "$wails_version" != "$wails_pin" ]]; then
 		if [[ "$install_tools" == "1" ]]; then
-			echo "==> installing Wails CLI"
-			go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0
+			echo "==> installing Wails CLI $wails_pin (found ${wails_version:-none})"
+			go install "github.com/wailsapp/wails/v2/cmd/wails@$wails_pin"
+			hash -r
 		else
-			fail "wails not found. Install with: go install github.com/wailsapp/wails/v2/cmd/[email protected]"
+			fail "Wails CLI ${wails_version:-not found} does not match .wails-version $wails_pin. Run: make wails-install"
 		fi
 	fi
+	wails_version="$(installed_wails_version)"
+	[[ "$wails_version" == "$wails_pin" ]] || fail "Wails CLI $wails_version does not match .wails-version $wails_pin after installation"

 	case "$os" in
 	darwin)
@@ -8,7 +8,7 @@
 # upgrade. One pin, read by everyone, and this check to prove it held.
 set -euo pipefail

-root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+root="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 pin="$(tr -d '[:space:]' < "$root/.wails-version")"
 mod="$(awk '/github.com\/wailsapp\/wails\/v2 v/ {print $2; exit}' "$root/desktop/go.mod")"

@@ -42,4 +42,29 @@ for workflow in "$root"/.github/workflows/ci.yml "$root"/.github/workflows/relea
  fi
 done

+# The workflows are not the only way developers build a release. Keep local
+# packaging and setup docs from bypassing the shared pin too. The escaped dots
+# keep this regex from matching its own source.
+hard_coded="$(git -C "$root" grep -nE 'github\.com/wailsapp/wails/v2/cmd/wails@(v[0-9]|latest)' -- . || true)"
+if [[ -n "$hard_coded" ]]; then
+  cat >&2 <<MSG
+check-wails-pin: Wails CLI installs must read .wails-version; found:
+$hard_coded
+MSG
+  exit 1
+fi
+
+grep -Fq 'github.com/wailsapp/wails/v2/cmd/wails@$(WAILS_VERSION)' "$root/Makefile" || {
+  echo "check-wails-pin: make wails-install must install WAILS_VERSION" >&2
+  exit 1
+}
+grep -Fq 'make wails-install' "$root/desktop/README.md" || {
+  echo "check-wails-pin: desktop/README.md must direct developers to make wails-install" >&2
+  exit 1
+}
+grep -Fq 'wails version' "$root/prod_test" || {
+  echo "check-wails-pin: prod_test must verify the installed Wails CLI version" >&2
+  exit 1
+}
+
 echo "check-wails-pin: CLI and library both pinned at $pin"
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+scratch="$(mktemp -d)"
+trap 'rm -rf "$scratch"' EXIT
+wails_module="github.com/wailsapp/wails/v2/cmd/wails"
+
+make_fixture() {
+  local name="$1"
+  local fixture="$scratch/$name"
+  mkdir -p "$fixture/.github/workflows" "$fixture/desktop" "$fixture/scripts"
+  cp "$root/scripts/check-wails-pin.sh" "$fixture/scripts/check-wails-pin.sh"
+  printf 'v2.13.0\n' > "$fixture/.wails-version"
+  printf 'github.com/wailsapp/wails/v2 v2.13.0\n' > "$fixture/desktop/go.mod"
+  printf 'run: go install "%s@$(cat "$GITHUB_WORKSPACE/.wails-version")"\n' "$wails_module" > "$fixture/.github/workflows/ci.yml"
+  cp "$fixture/.github/workflows/ci.yml" "$fixture/.github/workflows/release-desktop.yml"
+  printf 'go install "%s@$wails_pin"\nwails version\n' "$wails_module" > "$fixture/prod_test"
+  printf 'Run `make wails-install`.\n' > "$fixture/desktop/README.md"
+  printf 'WAILS_VERSION := v2.13.0\nwails-install:\n\tgo install %s@$(WAILS_VERSION)\n' "$wails_module" > "$fixture/Makefile"
+  git -C "$fixture" init -q
+  git -C "$fixture" add .
+  printf '%s' "$fixture"
+}
+
+expect_failure() {
+  local fixture="$1"
+  local expected="$2"
+  local output
+  if output="$(bash "$fixture/scripts/check-wails-pin.sh" "$fixture" 2>&1)"; then
+    echo "check-wails-pin test: expected failure containing: $expected" >&2
+    exit 1
+  fi
+  grep -Fq "$expected" <<<"$output" || {
+    echo "check-wails-pin test: missing failure text: $expected" >&2
+    echo "$output" >&2
+    exit 1
+  }
+}
+
+fixture="$(make_fixture valid)"
+bash "$fixture/scripts/check-wails-pin.sh" "$fixture" >/dev/null
+
+fixture="$(make_fixture prod-test-hard-code)"
+printf 'go install %[email protected]\n' "$wails_module" >> "$fixture/prod_test"
+git -C "$fixture" add prod_test
+expect_failure "$fixture" 'prod_test:'
+
+fixture="$(make_fixture docs-latest)"
+printf 'go install %s@latest\n' "$wails_module" >> "$fixture/desktop/README.md"
+git -C "$fixture" add desktop/README.md
+expect_failure "$fixture" 'desktop/README.md:'
+
+fixture="$(make_fixture module-drift)"
+printf 'github.com/wailsapp/wails/v2 v2.14.0\n' > "$fixture/desktop/go.mod"
+expect_failure "$fixture" 'version drift'
+
+fixture="$(make_fixture workflow-cwd)"
+printf 'run: go install "%s@$(cat .wails-version)"\n' "$wails_module" > "$fixture/.github/workflows/ci.yml"
+expect_failure "$fixture" "reads .wails-version relative to the job's working directory"
+
+fake_bin="$scratch/fake-bin"
+mkdir -p "$fake_bin"
+printf '#!/usr/bin/env bash\nprintf "v2.12.0\\n"\n' > "$fake_bin/wails"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$fake_bin/pnpm"
+chmod +x "$fake_bin/wails" "$fake_bin/pnpm"
+if output="$(GOBIN="$fake_bin" PATH="$fake_bin:$PATH" PROD_TEST_INSTALL_TOOLS=0 PROD_TEST_FAST=1 DESKTOP_BUILD_SKIP_DMG=1 PROD_TEST_OPEN_DIST=0 "$root/prod_test" darwin/arm64 2>&1)"; then
+  echo "check-wails-pin test: prod_test accepted a mismatched installed Wails CLI" >&2
+  exit 1
+fi
+grep -Fq 'Wails CLI v2.12.0 does not match .wails-version v2.13.0' <<<"$output" || {
+  echo "check-wails-pin test: prod_test did not report the installed-version mismatch" >&2
+  echo "$output" >&2
+  exit 1
+}
+
+echo "check-wails-pin tests: ok"