Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
The upgrade contract: an existing install must still be seen
Gauthier Piarrette3f5987563ebe
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 5525e96..d7d4b02 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -20,6 +20,8 @@ jobs:run: swift build- name: Unit testsrun: 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-dbdiff --git a/Scripts/release.sh b/Scripts/release.shindex aec7be8..82dd5e8 100755--- a/Scripts/release.sh+++ b/Scripts/release.sh@@ -27,6 +27,22 @@ thensleep 5fi+# 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.shnew file mode 100755index 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.swiftnew file mode 100644index 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 ?? "")")+ }+}