From 04e17ecabfd9639dd7bf2e0af1e91c054ebe5ece Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 20:19:37 +0000 Subject: [PATCH 01/21] Bump version to 3.1.0 Branch-opening commit for the 3.1.0 integration target. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011hqxFfwPYBmRRqt4rroHKi --- VERSION.TXT | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION.TXT b/VERSION.TXT index 4a36342f..fd2a0186 100644 --- a/VERSION.TXT +++ b/VERSION.TXT @@ -1 +1 @@ -3.0.0 +3.1.0 From aa49e646cf87e2271ceda4a0e9ec6e14db0b9225 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 11:00:24 +0000 Subject: [PATCH 02/21] Sign release builds with Azure Artifact Signing when configured release.yml signs SmartCitizen.exe (and the bundled unp4k/unforge), the installer and the portable .exe files, then zips the portable folder again with the new build_exe.py --portable --zip-only. Every signing step is skipped until the AZURE_SIGNING_ACCOUNT repository variable is set, so releases keep working unsigned until the Azure account is ready. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011hqxFg4JmXaXwTRySyJEQW --- .github/workflows/release.yml | 70 +++++++++++++++++++++++++++ CLAUDE.md | 2 + scripts/build/build_exe.py | 91 +++++++++++++++++++++++------------ 3 files changed, 131 insertions(+), 32 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index acffd4f1..e10ba79b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -35,11 +35,26 @@ jobs: name: Build & Release runs-on: windows-latest timeout-minutes: 30 + # A fixed environment name gives the Azure federated credential one + # subject to trust (repo:Osiris-DevWorks/smart-citizen:environment:release) + # whichever of the three triggers started the run. + environment: release permissions: # Required for: softprops/action-gh-release (create release + upload # assets) AND `git push origin ` (auto-tag the merge commit on # branch-push trigger). contents: write + # Required for the Azure OIDC login that code signing uses. + id-token: write + # Code signing (Azure Artifact Signing) runs only once the + # AZURE_SIGNING_ACCOUNT repository variable is set. Until then every + # signing step is skipped and the release ships unsigned, as before. + # Repository variables it reads (none are secret): AZURE_CLIENT_ID, + # AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_SIGNING_ENDPOINT + # (e.g. https://weu.codesigning.azure.net/), AZURE_SIGNING_ACCOUNT, + # AZURE_SIGNING_PROFILE. + env: + SIGN: ${{ vars.AZURE_SIGNING_ACCOUNT != '' }} steps: - name: Checkout (at tag, branch HEAD, or dispatch input) @@ -154,6 +169,28 @@ jobs: if: steps.gate.outputs.skip == 'false' run: python scripts/build/build_exe.py + - name: Azure login (code signing) + if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' + uses: azure/login@v2 + with: + client-id: ${{ vars.AZURE_CLIENT_ID }} + tenant-id: ${{ vars.AZURE_TENANT_ID }} + subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} + + - name: Sign program files (SmartCitizen.exe, unp4k, unforge) + if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' + uses: azure/artifact-signing-action@v2 + with: + endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }} + signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT }} + certificate-profile-name: ${{ vars.AZURE_SIGNING_PROFILE }} + files-folder: ${{ github.workspace }}\dist\SmartCitizen + files-folder-filter: exe + files-folder-recurse: true + file-digest: SHA256 + timestamp-rfc3161: http://timestamp.acs.microsoft.com + timestamp-digest: SHA256 + - name: Install Inno Setup if: steps.gate.outputs.skip == 'false' shell: pwsh @@ -174,6 +211,20 @@ jobs: exit $LASTEXITCODE } + - name: Sign installer + if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' + uses: azure/artifact-signing-action@v2 + with: + endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }} + signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT }} + certificate-profile-name: ${{ vars.AZURE_SIGNING_PROFILE }} + files-folder: ${{ github.workspace }}\dist + files-folder-filter: exe + files-folder-recurse: false + file-digest: SHA256 + timestamp-rfc3161: http://timestamp.acs.microsoft.com + timestamp-digest: SHA256 + - name: Stash standard installer before portable rebuild # build_exe.py unconditionally rmtrees `dist/` at the start of # every run (including --portable). Without stashing, the @@ -198,6 +249,25 @@ jobs: if: steps.gate.outputs.skip == 'false' run: python scripts/build/build_exe.py --portable + - name: Sign portable program files + if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' + uses: azure/artifact-signing-action@v2 + with: + endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }} + signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT }} + certificate-profile-name: ${{ vars.AZURE_SIGNING_PROFILE }} + files-folder: ${{ github.workspace }}\dist\SmartCitizen-Portable-v${{ steps.resolve.outputs.version }} + files-folder-filter: exe + files-folder-recurse: true + file-digest: SHA256 + timestamp-rfc3161: http://timestamp.acs.microsoft.com + timestamp-digest: SHA256 + + - name: Zip signed portable build again + # build_exe.py --portable zipped the folder before it was signed. + if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' + run: python scripts/build/build_exe.py --portable --zip-only + - name: Restore standard installer # Move the stashed installer back into dist/ so both artifacts # sit alongside each other for the verify + publish steps. diff --git a/CLAUDE.md b/CLAUDE.md index 4ea7bce7..c62a4105 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -264,6 +264,8 @@ The branching model above is enforced by GitHub settings, not just convention. D 6. Create the GitHub release and attach `dist/SmartCitizen-{VERSION}-Setup.exe` (installer only; portable onefile exe is retired). 7. Open the next `release/X.Y.(Z+1)` off `main` and bump `VERSION.TXT` — the new integration target. +**Code signing**: `release.yml` signs `SmartCitizen.exe` (with the bundled unp4k/unforge), the installer and the portable `.exe` files through Azure Artifact Signing, then zips the portable folder again (`build_exe.py --portable --zip-only`). It runs only when the `AZURE_SIGNING_ACCOUNT` repository variable is set; the job uses the `release` environment so the Azure federated credential has one subject. The Inno uninstaller is not signed yet. + Discord notification fires via GitHub Actions (`scripts/discord_notify.py`) when `DISCORD_RELEASE_WEBHOOK_URL` secret is set. **Tester pre-release installers**: `.github/workflows/installer-preview.yml` builds a downloadable `SmartCitizen-{VERSION}-Setup.exe` artifact outside the standard release flow. Triggers: (1) `workflow_dispatch` from the Actions tab against any branch, (2) adding the `build-installer` label to a PR (later pushes to the labeled PR rebuild via `synchronize`; remove the label to stop rebuilds). In the integration-branch model this is the *primary* signal that a release is near test sign-off — when the user adds the label, treat the active release branch as approaching ship. Artifact: `smartcitizen-installer-{SHA}`, 30-day retention (testers need lead time vs. CI's 7). The `concurrency` group cancels in-flight builds when a newer commit lands on the same PR / branch. diff --git a/scripts/build/build_exe.py b/scripts/build/build_exe.py index 4e83146a..cdd73806 100644 --- a/scripts/build/build_exe.py +++ b/scripts/build/build_exe.py @@ -8,6 +8,10 @@ python build_exe.py --increment major # Increment major version (0.1.0 -> 1.0.0) python build_exe.py --portable # Build standalone portable variant # (writes to /data/, no registry) + python build_exe.py --portable --zip-only + # Zip the existing dist/ portable folder + # again without rebuilding (release.yml + # runs it after signing the .exe files) # Flags can combine, e.g. `--portable --increment patch`. """ @@ -30,6 +34,7 @@ _args = sys.argv[1:] increment_version = None portable_mode = False +zip_only = False i = 0 while i < len(_args): arg = _args[i] @@ -46,6 +51,10 @@ portable_mode = True i += 1 continue + if arg == '--zip-only': + zip_only = True + i += 1 + continue i += 1 # Get version from VERSION.TXT @@ -97,6 +106,55 @@ def _cleanup_build_info() -> None: except OSError as e: print(f" WARNING: could not delete {build_info_path}: {e}") +# Build executable with PyInstaller. +# The registry / installer build uses a STABLE exe name (SmartCitizen.exe) so +# the installed path and the desktop / Start Menu shortcuts survive version +# updates (#104): a copied or pinned shortcut keeps working because the target +# no longer changes every release. The portable build keeps the versioned name +# so the downloadable zip and its folder identify the version at a glance. +exe_name = ( + f"SmartCitizen-Portable-v{current_version}" if portable_mode else "SmartCitizen" +) + + +def _write_portable_zip() -> None: + """Zip dist// into dist/.zip, files at the top level.""" + zip_name = f"{exe_name}.zip" + zip_path = os.path.join(root_dir, 'dist', zip_name) + onedir_path = os.path.join(root_dir, 'dist', exe_name) + print(f"Packaging portable zip: dist/{zip_name}") + with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED, compresslevel=6) as zf: + for root, _dirs, files in os.walk(onedir_path): + for fname in files: + full = os.path.join(root, fname) + # Inside the zip: files sit at the top level (no extra + # SmartCitizen-Portable-vX.Y.Z/ wrapper). Explorer's + # "Extract All" already creates an enclosing folder + # named after the zip, so wrapping here too used to + # double that prefix on the common extraction path — + # exactly the kind of redundant length that tips deep + # _internal/ paths over MAX_PATH. Recipients who + # manually unzip into an already-open folder instead + # of using Extract All will get the files loose there. + arcname = os.path.relpath(full, onedir_path) + zf.write(full, arcname=arcname) + zip_size_mb = os.path.getsize(zip_path) / (1024 * 1024) + print(f" Portable zip ready: dist/{zip_name} ({zip_size_mb:.1f} MB)") + print() + + +if zip_only: + # Re-package an existing portable build, e.g. after its .exe files + # were signed. No clean, no PyInstaller run. + if not portable_mode: + print("Error: --zip-only needs --portable") + sys.exit(1) + if not os.path.isdir(os.path.join(root_dir, 'dist', exe_name)): + print(f"Error: dist/{exe_name}/ not found; build it first") + sys.exit(1) + _write_portable_zip() + sys.exit(0) + # Clean previous builds print("Cleaning old builds...") for folder in ['build', 'dist']: @@ -109,16 +167,6 @@ def _cleanup_build_info() -> None: print() -# Build executable with PyInstaller. -# The registry / installer build uses a STABLE exe name (SmartCitizen.exe) so -# the installed path and the desktop / Start Menu shortcuts survive version -# updates (#104): a copied or pinned shortcut keeps working because the target -# no longer changes every release. The portable build keeps the versioned name -# so the downloadable zip and its folder identify the version at a glance. -exe_name = ( - f"SmartCitizen-Portable-v{current_version}" if portable_mode else "SmartCitizen" -) - # Write PyInstaller's generated .spec into build/ (ephemeral, wiped each run) # instead of the repo root, so the stable --name never clobbers the # hand-maintained root SmartCitizen.spec or litters the root with per-version @@ -240,28 +288,7 @@ def _cleanup_build_info() -> None: # The standard build doesn't get a zip — Inno Setup is its # distribution artifact, attached separately by release.yml. if portable_mode: - zip_name = f"{exe_name}.zip" - zip_path = os.path.join(root_dir, 'dist', zip_name) - onedir_path = os.path.join(root_dir, 'dist', exe_name) - print(f"Packaging portable zip: dist/{zip_name}") - with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED, compresslevel=6) as zf: - for root, _dirs, files in os.walk(onedir_path): - for fname in files: - full = os.path.join(root, fname) - # Inside the zip: files sit at the top level (no extra - # SmartCitizen-Portable-vX.Y.Z/ wrapper). Explorer's - # "Extract All" already creates an enclosing folder - # named after the zip, so wrapping here too used to - # double that prefix on the common extraction path — - # exactly the kind of redundant length that tips deep - # _internal/ paths over MAX_PATH. Recipients who - # manually unzip into an already-open folder instead - # of using Extract All will get the files loose there. - arcname = os.path.relpath(full, onedir_path) - zf.write(full, arcname=arcname) - zip_size_mb = os.path.getsize(zip_path) / (1024 * 1024) - print(f" Portable zip ready: dist/{zip_name} ({zip_size_mb:.1f} MB)") - print() + _write_portable_zip() except Exception as e: print(f"\nError building --onedir executable: {e}") sys.exit(1) From d1ced32de2924b4eabd8c40078ca0080adfa5aaa Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 13:02:15 +0000 Subject: [PATCH 03/21] Sign the uninstaller, attest release builds, add VirusTotal scan links Inno now signs Setup.exe and the uninstaller itself through scripts/build/sign_file.ps1 when release.yml compiles with /DSIGN, so the separate installer signing step is gone. Every release gets a build provenance attestation, and a VirusTotal scan whose links go into the release notes once the VIRUSTOTAL_API_KEY secret is set. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011hqxFg4JmXaXwTRySyJEQW --- .github/workflows/release.yml | 61 ++++++++++++++++++++++++++--------- CLAUDE.md | 2 +- installer.iss | 8 +++++ scripts/build/sign_file.ps1 | 42 ++++++++++++++++++++++++ 4 files changed, 96 insertions(+), 17 deletions(-) create mode 100644 scripts/build/sign_file.ps1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e10ba79b..b82f7829 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -44,8 +44,10 @@ jobs: # assets) AND `git push origin ` (auto-tag the merge commit on # branch-push trigger). contents: write - # Required for the Azure OIDC login that code signing uses. + # Required for the Azure OIDC login that code signing uses, and for + # the build provenance attestation. id-token: write + attestations: write # Code signing (Azure Artifact Signing) runs only once the # AZURE_SIGNING_ACCOUNT repository variable is set. Until then every # signing step is skipped and the release ships unsigned, as before. @@ -55,6 +57,7 @@ jobs: # AZURE_SIGNING_PROFILE. env: SIGN: ${{ vars.AZURE_SIGNING_ACCOUNT != '' }} + VT_KEY_SET: ${{ secrets.VIRUSTOTAL_API_KEY != '' }} steps: - name: Checkout (at tag, branch HEAD, or dispatch input) @@ -199,32 +202,29 @@ jobs: - name: Compile installer if: steps.gate.outputs.skip == 'false' shell: pwsh + env: + AZURE_SIGNING_ENDPOINT: ${{ vars.AZURE_SIGNING_ENDPOINT }} + AZURE_SIGNING_ACCOUNT: ${{ vars.AZURE_SIGNING_ACCOUNT }} + AZURE_SIGNING_PROFILE: ${{ vars.AZURE_SIGNING_PROFILE }} run: | $iscc = "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" if (-not (Test-Path $iscc)) { Write-Error "ISCC.exe not found at $iscc — Inno Setup install failed?" exit 1 } - & $iscc installer.iss + if ($env:SIGN -eq 'true') { + # Inno signs Setup.exe and the uninstaller itself, so the + # uninstaller it writes into the install folder is signed too. + $signScript = Join-Path $env:GITHUB_WORKSPACE "scripts\build\sign_file.ps1" + & $iscc /DSIGN "/Sazure=pwsh -NoProfile -ExecutionPolicy Bypass -File `"$signScript`" `$f" installer.iss + } else { + & $iscc installer.iss + } if ($LASTEXITCODE -ne 0) { Write-Error "Inno Setup compile failed with exit code $LASTEXITCODE" exit $LASTEXITCODE } - - name: Sign installer - if: steps.gate.outputs.skip == 'false' && env.SIGN == 'true' - uses: azure/artifact-signing-action@v2 - with: - endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }} - signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT }} - certificate-profile-name: ${{ vars.AZURE_SIGNING_PROFILE }} - files-folder: ${{ github.workspace }}\dist - files-folder-filter: exe - files-folder-recurse: false - file-digest: SHA256 - timestamp-rfc3161: http://timestamp.acs.microsoft.com - timestamp-digest: SHA256 - - name: Stash standard installer before portable rebuild # build_exe.py unconditionally rmtrees `dist/` at the start of # every run (including --portable). Without stashing, the @@ -349,6 +349,17 @@ jobs: git tag -a $tag -m "Release $tag (auto-tagged by release.yml on merge to ${{ github.ref_name }})" git push origin $tag + - name: Attest build provenance + # Records that these exact files were built by this workflow from + # this commit. Anyone can check a download with + # `gh attestation verify --repo Osiris-DevWorks/smart-citizen`. + if: steps.gate.outputs.skip == 'false' + uses: actions/attest-build-provenance@v2 + with: + subject-path: | + ${{ steps.artifacts.outputs.installer_path }} + ${{ steps.artifacts.outputs.portable_path }} + - name: Publish GitHub Release if: steps.gate.outputs.skip == 'false' uses: softprops/action-gh-release@v2 @@ -364,6 +375,24 @@ jobs: draft: false prerelease: false + - name: Scan release files on VirusTotal + # Uploads both files to VirusTotal and adds the scan links to the + # end of the release notes, so users can check the results + # themselves. Runs only when the VIRUSTOTAL_API_KEY secret is set + # (a free VirusTotal account's key is enough). A VirusTotal outage + # never fails a release that is already published. + if: steps.gate.outputs.skip == 'false' && env.VT_KEY_SET == 'true' + uses: crazy-max/ghaction-virustotal@v4 + with: + vt_api_key: ${{ secrets.VIRUSTOTAL_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} + update_release_body: true + request_rate: 4 + files: | + ${{ steps.artifacts.outputs.installer_path }} + ${{ steps.artifacts.outputs.portable_path }} + continue-on-error: true + - name: Post Discord notification # Inlined here because the standalone release-notify.yml workflow # — which subscribes to `release: published` — is blocked from diff --git a/CLAUDE.md b/CLAUDE.md index c62a4105..f9880d90 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -264,7 +264,7 @@ The branching model above is enforced by GitHub settings, not just convention. D 6. Create the GitHub release and attach `dist/SmartCitizen-{VERSION}-Setup.exe` (installer only; portable onefile exe is retired). 7. Open the next `release/X.Y.(Z+1)` off `main` and bump `VERSION.TXT` — the new integration target. -**Code signing**: `release.yml` signs `SmartCitizen.exe` (with the bundled unp4k/unforge), the installer and the portable `.exe` files through Azure Artifact Signing, then zips the portable folder again (`build_exe.py --portable --zip-only`). It runs only when the `AZURE_SIGNING_ACCOUNT` repository variable is set; the job uses the `release` environment so the Azure federated credential has one subject. The Inno uninstaller is not signed yet. +**Code signing**: `release.yml` signs `SmartCitizen.exe` (with the bundled unp4k/unforge), the installer and the portable `.exe` files through Azure Artifact Signing, then zips the portable folder again (`build_exe.py --portable --zip-only`). It runs only when the `AZURE_SIGNING_ACCOUNT` repository variable is set; the job uses the `release` environment so the Azure federated credential has one subject. Inno signs the installer and its uninstaller itself through `scripts/build/sign_file.ps1` (`/DSIGN` turns on `SignTool=azure` in `installer.iss`). Every release also gets a build provenance attestation (`gh attestation verify --repo Osiris-DevWorks/smart-citizen`), and, when the `VIRUSTOTAL_API_KEY` secret is set, a VirusTotal scan whose links are added to the release notes. Discord notification fires via GitHub Actions (`scripts/discord_notify.py`) when `DISCORD_RELEASE_WEBHOOK_URL` secret is set. diff --git a/installer.iss b/installer.iss index 0f9a80b6..39a2cc18 100644 --- a/installer.iss +++ b/installer.iss @@ -34,6 +34,14 @@ SetupIconFile=assets\logo.ico ; without this, the WARNING from a WaitForUninstallToFinish timeout goes nowhere ; and a tester reporting "uninstall.exe was deleted" gives us nothing to grep. SetupLogging=yes +; Code signing. release.yml compiles with /DSIGN and /Sazure=... once the +; Azure Artifact Signing account is set up; Inno then signs Setup.exe and the +; uninstaller through scripts\build\sign_file.ps1. Builds without /DSIGN +; (local builds, tester previews) stay unsigned. +#ifdef SIGN +SignTool=azure +SignedUninstaller=yes +#endif [Languages] Name: "english"; MessagesFile: "compiler:Default.isl" diff --git a/scripts/build/sign_file.ps1 b/scripts/build/sign_file.ps1 new file mode 100644 index 00000000..2324cbae --- /dev/null +++ b/scripts/build/sign_file.ps1 @@ -0,0 +1,42 @@ +# Signs one file with Azure Artifact Signing. Inno Setup calls it through +# its SignTool directive for Setup.exe and the uninstaller (release.yml +# passes /DSIGN and /Sazure=... to ISCC), so it runs only in a release +# build where azure/login has already signed in. +# +# Reads the same repository variables as release.yml, passed in as +# environment variables: AZURE_SIGNING_ENDPOINT, AZURE_SIGNING_ACCOUNT, +# AZURE_SIGNING_PROFILE. +# +# Inno hands over temporary files whose names do not end in .exe (the +# uninstaller is signed as a .tmp file), so the file is copied into an +# empty folder as an .exe, signed there by folder and filter, and copied +# back. +param([Parameter(Mandatory = $true)][string]$File) + +$ErrorActionPreference = "Stop" + +if (-not (Get-Module -ListAvailable -Name ArtifactSigning)) { + Install-Module -Name ArtifactSigning -Scope CurrentUser -Force -AllowClobber +} + +$work = Join-Path ([System.IO.Path]::GetTempPath()) ("sc-sign-" + [guid]::NewGuid()) +New-Item -ItemType Directory -Path $work | Out-Null +try { + $copy = Join-Path $work "file.exe" + Copy-Item -LiteralPath $File -Destination $copy + $params = @{ + Endpoint = $env:AZURE_SIGNING_ENDPOINT + CodeSigningAccountName = $env:AZURE_SIGNING_ACCOUNT + CertificateProfileName = $env:AZURE_SIGNING_PROFILE + FilesFolder = $work + FilesFolderFilter = "exe" + FileDigest = "SHA256" + TimestampRfc3161 = "http://timestamp.acs.microsoft.com" + TimestampDigest = "SHA256" + } + Invoke-ArtifactSigning @params + Copy-Item -LiteralPath $copy -Destination $File -Force +} +finally { + Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue +} From 27d44dabd36963ad20a24cc0c733bfb2d9f983a1 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 22:13:07 +0000 Subject: [PATCH 04/21] SCO: follow the monitor Star Citizen is on (#573) The drawer docked to the primary screen and the scan decoder captured it, so with the game on a second monitor the drawer was on the wrong screen and nothing was read. A running overlay now looks for the game window once a second (FindWindowW by class or title, MonitorFromWindow, GetMonitorInfoW: no process handle, memory read, hook or input) and docks the drawer and captures on that screen, falling back to the primary screen when the game is not found. The capture now passes screen-local coordinates to grabWindow, which counts from the screen's own top-left. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011hqxFgfzN2geRf5Nsc5cKP --- CLAUDE.md | 2 +- src/gui/CLAUDE.md | 1 + src/gui/game_screen.py | 133 +++++++++++++++++++ src/gui/sco_overlay.py | 75 +++++++++-- tests/CLAUDE.md | 1 + tests/test_sco_game_screen.py | 239 ++++++++++++++++++++++++++++++++++ 6 files changed, 442 insertions(+), 9 deletions(-) create mode 100644 src/gui/game_screen.py create mode 100644 tests/test_sco_game_screen.py diff --git a/CLAUDE.md b/CLAUDE.md index 4ea7bce7..e521c638 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -223,7 +223,7 @@ Anchor examples already in-tree: `COL_*` constants in `src/gui/string_table_mode | Change the data move after a YES on Setup's OneDrive warning | `installer.iss`, `src/utils/settings.py`, `src/utils/user_ini_manager.py`, `src/main.py`, `src/gui/main_window.py` | `NextButtonClick` (a YES remembers the data folder in `OneDriveMoveFrom` when it is the one being left, a NO forgets it, and leaving the page works out `PendingDataMoveFrom`) and `WriteInstallerChoicesToRegistry` (writes it as `pending_data_move_from`); `AppSettings.migrate_installer_data_move()` (reads and deletes the value, one try, before the channel-layout and cache migrators); `move_owned_user_data()` (only `OWNED_DATA_FOLDERS`, the channel folders and `logs`, merged, never overwriting); `MainWindow._report_installer_data_move()` (a status bar note, or a box when files stayed) (#455) | | Change the toolbar More overflow menu | `src/gui/main_window.py` | `more_menu` block in toolbar setup (restore backup, clear loc/cache, import/export, open loc dir) | | Change the tester Test Plan panel / content | `src/utils/test_plan.py`, `src/gui/test_plan_panel.py` | `TEST_SECTIONS` (per-release checklist), `TestPlanPanel`, `_ensure_test_plan_dock()` / `show_test_plan()` (#144) | -| Change the Smart Citizen Overlay (SCO) | `src/gui/sco_overlay.py`, `src/gui/global_hotkey.py`, `src/utils/mining_signatures.py`, `src/utils/sco_digit_reader.py`, `src/utils/blueprint_log_scanner.py` | `ScoOverlay`, `BlueprintDrawer`, `ScanLabelWindow` (the watched-target alerts, `ALERTS`, and the text size, #523), `SCAN_REGION`, `decode_signature()`, `format_matches()`, `read_signature()` (+ `DIGIT_SAMPLES` reference glyphs), `GameLogTail`, `GlobalHotkey` (the drawer hotkey) and `ScoOverlay.toggle_drawer()`; MainWindow `_toggle_sco_overlay()` / `_on_sco_blueprints_found()` / `_on_sco_hotkey_problem()` | +| Change the Smart Citizen Overlay (SCO) | `src/gui/sco_overlay.py`, `src/gui/global_hotkey.py`, `src/gui/game_screen.py`, `src/utils/mining_signatures.py`, `src/utils/sco_digit_reader.py`, `src/utils/blueprint_log_scanner.py` | `ScoOverlay`, `BlueprintDrawer`, `ScanLabelWindow` (the watched-target alerts, `ALERTS`, and the text size, #523), `SCAN_REGION`, `decode_signature()`, `format_matches()`, `read_signature()` (+ `DIGIT_SAMPLES` reference glyphs), `GameLogTail`, `GlobalHotkey` (the drawer hotkey), `game_screen()` (the drawer and the capture follow the game's monitor, #573) and `ScoOverlay.toggle_drawer()`; MainWindow `_toggle_sco_overlay()` / `_on_sco_blueprints_found()` / `_on_sco_hotkey_problem()` | | Fix an SCO scan misread (teach the digit reader a new glyph) | `scripts/add_sco_sample.py`, `src/utils/sco_digit_samples.py`, `src/utils/sco_digit_reader.py` | Start the app with `SMART_CITIZEN_SCO_SAMPLES=1` so the overlay saves crops, rename the crop from `logs\sco_samples` to the real number (or pass `--digits`), run `add_sco_sample.py --write` (`cut_glyphs()` cuts the digits without matching them), copy the crop to `tests/fixtures/sco/_.png`; `DIGIT_SAMPLES` | | Change the SCO drawer's Minerals / Crafting searches | `src/utils/mining_catalog.py`, `src/gui/sco_overlay.py`, `scripts/generate_enhancements_ini.py` | `parse_mining_compendium()` / `read_compendium()`, `star_system()` (+ `STAR_SYSTEM_LOCATIONS`), `CraftingIndex` / `crafting_index.json` (written by `scan_crafting_blueprints(crafting_index=...)`), `BlueprintDrawer.set_catalog()`, `MainWindow._refresh_sco_catalog()` | | Change the Overlay tab / SCO on-off switches | `src/gui/overlay_tab.py`, `src/utils/settings.py`, `src/gui/main_window.py` | `OverlayTab`, `AppSettings.SCO_OPTION_SETTING` + `get_/set_sco_option()` (the `alert_` switches included), `get_/set_sco_drawer_position()` (`SCO_DRAWER_POSITIONS` → `BlueprintDrawer.set_position()`), `get_/set_sco_label_size()` (`SCO_LABEL_SIZES` → `ScoOverlay.set_label_size()`), `get_/set_sco_drawer_hotkey()` (→ `ScoOverlay.set_drawer_hotkey()`), `MainWindow._apply_sco_options()` | diff --git a/src/gui/CLAUDE.md b/src/gui/CLAUDE.md index 28499d23..16ece822 100644 --- a/src/gui/CLAUDE.md +++ b/src/gui/CLAUDE.md @@ -24,6 +24,7 @@ GUI layer (PyQt6). See the root `CLAUDE.md` for project context and cross-cuttin - `overlay_tab.py` — **Overlay Tab** (3.0.0): Start/Stop Overlay button plus one checkbox per `AppSettings.SCO_OPTION_SETTING` switch (names are `AppSettings.SCO_*` constants; a drawer section's switch is `SCO_DRAWER_SECTION_PREFIX` plus its `sco_overlay.SECTION_ICONS` name) (scan decoder, drawer, its Blueprints / Minerals / Crafting sections indented under it and greyed out while the drawer is off (names starting `drawer_`), mark new blueprints owned from Game.log) and a drawer position picker under the drawer switch (`AppSettings.SCO_DRAWER_POSITIONS`, default middle right, greyed out with the drawer). The scan-sample capture has no switch here (tuning only, see `sco_overlay.py`). #523 added, under the scan decoder switch and greyed out with it, a **Scan text size** picker (`AppSettings.SCO_LABEL_SIZES`, `get_/set_sco_label_size`, default medium) and, under an `overlay.alerts_title` line, one switch per watched-target alert (names `SCO_ALERT_PREFIX` plus a `sco_overlay.ALERTS` name: glow and flash on by default, color, bigger and sound off), and under the drawer's position picker, greyed out with the drawer, a **Drawer hotkey** box (`HotkeyEdit`, saved through `get_/set_sco_drawer_hotkey` as portable text; its hint's example is Alt+8 because Star Citizen's default bindings, `Data/Libs/Config/defaultProfile.xml` in Data.p4k, use every letter, F1 to F12, Home, End, Page Up and Down, Pause, Tab, Space, the arrows and `/`, and Left Ctrl and both Shifts on their own, but never 8, Insert, Delete or Alt on its own, read on LIVE 2026-10-23). Since #523 the tab is in titled boxes like the Config and Enhancements tabs (`_group`, titles `overlay.scan_group`, `drawer_group`, `blueprint_watch_group`): each part's switch first with its hint under it (`_add_switch`), what hangs under it set in (`_indented`), and the alerts and the drawer's sections side by side (`_switch_row`) with their hints as tooltips. `HotkeyEdit` (a `QLineEdit` nothing can be typed or pasted into, with a **Clear** button to its right, `clear_hotkey`, lit only while a hotkey is saved, since every key pressed in the box is taken as the hotkey) records one key combination from the Windows virtual key each press reports (`nativeVirtualKey`, through `global_hotkey.hotkey_text`), not from the character the keyboard layout makes of it: where Ctrl+Alt is AltGr, Ctrl+Alt+O makes a character such as "ó", which a `QKeySequenceEdit` takes for the key (so the combination could not be registered; found in testing), and Shift+1 makes "!". A press with no virtual key (another platform, a press sent by code) falls back to Qt's key. While only modifiers are held it shows them ("Ctrl+Alt+"; Qt leaves a modifier key's own modifier out of its press, so `_MODIFIER_KEYS` adds it back), it takes Tab and every key an app shortcut would (it accepts `ShortcutOverride`), and a combination `windows_hotkey` does not take (a key Windows has no code for, a dead key, a symbol another key also types, or a letter, digit, symbol, Space, Tab or navigation key without Ctrl, Alt or Win) is not saved: the box goes back to the saved one and says why (`refused`). `set_hotkey_problem()` shows why the hotkey is not in use (`global_hotkey.HOTKEY_TAKEN` or `HOTKEY_UNSUPPORTED`, worded by `hotkey_problem_text()` as `overlay.hotkey_taken` or `overlay.hotkey_unsupported`), which `MainWindow._on_sco_hotkey_problem` passes on from `ScoOverlay.hotkey_problem` along with the same text in the status bar. The text size and position pickers are both built by `_picker_row`, and their settings read and saved through `AppSettings._get_choice` / `_set_choice` (a value outside the choices reads, and saves, as the default). Checkboxes save straight to settings and emit `options_changed` → `MainWindow._apply_sco_options` (pushes them to `ScoOverlay.set_options` and starts/stops the live log watcher); the start button emits `overlay_toggled`, which drives the toolbar Overlay button so both go through `_toggle_sco_overlay`, and `set_running()` mirrors the overlay back without re-emitting; `set_option()` likewise mirrors a switch the SCO drawer changed. `refresh_styles()` re-applies the start button's theme colour; `MainWindow.refresh_action_buttons()` calls it on a live theme swap, with the toolbar's Overlay and Tutorial buttons. - `sco_overlay.py` — **Smart Citizen Overlay (SCO)** (3.0.0): always-on-top windows over the game, toggled by the toolbar's **Overlay** button (`MainWindow._toggle_sco_overlay`). `ScanLabelWindow` is click-through and shows the decoded mining signature centred under the scanner readout, always in the ODW colours (`ODW_OVERLAY_COLORS`, see-through at `DRAWER_ALPHA`) whatever the app theme; `BlueprintDrawer` is a stack of three tapered icon tabs (`SectionTabBar`, one per section, icons from `SECTION_ICONS` painted as `QPainterPath`s and kept upright on every edge) docked at one of eight positions (`set_position()`; `drawer_edge()` maps a corner or middle position to its side edge and top/bottom centre to the top or bottom edge, and `SectionTabBar.set_edge()` turns the stack to match). Neighbouring tabs overlap by their taper (`DRAWER_HANDLE_OVERLAP`), like browser tabs; the open section's tab is painted last and near-solid so it sits in front, and `tab_at()` hit-tests front to back so a click in an overlap goes to the tab you see. A tab click (`open_section()`) opens the see-through (`DRAWER_ALPHA`) panel, a `QStackedWidget`, straight to that section, another tab switches section, and the open section's own tab closes it. A section switched off on the Overlay tab hides its tab (closing the drawer if it was open), and with all three off the drawer is hidden (`has_sections()`). The panel takes clicks and focus, but only a search box (`DrawerSearch`, focus on a click only) ever takes the keyboard: every other widget in the panel is `NoFocus`, and a search box ignores a held key's printable repeats. In game F is held to move the mouse, and a tab click gave the Blueprints or Crafting search focus, which then filled with "ffff" (#523). Its sections: a searchable blueprint list with owned checkboxes, a Minerals search (mineral → star system → location; a location finds its minerals) topped by a scan decoder checkbox (the same `scan_decoder` setting as the Overlay tab's: `scan_decoder_toggled` → `MainWindow._on_sco_scan_decoder_toggled` saves it and mirrors the tab via `OverlayTab.set_option`, while `set_options` mirrors the tab back with `set_scan_decoder`) and a **Clear all** button, with a watch checkbox right-aligned in column 1 of each ore's row (only ores `mining_catalog.ore_key` knows, since only those can decode) and of a **Salvage** row that ends the list whatever the catalog holds (`SALVAGE`, the `OTHER_SIGNATURES` key it watches, #523; `_add_watch_box` makes both kinds of box). Ticked ores and salvage go out through `watched_changed` and are saved by MainWindow (`AppSettings.get_/set_sco_watched_minerals`, fed back with `ScoOverlay.set_watched_minerals` on start); when a decode includes one, the label sets off the alerts switched on (`ScanLabelWindow.set_alerts`, from the Overlay tab's `alert_` switches; `set_watched` while it shows). The lasting ones: the glow (a pulsing `QGraphicsDropShadowEffect` in the theme accent, `GLOW_PULSE_MS`, with room for it from `GLOW_MARGIN`, less above (`GLOW_TOP_MARGIN`) so the masked label window never covers the readout), the text in `ALERT_COLOR` (a bright green, not the theme accent, which is dark blue in the Light theme) and the text `ALERT_TEXT_SCALE` times bigger, the label re-sized and re-centred under its anchor (`_place`). When a watched target is first read (`_on_reading`'s `fresh`: a value that was not showing), the label flashes, `FLASH_TOGGLES` swaps of its text and background colours `FLASH_MS` apart that change no size, and `play_alert_sound` starts the sound picked on the Overlay tab (`AppSettings.get_sco_alert_sound`, pushed with `ScoOverlay.set_alert_sound`; the tab's **Preview** calls it too) with winmm's `PlaySoundW`: "Smart Citizen Default" is a two-note chime made in memory (`alert_chime_wav`, `SND_MEMORY | SND_ASYNC`, so nothing waits and no sound file ships), the `voice_` choices are recorded WAVs shipped in `assets/sounds/` (`VOICE_ALERT_SOUNDS`, `voice_sound_path`, `SND_FILENAME`; bundled with the rest of `assets/`), and the others are Windows sound aliases (`WINDOWS_ALERT_SOUNDS`, `SND_ALIAS`, which follow the user's sound scheme); keep both in step with `AppSettings.SCO_ALERT_SOUNDS`; a steady repeat does neither. `set_text_size` (the Overlay tab's **Scan text size**) scales the label's font against the app font (`LABEL_SIZE_SCALE`). The third section is a Crafting search (a mineral lists the items it goes into, an item lists the materials it needs). Crafting rows lead back to their compendium mineral through `_mineral_by_material`, built in `set_catalog()` with `CraftingIndex.material_key_for`, the same link the mineral tooltips use, so CIG's spelling differences (Pressurized Ice / Ice, Aluminum / Aluminium, ...) resolve both ways. Minerals, locations and items carry tooltips (`mineral_tooltip`, `location_tooltip`, `_item_tooltip`). `BlueprintDrawer.retranslate_ui()` sets every fixed text and redraws the list and trees; it runs at construction and from `MainWindow.retranslate_ui()` after a language switch. The guided tour's `overlay` step (`assets/tutorial.json`, after `blueprint_tracker`) points at the Overlay tab's start button. `MainWindow._refresh_sco_catalog` feeds `set_catalog()` from the English base.ini's Mining Compendium and the `crafting_index.json` the generator writes (see `src/utils/mining_catalog.py`), re-reading only when either file changed. The drawer is coloured from the active theme via `OverlayColors.from_theme()` (window colour + title/tagline accents), re-read on every start. `ScoOverlay.set_options(dict)` applies the Overlay tab switches, a missing name taking its `SCO_OPTION_SETTING` default. `format_matches` lists a reading that fits salvage too (12,000 is 3 ROC, 4 FPS or 6 Salvage) with salvage first and the `SURFACE_ONLY` kinds marked `sco.surface_only`: the overlay cannot tell space from a planet, and in space salvage is the only answer (#523). A selected row in the drawer keeps the panel's text colour (`::item:selected { color }`): left to the palette it took `HighlightedText`, near black in the SCLE and ODW themes, on the dark see-through panel. **Drawer hotkey (#523).** `ScoOverlay` owns a `global_hotkey.GlobalHotkey`, given the Overlay tab's combination by `set_drawer_hotkey` and held only while the overlay runs with the drawer showing (`_sync_hotkey`, from `_sync_windows` and `stop`), since Windows keeps a held combination from the game. Each try ends in `hotkey_problem` ("" or why), and a refused combination is not tried again until it changes or the overlay stops (`_hotkey_refused`), so one start reports it once. The hotkey runs `toggle_drawer`: closed, it remembers the window that has focus (`foreground_window`, the game), opens the drawer on the section used last (`BlueprintDrawer.open_last_section`, the first shown one before any) and activates it. That takes focus only when the press came as `WM_HOTKEY` (Windows lets a process that just got its hotkey take the foreground), which frees the mouse over another program. In Star Citizen the press arrives through raw input alone, Windows keeps focus on the game, and the player still holds F to use the mouse in the drawer (found in testing; `_report_focus` logs it at INFO `FOCUS_CHECK_MS` after the open). Taking focus anyway would need `AttachThreadInput` with the game's thread, sent input or a changed Windows setting, which the anti-cheat rule below keeps out. Open, it closes it. Whenever the drawer closes (the hotkey or its own tab, `expanded_changed`) while it still has focus, the remembered window gets focus back (`give_focus_back`), so the mouse returns to the game; a drawer the player has clicked away from leaves focus alone, and a drawer hidden by its switch (`_sync_windows`) forgets the window, since it closed nothing the hotkey opened. `ScoOverlay` owns both plus the capture timer over `SCAN_REGION` (fractions of the primary screen); the reader is pluggable (`SignatureReader`); the default `hud_signature_reader` hands the capture's red, green and blue channels to `src/utils/sco_digit_reader.py` and maps the box back from device to logical pixels. A new reading only replaces the label after `READINGS_TO_CHANGE` identical captures in a row (`_on_reading`; any accepted or steady reading clears the pending candidate, so a misread that comes back later still has to repeat back to back), so a one-frame misread can't flash "Unidentified" over a steady signature. The confirming capture runs at once (`QTimer.singleShot(0, _capture_once)` on a first sighting) instead of waiting for the next tick, so a new signal shows up to a tick sooner; `_capture_once` drops a queued one once the timer has stopped. The label sits `LABEL_GAP` px below the readout, centred under the scanner's pin icon and the number together (the reader's box covers the digits only, so `_handle_found` widens it left by `READOUT_PIN_WIDTH` digit heights, #523), and `_mask_own_label` blacks it out of each capture so its own text is never read. The box comes to logical pixels with each edge rounded outward, so with display scaling the label never sits over the digits' bottom row (it did, and its blackout then made the next reads fail, 1080 px at 125%), and while the label shows, `_steady_anchor` keeps it where it is unless the readout has moved more than `ANCHOR_DEAD_ZONE` digit heights: captures of a still readout put its box a few pixels apart, which made the label twitch on every capture (#523). Each distinct reading's crop is saved once per session to `{logs_dir}/sco_samples/