Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

The upgrade contract: an existing install must still be seen

Gauthier Piarrette3f5987563ebe
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5525e96..d7d4b02 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -20,6 +20,8 @@ jobs:
run: swift build
- name: Unit tests
run: swift test
+ - name: Upgrade smoke (an existing install is still seen; headless)
+ run: Scripts/upgrade-smoke.sh
- name: Validate recipes against the CLI (from highball-db)
run: |
git clone --depth 1 https://github.com/gauthierpiarrette/highball-db.git ../highball-db
diff --git a/Scripts/release.sh b/Scripts/release.sh
index aec7be8..82dd5e8 100755
--- a/Scripts/release.sh
+++ b/Scripts/release.sh
@@ -27,6 +27,22 @@ then
sleep 5
fi
+# Upgrade regressions (the issue #21 class: 0.8.0 hid an existing user's environment) ship via
+# UI and state changes, and every first-run check starts from an empty home, so a release wants
+# a recent Scripts/upgrade-smoke.sh result too. Same rule as above: warn, don't block.
+if ! python3 - <<'PY' 2>/dev/null
+import json, sys, time
+d = json.load(open("private/upgrade-smoke/latest.json"))
+sys.exit(0 if d.get("passed") and time.time() - d.get("epoch", 0) < 14*86400 else 1)
+PY
+then
+ echo "" >&2
+ echo "WARNING: no passing upgrade-smoke result from the last 14 days." >&2
+ echo " Run Scripts/upgrade-smoke.sh --screen — an existing install going invisible ships silently without it." >&2
+ echo " Continuing in 5s…" >&2
+ sleep 5
+fi
+
Scripts/make-app.sh release "$VERSION"
ZIP="dist/Highball-$VERSION.zip"
ditto -c -k --keepParent dist/Highball.app "$ZIP"
diff --git a/Scripts/upgrade-smoke.sh b/Scripts/upgrade-smoke.sh
new file mode 100755
index 0000000..cd523af
--- /dev/null
+++ b/Scripts/upgrade-smoke.sh
@@ -0,0 +1,106 @@
+#!/bin/zsh
+# Upgrade smoke: this build must still see the install the previous build left behind.
+#
+# Seeds a home the way a real user's looks after 0.8: an environment that is NOT the default
+# name ("CS"), holding an installed Steam game, written in the previous release's on-disk
+# shape. Then checks, through the CLI, that the environment lists as real (not DAMAGED).
+# With --screen it also launches the app on that home and requires a window within 20 s,
+# saving a capture to look at. Records private/upgrade-smoke/latest.json, which
+# Scripts/release.sh reads (warn-only, like render-smoke).
+#
+# Why: the 0.8.0 regression (#21) was invisible to every existing check because each one
+# starts from an empty home. Unit tests cover the same contract headlessly
+# (Tests/HighballKitTests/UpgradeInstallTests.swift); this is the end-to-end echo of it.
+#
+# Usage: Scripts/upgrade-smoke.sh [--screen]
+# Env: UPGRADE_SMOKE_HOME (default: $TMPDIR/hb-upgrade-smoke, recreated)
+# UPGRADE_SMOKE_ENGINE (optional: path of an installed engine dir to link in, so the
+# app has an engine and skips onboarding; the CLI part never needs it)
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+HB="$ROOT/.build/debug/highball"
+[ -x "$HB" ] || swift build --package-path "$ROOT" >/dev/null
+SCREEN=0; [ "${1:-}" = "--screen" ] && SCREEN=1
+H="${UPGRADE_SMOKE_HOME:-${TMPDIR:-/tmp}/hb-upgrade-smoke}"
+rm -rf "$H"; mkdir -p "$H/bottles/CS/drive_c/windows"
+STEAM="$H/bottles/CS/drive_c/Program Files (x86)/Steam"
+mkdir -p "$STEAM/steamapps/common/Counter-Strike Source"
+: > "$STEAM/steam.exe"
+cat > "$STEAM/steamapps/appmanifest_240.acf" <<'ACF'
+"AppState"
+{
+ "appid" "240"
+ "name" "Counter-Strike: Source"
+ "installdir" "Counter-Strike Source"
+ "StateFlags" "4"
+ "SizeOnDisk" "5000000000"
+}
+ACF
+# The shape 0.8.0 writes (every key), kept in sync with UpgradeInstallTests.bottleJSON_0_8.
+cat > "$H/bottles/CS/bottle.json" <<'JSON'
+{
+ "advertiseAVX" : false,
+ "commandIsControl" : true,
+ "commandIsControlSynced" : true,
+ "created" : "2026-08-23T16:45:00Z",
+ "dllOverrides" : "",
+ "dpiScale" : 96,
+ "dxvkAppConfig" : {},
+ "dxvkAsync" : false,
+ "engineID" : "x64-sikarugir10.0_6-r1",
+ "environment" : {},
+ "formatVersion" : 3,
+ "fpsCap" : 0,
+ "metalHUD" : false,
+ "name" : "CS",
+ "pins" : [],
+ "recipes" : ["steam"],
+ "renderer" : "dxmt",
+ "rendererExplicit" : false,
+ "sync" : "msync",
+ "windowsVersion" : "win10"
+}
+JSON
+if [ -n "${UPGRADE_SMOKE_ENGINE:-}" ] && [ -d "$UPGRADE_SMOKE_ENGINE" ]; then
+ mkdir -p "$H/engines"; ln -s "$UPGRADE_SMOKE_ENGINE" "$H/engines/$(basename "$UPGRADE_SMOKE_ENGINE")"
+fi
+export HIGHBALL_HOME="$H"
+
+fail() { echo "UPGRADE SMOKE FAILED: $*" >&2; record false; exit 1; }
+record() {
+ mkdir -p "$ROOT/private/upgrade-smoke"
+ python3 - "$1" "$SCREEN" "$ROOT/private/upgrade-smoke/latest.json" <<'PY'
+import json, sys, time
+passed, screen, out = sys.argv[1] == "true", sys.argv[2] == "1", sys.argv[3]
+json.dump({"passed": passed, "epoch": int(time.time()), "date": time.strftime("%Y-%m-%d"),
+ "screen": screen}, open(out, "w"), indent=2)
+PY
+}
+
+echo "== CLI: the existing environment is seen"
+out="$("$HB" bottle list 2>&1)"; echo "$out"
+echo "$out" | grep -q '^CS' || fail "environment 'CS' not listed"
+echo "$out" | grep -q 'DAMAGED' && fail "environment reported as damaged"
+
+if [ "$SCREEN" = 1 ]; then
+ echo "== app: launches on that home and shows a window"
+ APP="$ROOT/dist/Highball.app/Contents/MacOS/Highball"
+ [ -x "$APP" ] || "$ROOT/Scripts/make-app.sh" >/dev/null
+ pkill -f "dist/Highball.app/Contents/MacOS/Highball" 2>/dev/null || true; sleep 1
+ "$APP" >/dev/null 2>&1 &
+ sleep 1; pid=$(pgrep -n -f "dist/Highball.app/Contents/MacOS/Highball" || true)
+ [ -n "$pid" ] || fail "app did not start"
+ n=0; win=0
+ until [ "$win" -ge 1 ] || [ $n -ge 20 ]; do
+ sleep 1; n=$((n+1))
+ win=$(osascript -e "tell application \"System Events\" to count windows of (first process whose unix id is $pid)" 2>/dev/null || echo 0)
+ done
+ [ "$win" -ge 1 ] || { kill "$pid" 2>/dev/null || true; fail "no window after 20 s"; }
+ sleep 4
+ screencapture -x "$ROOT/private/upgrade-smoke/library.png" 2>/dev/null || true
+ kill "$pid" 2>/dev/null || true
+ echo " window appeared; capture at private/upgrade-smoke/library.png (look: the game should show, not 'prepare an environment')"
+fi
+
+record true
+echo "UPGRADE SMOKE PASSED"
diff --git a/Tests/HighballKitTests/UpgradeInstallTests.swift b/Tests/HighballKitTests/UpgradeInstallTests.swift
new file mode 100644
index 0000000..3cf0677
--- /dev/null
+++ b/Tests/HighballKitTests/UpgradeInstallTests.swift
@@ -0,0 +1,121 @@
+import XCTest
+@testable import HighballKit
+
+/// The upgrade contract (issue #21, 0.8.0): a build must see the install the previous build
+/// left behind. An environment that is not the default name, holding an installed Steam game,
+/// written in the on-disk shape of the previous release, has to list as a real (not damaged)
+/// environment, its game has to be found, and the library has to show it. Every first-run
+/// script wipes the home, so this is the one place the *existing user* is the subject.
+final class UpgradeInstallTests: XCTestCase {
+ private var home: URL!
+ private var paths: HighballPaths!
+
+ override func setUp() {
+ home = FileManager.default.temporaryDirectory.appending(path: "hb-upgrade-\(UUID().uuidString)")
+ paths = HighballPaths(home: home)
+ try? FileManager.default.createDirectory(at: paths.bottles, withIntermediateDirectories: true)
+ }
+ override func tearDown() { try? FileManager.default.removeItem(at: home) }
+
+ /// The exact shape 0.8.0 writes for a bottle (every key it emits), frozen. If a decoder
+ /// change ever refuses this, every 0.8 user's environment turns "damaged" on update.
+ static let bottleJSON_0_8 = """
+ {
+ "advertiseAVX" : false,
+ "commandIsControl" : true,
+ "commandIsControlSynced" : true,
+ "created" : "2026-08-23T16:45:00Z",
+ "dllOverrides" : "",
+ "dpiScale" : 96,
+ "dxvkAppConfig" : {},
+ "dxvkAsync" : false,
+ "engineID" : "x64-sikarugir10.0_6-r1",
+ "environment" : {},
+ "formatVersion" : 3,
+ "fpsCap" : 0,
+ "metalHUD" : false,
+ "name" : "CS",
+ "pins" : [],
+ "recipes" : ["steam"],
+ "renderer" : "dxmt",
+ "rendererExplicit" : false,
+ "sync" : "msync",
+ "windowsVersion" : "win10"
+ }
+ """
+
+ /// A 0.7-era install: `gin.json`, format 1, only the keys that version wrote.
+ static let ginJSON_0_7 = """
+ {"formatVersion":1,"name":"CS","engineID":"x64-sikarugir10.0_6-r0","renderer":"dxmt","recipes":["steam"]}
+ """
+
+ private func seed(name: String, settingsFile: String, json: String, appid: Int = 240,
+ game: String = "Counter-Strike: Source") throws -> URL {
+ let bottle = paths.bottles.appending(path: name)
+ let steam = bottle.appending(path: "drive_c/Program Files (x86)/Steam")
+ let steamapps = steam.appending(path: "steamapps")
+ try FileManager.default.createDirectory(at: steamapps.appending(path: "common/\(game)"), withIntermediateDirectories: true)
+ try FileManager.default.createDirectory(at: bottle.appending(path: "drive_c/windows"), withIntermediateDirectories: true)
+ try Data().write(to: steam.appending(path: "steam.exe"))
+ try json.write(to: bottle.appending(path: settingsFile), atomically: true, encoding: .utf8)
+ let acf = """
+ "AppState"
+ {
+ \t"appid"\t\t"\(appid)"
+ \t"name"\t\t"\(game)"
+ \t"installdir"\t\t"\(game)"
+ \t"StateFlags"\t\t"4"
+ \t"SizeOnDisk"\t\t"5000000000"
+ }
+ """
+ try acf.write(to: steamapps.appending(path: "appmanifest_\(appid).acf"), atomically: true, encoding: .utf8)
+ return bottle
+ }
+
+ private func assertSeen(_ file: StaticString = #filePath, line: UInt = #line) throws {
+ let store = BottleStore(paths: paths)
+ let bottles = try store.list()
+ XCTAssertEqual(bottles.map(\.name), ["CS"], "the environment lists under its own name", file: file, line: line)
+ XCTAssertTrue(try store.damaged().isEmpty, "and is not reported as damaged", file: file, line: line)
+ guard let cs = bottles.first else { return }
+ let games = SteamLibrary.games(in: cs)
+ XCTAssertEqual(games.map(\.appid), [240], "its installed game is found", file: file, line: line)
+ XCTAssertTrue(games.first?.isReady == true, file: file, line: line)
+ let items = LibraryIndex.build(bottles: bottles, steamByBottle: ["CS": games], epicOwned: [], epicInstalls: [:])
+ XCTAssertEqual(items.count, 1, "and the library shows it", file: file, line: line)
+ XCTAssertEqual(items.first?.title, "Counter-Strike: Source", file: file, line: line)
+ XCTAssertTrue(items.first?.installed == true, file: file, line: line)
+ }
+
+ func testAn08InstallIsStillSeen() throws {
+ _ = try seed(name: "CS", settingsFile: "bottle.json", json: Self.bottleJSON_0_8)
+ try assertSeen()
+ }
+
+ func testA07InstallIsStillSeen() throws {
+ _ = try seed(name: "CS", settingsFile: "gin.json", json: Self.ginJSON_0_7)
+ try assertSeen()
+ }
+
+ /// What this build writes today must read back tomorrow: a round trip through the real
+ /// encoder, so a new field with no default cannot slip in unnoticed.
+ func testTodaysEncoderOutputReadsBack() throws {
+ let settings = BottleSettings(name: "CS", engineID: "x64-sikarugir10.0_6-r1")
+ let data = try JSONEncoder.highball.encode(settings)
+ let bottle = try seed(name: "CS", settingsFile: "bottle.json", json: String(decoding: data, as: UTF8.self))
+ XCTAssertNoThrow(try Bottle.load(bottle))
+ try assertSeen()
+ }
+
+ /// The failure mode from the field: a settings file that cannot be read must surface as a
+ /// damaged environment, never silently vanish (the library then points at Troubleshooting
+ /// instead of telling the user to prepare a new environment).
+ func testAnUnreadableSettingsFileIsReportedNotHidden() throws {
+ _ = try seed(name: "CS", settingsFile: "bottle.json", json: "{ not json")
+ let store = BottleStore(paths: paths)
+ XCTAssertTrue(try store.list().isEmpty)
+ let damaged = try store.damaged()
+ XCTAssertEqual(damaged.map(\.name), ["CS"])
+ XCTAssertTrue(damaged.first?.reason.contains("bottle.json") == true, "names the settings file: \(damaged.first?.reason ?? "")")
+ }
+}