Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

34.3 KB
Raw Blame
"""Installer release-resolution guards.

The release workflow advances the baked version only after every staged asset
is public. The runtime fallback remains defense in depth for manual edits,
asset removal, interrupted legacy releases, and installer copies from older
branches where a baked version may still point at an unavailable asset.

A missing baked value may therefore degrade to the GitHub Releases API rather
than fail the install. An explicit pin (CUA_DRIVER_RS_VERSION, -Release) is the
opposite case: the user named one version, so a missing asset must stay fatal
rather than silently installing a different one.

Published installer-state agreement is owned by
.github/scripts/validate_release_versions.py; this module tests runtime
resolution and failure semantics.
"""

from __future__ import annotations

import json
import os
import re
import shutil
import subprocess
import textwrap
import threading
from contextlib import contextmanager
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from typing import Iterator

import pytest

# _install-rust.sh only ever runs on macOS and Linux, so the behavioral tests
# below are posix-only. Gating on os.name as well as bash's presence matters:
# on Windows, `bash.exe` is usually the WSL launcher, which resolves via
# shutil.which but cannot execute anything when no distro is installed.
requires_posix_bash = pytest.mark.skipif(
    os.name != "posix" or shutil.which("bash") is None,
    reason="requires a posix host with bash",
)
POWERSHELL = shutil.which("pwsh") or shutil.which("powershell")
requires_powershell = pytest.mark.skipif(
    POWERSHELL is None,
    reason="requires PowerShell",
)

REPO_ROOT = Path(__file__).resolve().parents[4]
SCRIPTS = REPO_ROOT / "libs/cua-driver/scripts"

WINDOWS_INSTALLER = SCRIPTS / "install.ps1"
UNIX_INSTALLER = SCRIPTS / "_install-rust.sh"


def _windows_source() -> str:
    return WINDOWS_INSTALLER.read_text(encoding="utf-8-sig")


def _unix_source() -> str:
    return UNIX_INSTALLER.read_text(encoding="utf-8")


# ---------- Windows -------------------------------------------------------


def _extract_powershell_function(source: str, name: str) -> str:
    start = source.index(f"function {name}")
    next_function = source.find("\nfunction ", start + 1)
    assert next_function != -1, f"could not locate the end of PowerShell function {name}"
    return source[start:next_function].strip()


def _run_powershell(tmp_path: Path, body: str) -> subprocess.CompletedProcess[str]:
    script = tmp_path / "installer-harness.ps1"
    script.write_text(
        "$ErrorActionPreference = 'Stop'\n" + body,
        encoding="utf-8",
    )
    return subprocess.run(
        [str(POWERSHELL), "-NoProfile", "-NonInteractive", "-File", str(script)],
        capture_output=True,
        text=True,
        check=True,
    )


@contextmanager
def _powershell_download_server(
    scenario: str,
) -> Iterator[tuple[str, list[str]]]:
    requests: list[str] = []

    class Handler(BaseHTTPRequestHandler):
        def do_GET(self) -> None:
            requests.append(self.path)
            if scenario == "network":
                self.connection.close()
                return
            status = {
                "missing": 404,
                "server": 503,
                "auth": 401,
            }[scenario]
            self.send_response(status)
            self.end_headers()

        def log_message(self, _format: str, *args: object) -> None:
            pass

    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
    thread = threading.Thread(target=server.serve_forever, daemon=True)
    thread.start()
    try:
        host, port = server.server_address
        yield f"http://{host}:{port}", requests
    finally:
        server.shutdown()
        server.server_close()
        thread.join()


def test_windows_installer_falls_back_when_baked_release_is_unpublished() -> None:
    source = _windows_source()

    # The baked branch must record its provenance for the download path to key on.
    assert "$Script:CuaDriverRsVersionSource = 'baked'" in source

    fallback = source.index(
        "if ($download.Missing -and $Script:CuaDriverRsVersionSource -eq 'baked')"
    )
    # The recovery must consult the API and retry the download, in that order.
    api_call = source.index("$apiVersion = Get-LatestVersionFromApi", fallback)
    retry = source.index(
        "$download = Get-ReleaseZip $resolvedVersion $archLabel $destDir", api_call
    )
    fatal = source.index("if ($download.Missing) {", retry)
    assert fallback < api_call < retry < fatal


def test_windows_installer_does_not_fall_back_for_an_explicit_version_pin() -> None:
    source = _windows_source()

    assert "$Script:CuaDriverRsVersionSource = 'env'" in source
    assert "$Script:CuaDriverRsVersionSource = 'release-arg'" in source
    # Exactly one fallback site, and it is gated on the baked provenance, so
    # neither pin route can reach it.
    assert source.count("$Script:CuaDriverRsVersionSource -eq 'baked'") == 1


def test_windows_installer_adopts_the_version_that_actually_downloaded() -> None:
    """A fallback changes the install path and the cursor-theme capability check.

    Get-ReleaseAsset therefore returns the resolved version, and the caller must
    re-derive $versionedDir from it before staging anything.
    """
    source = _windows_source()

    assert "return @{ StageDir = $stageDir; Version = $version }" in source

    adopt = source.index("if ($asset.Version -ne $version) {")
    assert source.index("$version = $asset.Version", adopt) < source.index(
        "$versionedDir = Join-Path $ReleasesDir", adopt
    )
    # The retarget has to precede the directory creation that consumes it.
    assert adopt < source.index("New-Item -ItemType Directory -Force -Path $versionedDir", adopt)


def test_windows_installer_rechecks_an_already_installed_fallback_before_copy() -> None:
    """A running fallback binary is locked on Windows and must not be overwritten."""
    source = _windows_source()
    adopt = source.index("if ($asset.Version -ne $version) {")
    recheck = source.index(
        "if (Test-Path -LiteralPath (Join-Path $versionedDir $BinaryName))", adopt
    )
    copy = source.index(
        "Copy-Item -LiteralPath (Join-Path $stageDir $BinaryName)", recheck
    )
    assert adopt < recheck < copy


def test_windows_api_resolver_avoids_the_automatic_matches_variable() -> None:
    """$matches is clobbered by every `-match`; a local of that name is a trap."""
    source = _windows_source()
    body = source[
        source.index("function Get-LatestVersionFromApi") : source.index("function Resolve-Version")
    ]
    code = "\n".join(line for line in body.splitlines() if not line.lstrip().startswith("#"))

    assert "$releaseMatches" in code
    # Word-boundary match so $releaseMatches does not count as a hit.
    assert not re.search(r"\$matches\b", code)


@requires_powershell
@pytest.mark.parametrize(
    ("scenario", "missing", "attempts", "has_error"),
    [
        ("missing", True, 1, False),
        ("server", False, 3, True),
        ("network", False, 3, True),
        ("auth", False, 1, True),
    ],
)
def test_windows_download_classifies_and_retries_failures_behaviorally(
    tmp_path: Path,
    scenario: str,
    missing: bool,
    attempts: int,
    has_error: bool,
) -> None:
    source = _windows_source()
    with _powershell_download_server(scenario) as (base_url, requests):
        functions = "\n\n".join(
            _extract_powershell_function(source, name)
            for name in (
                "Get-HttpStatusCode",
                "Test-TransientDownloadFailure",
                "Get-ReleaseZip",
            )
        )
        functions = functions.replace(
            "https://github.com/$Repo/releases/download/",
            f"{base_url}/",
        ).replace(
            "Start-Sleep -Seconds $delaySeconds",
            "$null = $delaySeconds",
        )
        result = _run_powershell(
            tmp_path,
            f"""
$Repo = 'trycua/cua'
$TagPrefix = 'cua-driver-rs-v'
function Write-Step {{ param([string]$Message) }}
function Write-WarningStep {{ param([string]$Message) }}

{functions}

$download = Get-ReleaseZip '1.2.3' 'windows-x86_64' '{tmp_path.as_posix()}'
[pscustomobject]@{{
    Missing = [bool]$download.Missing
    Attempts = [int]$download.Attempts
    HasError = [bool]$download.ErrorMessage
}} | ConvertTo-Json -Compress
""",
        )
    observed = json.loads(result.stdout)
    assert observed == {
        "Missing": missing,
        "Attempts": attempts,
        "HasError": has_error,
    }
    if scenario == "network":
        # Invoke-WebRequest has its own transport retry on a dropped socket;
        # the installer-level Attempts count must still remain bounded at three.
        assert len(requests) >= attempts
    else:
        assert len(requests) == attempts


@requires_powershell
def test_windows_api_resolver_filters_drafts_but_accepts_stable_prereleases(
    tmp_path: Path,
) -> None:
    source = _windows_source()
    functions = "\n\n".join(
        _extract_powershell_function(source, name)
        for name in ("Test-WithdrawnVersion", "Get-GitHubApiHeaders", "Get-LatestVersionFromApi")
    )
    result = _run_powershell(
        tmp_path,
        f"""
$Repo = 'trycua/cua'
$TagPrefix = 'cua-driver-rs-v'
function Write-Step {{ param([string]$Message) }}
function Write-WarningStep {{ param([string]$Message) }}
function Invoke-RestMethod {{
    param(
        [string]$Uri,
        [hashtable]$Headers,
        [switch]$UseBasicParsing
    )
    @(
        [pscustomobject]@{{ tag_name = 'cua-driver-rs-v9.0.0'; draft = $true; prerelease = $false }}
        [pscustomobject]@{{ tag_name = 'cua-driver-rs-v1.20.3'; draft = $false; prerelease = $true }}
        [pscustomobject]@{{ tag_name = 'cua-driver-rs-v8.0.0-rc.1'; draft = $false; prerelease = $false }}
    )
}}

{functions}

Get-LatestVersionFromApi
""",
    )
    assert result.stdout.strip() == "1.20.3"


# ---------- Unix ----------------------------------------------------------


def _extract_shell_function(source: str, name: str) -> str:
    match = re.search(rf"^{re.escape(name)}\(\) \{{.*?^\}}", source, re.MULTILINE | re.DOTALL)
    assert match, f"could not locate shell function {name}()"
    return match.group(0)


def _run_resolver(
    tmp_path: Path, releases_json: str, epilogue: str, strict: bool, withdrawn: str = ""
) -> str:
    """Runs the real resolver function with curl shadowed by a shell function.

    A function shim beats a PATH shim here: it needs no exec bit and no PATH
    entry, so the harness behaves the same whether the test host is Linux,
    macOS, or a Windows checkout whose drive letters would otherwise collide
    with the ':' PATH separator.
    """
    fixture = tmp_path / "releases.json"
    fixture.write_text(releases_json, encoding="utf-8")

    script = tmp_path / "run.sh"
    script.write_text(
        textwrap.dedent("""\
            set -{flags}uo pipefail
            REPO="trycua/cua"
            TAG_PREFIX="cua-driver-rs-v"
            curl() {{ cat "{fixture}"; }}
            CUA_DRIVER_RS_WITHDRAWN_VERSIONS="{withdrawn}"
            {is_withdrawn}
            {github_api_curl}
            {published_versions}
            {resolver}
            {epilogue}
            """).format(
            # `set -euo pipefail` when the resolver is expected to succeed;
            # `set -uo pipefail` when the test asserts on its non-zero return,
            # which -e would otherwise turn into an abort before the assertion.
            flags="e" if strict else "",
            fixture=fixture.as_posix(),
            withdrawn=withdrawn,
            is_withdrawn=_extract_shell_function(_unix_source(), "is_withdrawn_version"),
            github_api_curl=_extract_shell_function(_unix_source(), "github_api_curl"),
            published_versions=_extract_shell_function(
                _unix_source(), "extract_published_release_versions"
            ),
            resolver=_extract_shell_function(_unix_source(), "resolve_latest_version_from_api"),
            epilogue=epilogue,
        ),
        encoding="utf-8",
    )

    result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True, check=True)
    return result.stdout.strip()


@requires_posix_bash
def test_unix_api_resolver_picks_the_highest_semver(tmp_path: Path) -> None:
    """Behavioral check on the grep/sed/sort pipeline, with curl stubbed.

    0.9.1 sorts above 0.12.6 lexicographically, so this fails if the numeric
    sort keys regress. The unrelated cua-driver-v* and lume-v* tags must be
    filtered out entirely.
    """
    resolved = _run_resolver(
        tmp_path,
        """
        [
          {
            "tag_name": "cua-driver-v9.9.9",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v0.9.1",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v0.12.6",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v0.11.0",
            "draft": false
          },
          {
            "tag_name": "lume-v0.4.0",
            "draft": false
          }
        ]
        """,
        epilogue="resolve_latest_version_from_api",
        strict=True,
    )
    assert resolved == "0.12.6"


@requires_posix_bash
def test_unix_api_resolver_fails_when_no_tag_matches(tmp_path: Path) -> None:
    """A miss must return non-zero so the caller can report it, not print junk."""
    resolved = _run_resolver(
        tmp_path,
        '[\n  {\n    "tag_name": "lume-v0.4.0",\n    "draft": false\n  }\n]',
        epilogue="if resolve_latest_version_from_api; then echo RESOLVED; else echo NOMATCH; fi",
        strict=False,
    )
    assert resolved == "NOMATCH"


@requires_posix_bash
def test_unix_api_resolver_rejects_prerelease_and_malformed_tags(tmp_path: Path) -> None:
    resolved = _run_resolver(
        tmp_path,
        """
        [
          {
            "tag_name": "cua-driver-rs-v9.0.0-rc.1",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v8.0.0+build.1",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v7.0.0.1",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v6.0",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v5.4.3",
            "draft": false
          }
        ]
        """,
        epilogue="resolve_latest_version_from_api",
        strict=True,
    )
    assert resolved == "5.4.3"


@requires_posix_bash
def test_unix_api_resolver_rejects_drafts_but_accepts_stable_prereleases(
    tmp_path: Path,
) -> None:
    resolved = _run_resolver(
        tmp_path,
        """
        [
          {
            "tag_name": "cua-driver-rs-v9.0.0",
            "draft": true,
            "prerelease": false
          },
          {
            "tag_name": "cua-driver-rs-v1.20.3",
            "draft": false,
            "prerelease": true
          }
        ]
        """,
        epilogue="resolve_latest_version_from_api",
        strict=True,
    )
    assert resolved == "1.20.3"


def _release_page(tags: list[str], filler: int) -> str:
    rows = [f"lume-v1.0.{i}" for i in range(filler)] + tags
    return json.dumps([{"tag_name": tag, "draft": False, "prerelease": True} for tag in rows], indent=2)


def _run_paged_resolver(tmp_path: Path, pages: list[str]) -> tuple[str, list[str]]:
    """Run the real resolver against numbered release pages served by a curl shim."""
    calls = tmp_path / "calls"
    cases = []
    for number, page in enumerate(pages, start=1):
        page_file = tmp_path / f"page-{number}.json"
        page_file.write_text(page, encoding="utf-8")
        cases.append(f'*"&page={number}") cat "{page_file.as_posix()}" ;;')
    script = tmp_path / "run-pages.sh"
    script.write_text(
        textwrap.dedent(
            """\
            set -euo pipefail
            REPO="trycua/cua"
            TAG_PREFIX="cua-driver-rs-v"
            GH_TOKEN="test-token"
            curl() {{
                printf '%s\\n' "$*" >> "{calls}"
                case "$*" in
                    {cases}
                    *) return 99 ;;
                esac
            }}
            {github_api_curl}
            {published_versions}
            {resolver}
            resolve_latest_version_from_api
            """
        ).format(
            calls=calls.as_posix(),
            cases="\n                    ".join(cases),
            github_api_curl=_extract_shell_function(_unix_source(), "github_api_curl"),
            published_versions=_extract_shell_function(
                _unix_source(), "extract_published_release_versions"
            ),
            resolver=_extract_shell_function(_unix_source(), "resolve_latest_version_from_api"),
        ),
        encoding="utf-8",
    )
    result = subprocess.run(
        ["bash", script.as_posix()], capture_output=True, text=True, check=True
    )
    return result.stdout, calls.read_text(encoding="utf-8").splitlines()


@requires_posix_bash
def test_unix_api_resolver_paginates_full_pages_and_sends_token_header(
    tmp_path: Path,
) -> None:
    """The repo interleaves lume/Python/Swift releases with these.

    A short page can contain no cua-driver-rs-v* tag at all and make a healthy
    repo look empty, which would turn the fallback into a dead end.
    """
    resolved, calls = _run_paged_resolver(
        tmp_path,
        [_release_page([], filler=100), _release_page(["cua-driver-rs-v1.20.3"], filler=0)],
    )

    assert resolved == "1.20.3"
    assert len(calls) == 2
    assert all("per_page=100&" in line for line in calls)
    assert all("Authorization: Bearer test-token" in line for line in calls)


@requires_posix_bash
def test_unix_api_resolver_stops_after_ten_full_pages(tmp_path: Path) -> None:
    pages = [_release_page(["cua-driver-rs-v1.0.0"], filler=99)]
    pages += [_release_page([], filler=100) for _ in range(9)]
    pages.append(_release_page(["cua-driver-rs-v9.9.9"], filler=99))

    resolved, calls = _run_paged_resolver(tmp_path, pages)

    assert resolved == "1.0.0"
    assert len(calls) == 10
    assert not any("&page=11" in line for line in calls)


def _run_download(tmp_path: Path, scenario: str, token_env: str = "") -> tuple[int, list[str], str]:
    """Run the real download helper with deterministic HTTP/curl behavior."""
    calls = tmp_path / "download-calls"
    script = tmp_path / "run-download.sh"
    script.write_text(
        textwrap.dedent(
            f"""\
            set -uo pipefail
            REPO="trycua/cua"
            TAG_PREFIX="cua-driver-rs-v"
            TAG="cua-driver-rs-v1.2.3"
            LABEL="linux-x86_64"
            TMP_DIR="{tmp_path.as_posix()}"
            {token_env}
            log() {{ printf '==> %s\\n' "$*"; }}
            err() {{ printf 'error: %s\\n' "$*" >&2; }}
            sleep() {{ :; }}
            curl() {{
                printf '%s\\n' "$*" >> "{calls.as_posix()}"
                local output="" previous="" arg
                for arg in "$@"; do
                    if [[ "$previous" == "-o" ]]; then output="$arg"; fi
                    previous="$arg"
                done
                case "{scenario}" in
                    success)
                        printf 'archive' > "$output"
                        printf '200'
                        return 0
                        ;;
                    missing)
                        printf '404'
                        return 0
                        ;;
                    transient)
                        printf '503'
                        return 0
                        ;;
                    auth)
                        printf '401'
                        return 0
                        ;;
                    network)
                        printf '000'
                        return 7
                        ;;
                esac
            }}
            {_extract_shell_function(_unix_source(), "release_tarball_name")}
            {_extract_shell_function(_unix_source(), "download_release_tarball")}
            download_release_tarball "1.2.3"
            """
        ),
        encoding="utf-8",
    )
    result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True)
    call_lines = calls.read_text(encoding="utf-8").splitlines()
    return result.returncode, call_lines, result.stderr


@requires_posix_bash
def test_unix_download_reports_confirmed_404_without_retry(tmp_path: Path) -> None:
    returncode, calls, _ = _run_download(tmp_path, "missing")
    assert returncode == 44
    assert len(calls) == 1


@requires_posix_bash
@pytest.mark.parametrize("scenario", ["transient", "network"])
def test_unix_download_retries_transient_failure_without_fallback(
    tmp_path: Path, scenario: str
) -> None:
    returncode, calls, stderr = _run_download(tmp_path, scenario)
    assert returncode == 1
    assert len(calls) == 3
    assert "refusing to fall back to an older release" in stderr


@requires_posix_bash
def test_unix_download_does_not_retry_auth_failure_or_fallback(tmp_path: Path) -> None:
    returncode, calls, stderr = _run_download(tmp_path, "auth")
    assert returncode == 1
    assert len(calls) == 1
    assert "HTTP 401" in stderr
    assert "refusing to fall back to an older release" in stderr


@requires_posix_bash
def test_unix_public_asset_download_does_not_forward_api_token(tmp_path: Path) -> None:
    returncode, calls, stderr = _run_download(tmp_path, "success", 'GITHUB_TOKEN="api-token"')
    assert returncode == 0
    assert len(calls) == 1
    assert "Authorization:" not in calls[0]
    assert "api-token" not in stderr


@requires_posix_bash
@pytest.mark.parametrize(
    ("value", "expected"),
    [
        ("1.2.3", "cua-driver-rs-v1.2.3"),
        ("cua-driver-rs-v1.2.3", "cua-driver-rs-v1.2.3"),
        (
            "1.2.4-nightly.20260812.42",
            "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
        ),
        (
            "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
            "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
        ),
    ],
)
def test_unix_explicit_pin_selects_an_exact_stable_or_nightly_tag(
    tmp_path: Path, value: str, expected: str
) -> None:
    script = tmp_path / "resolve-pin.sh"
    script.write_text(
        textwrap.dedent(
            f"""\
            set -euo pipefail
            TAG_PREFIX="cua-driver-rs-v"
            NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
            {_extract_shell_function(_unix_source(), "resolve_explicit_release_tag")}
            resolve_explicit_release_tag "{value}"
            """
        ),
        encoding="utf-8",
    )
    result = subprocess.run(
        ["bash", script.as_posix()], capture_output=True, text=True, check=True
    )
    assert result.stdout == expected


@requires_posix_bash
@pytest.mark.parametrize(
    "value",
    [
        "nightly-cua-driver-rs-v1.2.4-rc.1",
        "cua-driver-rs-v1.2.4-nightly.20260812.42",
        "nightly-lume-v1.2.4-nightly.20260812.42",
        "1.2",
    ],
)
def test_unix_explicit_pin_rejects_cross_channel_and_malformed_tags(
    tmp_path: Path, value: str
) -> None:
    script = tmp_path / "resolve-bad-pin.sh"
    script.write_text(
        textwrap.dedent(
            f"""\
            set -euo pipefail
            TAG_PREFIX="cua-driver-rs-v"
            NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
            {_extract_shell_function(_unix_source(), "resolve_explicit_release_tag")}
            resolve_explicit_release_tag "{value}"
            """
        ),
        encoding="utf-8",
    )
    result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True)
    assert result.returncode != 0


def _run_fallback_flow(
    tmp_path: Path, *, version_source: str, download_statuses: list[int]
) -> tuple[subprocess.CompletedProcess[str], list[str]]:
    """Execute the installer's real post-download fallback control flow."""
    source = _unix_source()
    start = source.index("DOWNLOAD_STATUS=0\n")
    end = source.index('\nlog "extracting"', start)
    flow = source[start:end]
    statuses = " ".join(str(status) for status in download_statuses)
    calls = tmp_path / "flow-calls"
    script = tmp_path / "run-flow.sh"
    script.write_text(
        textwrap.dedent(
            f"""\
            set -uo pipefail
            VERSION_SOURCE="{version_source}"
            VERSION="1.2.3"
            TAG_PREFIX="cua-driver-rs-v"
            TAG="${{TAG_PREFIX}}${{VERSION}}"
            LABEL="linux-x86_64"
            REPO="trycua/cua"
            DOWNLOAD_RESULTS=({statuses})
            DOWNLOAD_INDEX=0
            err() {{ printf 'error: %s\\n' "$*" >&2; }}
            download_release_tarball() {{
                printf 'download:%s\\n' "$1" >> "{calls.as_posix()}"
                local result="${{DOWNLOAD_RESULTS[$DOWNLOAD_INDEX]}}"
                DOWNLOAD_INDEX=$((DOWNLOAD_INDEX + 1))
                return "$result"
            }}
            resolve_latest_version_from_api() {{
                printf 'api\\n' >> "{calls.as_posix()}"
                printf '1.2.2'
            }}
            {_extract_shell_function(source, "release_tarball_name")}
            {flow}
            printf 'resolved:%s:%s:%s\\n' "$VERSION" "$TAG" "$TARBALL"
            """
        ),
        encoding="utf-8",
    )
    result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True)
    call_lines = calls.read_text(encoding="utf-8").splitlines()
    return result, call_lines


@requires_posix_bash
def test_unix_baked_404_falls_back_and_adopts_downloaded_version(tmp_path: Path) -> None:
    result, calls = _run_fallback_flow(
        tmp_path, version_source="baked", download_statuses=[44, 0]
    )
    assert result.returncode == 0
    assert calls == ["download:1.2.3", "api", "download:1.2.2"]
    # Every release-derived name, including the archive, follows the adopted version.
    assert result.stdout == (
        "resolved:1.2.2:cua-driver-rs-v1.2.2:cua-driver-rs-1.2.2-linux-x86_64-binary.tar.gz\n"
    )
    assert "temporary publish lag" in result.stderr


@requires_posix_bash
@pytest.mark.parametrize(
    ("version_source", "download_status"),
    [("pin", 44), ("pin", 1), ("baked", 1)],
)
def test_unix_non_fallback_download_failure_makes_zero_api_calls(
    tmp_path: Path, version_source: str, download_status: int
) -> None:
    result, calls = _run_fallback_flow(
        tmp_path, version_source=version_source, download_statuses=[download_status]
    )
    assert result.returncode == 1
    assert calls == ["download:1.2.3"]


# ---------- Withdrawn releases ----------------------------------------------
#
# A withdrawn release (for example 0.28.3, whose macOS app was published
# unsigned) stays published for audit but must never be selected. The
# installers cannot read repository files at runtime, so each carries a baked
# list that validate_release_versions.py keeps equal to
# .github/release-state/cua-driver-rs-withdrawn-versions.


@requires_posix_bash
def test_unix_api_resolver_skips_withdrawn_releases(tmp_path: Path) -> None:
    releases = """
        [
          {
            "tag_name": "cua-driver-rs-v0.28.3",
            "draft": false
          },
          {
            "tag_name": "cua-driver-rs-v0.28.2",
            "draft": false
          }
        ]
        """
    assert (
        _run_resolver(tmp_path, releases, "resolve_latest_version_from_api", strict=True)
        == "0.28.3"
    )
    assert (
        _run_resolver(
            tmp_path,
            releases,
            "resolve_latest_version_from_api",
            strict=True,
            withdrawn="0.28.1 0.28.3",
        )
        == "0.28.2"
    )


@requires_posix_bash
def test_unix_api_resolver_fails_when_only_withdrawn_releases_remain(tmp_path: Path) -> None:
    resolved = _run_resolver(
        tmp_path,
        '[\n  {\n    "tag_name": "cua-driver-rs-v0.28.3",\n    "draft": false\n  }\n]',
        epilogue="if resolve_latest_version_from_api; then echo RESOLVED; else echo NOMATCH; fi",
        strict=False,
        withdrawn="0.28.3",
    )
    assert resolved == "NOMATCH"


def _run_resolution_flow(
    tmp_path: Path, *, pin: str = "", baked: str = "", withdrawn: str = ""
) -> tuple[subprocess.CompletedProcess[str], list[str]]:
    """Execute the installer's real release-tag resolution block."""
    source = _unix_source()
    start = source.index('if [[ -n "${CUA_DRIVER_RS_VERSION:-}" ]]; then\n    VERSION_SOURCE="pin"')
    end = source.index('if [[ "$TAG" == "$NIGHTLY_TAG_PREFIX"* ]]; then', start)
    calls = tmp_path / "resolution-calls"
    calls.write_text("", encoding="utf-8")
    script = tmp_path / "run-resolution.sh"
    script.write_text(
        textwrap.dedent(
            f"""\
            set -uo pipefail
            REPO="trycua/cua"
            TAG_PREFIX="cua-driver-rs-v"
            NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
            SELECTED_CHANNEL="stable"
            SELECTED_TAG_PREFIX="$TAG_PREFIX"
            CUA_DRIVER_RS_VERSION="{pin}"
            CUA_DRIVER_RS_BAKED_VERSION="{baked}"
            CUA_DRIVER_RS_WITHDRAWN_VERSIONS="{withdrawn}"
            log() {{ printf 'log: %s\\n' "$*" >&2; }}
            err() {{ printf 'error: %s\\n' "$*" >&2; }}
            resolve_latest_version_from_api() {{
                printf 'api\\n' >> "{calls.as_posix()}"
                printf '0.28.2'
            }}
            """
        )
        + _extract_shell_function(source, "is_withdrawn_version")
        + "\n"
        + _extract_shell_function(source, "resolve_explicit_release_tag")
        + "\n"
        + source[start:end]
        + '\nprintf \'resolved:%s:%s\\n\' "$VERSION_SOURCE" "$TAG"\n',
        encoding="utf-8",
    )
    result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True)
    return result, calls.read_text(encoding="utf-8").splitlines()


@requires_posix_bash
def test_unix_installer_refuses_an_explicit_withdrawn_pin(tmp_path: Path) -> None:
    result, calls = _run_resolution_flow(
        tmp_path, pin="0.28.3", baked="0.28.2", withdrawn="0.28.3"
    )
    assert result.returncode == 1
    assert "cua-driver-rs-v0.28.3 was withdrawn and must not be installed" in result.stderr
    assert "resolved:" not in result.stdout
    assert calls == []


@requires_posix_bash
def test_unix_installer_resolves_past_a_withdrawn_baked_version(tmp_path: Path) -> None:
    result, calls = _run_resolution_flow(tmp_path, baked="0.28.3", withdrawn="0.28.3")
    assert result.returncode == 0, result.stderr
    assert result.stdout == "resolved:api:cua-driver-rs-v0.28.2\n"
    assert "baked release cua-driver-rs-v0.28.3 was withdrawn" in result.stderr
    assert calls == ["api"]


@requires_posix_bash
def test_unix_installer_uses_an_eligible_baked_version_without_api(tmp_path: Path) -> None:
    result, calls = _run_resolution_flow(tmp_path, baked="0.28.2", withdrawn="0.28.3")
    assert result.returncode == 0, result.stderr
    assert result.stdout == "resolved:baked:cua-driver-rs-v0.28.2\n"
    assert calls == []


def test_unix_installer_fails_closed_on_macos_signature_failure() -> None:
    """A bad signature never triggers an automatic downgrade to another release."""
    source = _unix_source()
    failure = source.index(
        'err "downloaded CuaDriver.app failed signature verification; the installed app was not changed"'
    )
    exit_line = source.index("exit 1", failure)
    between = source[failure:exit_line]
    assert "resolve_latest_version_from_api" not in between
    assert "download_release_tarball" not in between
    assert "CUA_DRIVER_RS_VERSION=<x.y.z>" in between


def test_windows_installer_rejects_withdrawn_pins_and_baked_versions() -> None:
    source = _windows_source()
    resolve = source[
        source.index("function Resolve-Version") : source.index("# ---------- Download + extract")
    ]
    env_pin = resolve.index("$Script:CuaDriverRsVersionSource = 'env'")
    release_pin = resolve.index("$Script:CuaDriverRsVersionSource = 'release-arg'")
    assert resolve.index("Assert-NotWithdrawnPin $release") < env_pin
    assert resolve.index("Assert-NotWithdrawnPin $release", env_pin) < release_pin
    baked = resolve.index("$Script:CuaDriverRsVersionSource = 'baked'")
    assert resolve.index("if (Test-WithdrawnVersion $v) {") < baked

    api = source[
        source.index("function Get-LatestVersionFromApi") : source.index(
            "function Resolve-SelectedChannel"
        )
    ]
    assert "Test-WithdrawnVersion $_.tag_name.Substring($selectedPrefix.Length)" in api


@requires_powershell
def test_windows_api_resolver_skips_withdrawn_releases(tmp_path: Path) -> None:
    source = _windows_source()
    functions = "\n\n".join(
        _extract_powershell_function(source, name)
        for name in ("Test-WithdrawnVersion", "Get-GitHubApiHeaders", "Get-LatestVersionFromApi")
    )
    result = _run_powershell(
        tmp_path,
        f"""
$Repo = 'trycua/cua'
$TagPrefix = 'cua-driver-rs-v'
$Script:CuaDriverRsWithdrawnVersions = @('0.28.3')
function Write-Step {{ param([string]$Message) }}
function Write-WarningStep {{ param([string]$Message) }}
function Invoke-RestMethod {{
    param([string]$Uri, [hashtable]$Headers, [switch]$UseBasicParsing)
    @(
        [pscustomobject]@{{ tag_name = 'cua-driver-rs-v0.28.3'; draft = $false; prerelease = $true }}
        [pscustomobject]@{{ tag_name = 'cua-driver-rs-v0.28.2'; draft = $false; prerelease = $true }}
    )
}}

{functions}

Get-LatestVersionFromApi
""",
    )
    assert result.stdout.strip() == "0.28.2"


@requires_powershell
def test_windows_installer_refuses_an_explicit_withdrawn_pin(tmp_path: Path) -> None:
    source = _windows_source()
    functions = "\n\n".join(
        _extract_powershell_function(source, name)
        for name in ("Test-WithdrawnVersion", "Assert-NotWithdrawnPin")
    )
    script = tmp_path / "withdrawn-pin.ps1"
    script.write_text(
        f"""
$Script:CuaDriverRsWithdrawnVersions = @('0.28.3')
function Write-ErrorStep {{ param([string]$Message) [Console]::Error.WriteLine($Message) }}
{functions}
Assert-NotWithdrawnPin @{{ Version = '0.28.2'; Tag = 'cua-driver-rs-v0.28.2' }}
Write-Output 'eligible'
Assert-NotWithdrawnPin @{{ Version = '0.28.3'; Tag = 'cua-driver-rs-v0.28.3' }}
Write-Output 'unreachable'
""",
        encoding="utf-8",
    )
    result = subprocess.run(
        [str(POWERSHELL), "-NoProfile", "-NonInteractive", "-File", str(script)],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 1
    assert result.stdout.split() == ["eligible"]
    assert "cua-driver-rs-v0.28.3 was withdrawn" in result.stderr